Идентификаторы

В API HRlink сущности имеют два типа идентификаторов: внутренний id и внешний externalId.

Когда использовать

Используйте эту страницу, когда решаете, хранить ли внутренние UUID HRlink во внешней системе, как искать сущности по идентификатору из 1С или SAP и как безопасно обновлять данные через PUT.

Что нужно заранее

Что нужно	Где получить
`tenantHost`	Адрес тенанта HRlink
`clientId`	Текущий пользователь
Токен	Аутентификация
Стабильный внешний идентификатор	В системе-источнике: 1С, SAP, Bitrix24 или другой HR-системе

Типовые сценарии

Найти сущность по externalId

Возьмите внешний идентификатор из системы-источника.
Вызовите метод чтения по externalId, например Получить сотрудника по externalId.
Если сервер вернул 404, создайте сущность или обработайте отсутствие как нормальный результат синхронизации.

Обновить сущность без потери данных

Получите текущее состояние сущности.
Сохраните version и все поля, которые поддерживает PUT-метод.
Измените нужные поля.
Отправьте PUT со всем набором полей.

Ограничения и ошибки

Файлы не поддерживают externalId.
Если в ссылке на связанную сущность передать и id, и externalId, сервер использует id.
PUT в HRlink заменяет весь объект: не переданные поля сервер сохранит как null.
PATCH-методов для частичного обновления нет.

id — внутренний идентификатор

Формат: UUID (xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)
Генерируется HRlink при создании сущности
Неизменяемый
Используется во всех запросах к API

externalId — внешний идентификатор

Формат: произвольная строка
Задаётся интегратором при создании сущности
Связывает запись с внешней системой (1С, SAP, Bitrix24 и др.)
Позволяет не хранить отдельный маппинг UUID: вы обращаетесь к сущностям HRlink по идентификатору из вашей системы

Рекомендация

Для единообразия используйте externalId для всех сущностей: если вы задали externalId для сотрудника, задавайте его и для юрлиц, должностей и отделов.

Поддержка externalId

Почти все сущности API поддерживают externalId, кроме файлов. Для большинства сущностей есть отдельные эндпоинты — через них вы получаете и обновляете объект по внешнему идентификатору без знания внутреннего UUID.

Правила приоритета

При создании

Интегратор передаёт externalId в теле запроса при создании сущности
Если externalId не передан — сущность создаётся без внешнего идентификатора

При обновлении (PUT)

PUT-методы в HRlink работают как полная замена всех полей объекта, а не только externalId. Подробности — в разделе Поведение PUT: полная замена полей.

В запросах с обоими идентификаторами

Некоторые операции (например, создание документа) позволяют указать оба типа идентификаторов одновременно:

{
  "headManagerId": "146e54ac-1111-2222-3333-444455556666",
  "headManagerExternalId": "91979976",
  "employeeIds": ["6c75c66b-1111-2222-3333-444455556666"],
  "employeeExternalIds": ["91979977"]
}

Приоритет id над externalId при ссылке на сущность

Если для ссылки на связанную сущность переданы оба варианта (например, headManagerId и headManagerExternalId), сервер использует id, а externalId игнорирует. Передавайте только один вариант.

Паттерн интеграции на externalId

Типовой сценарий интеграции через externalId:

При синхронизации — задавайте externalId из вашей системы (табельный номер, ID в 1С и т.п.)
При обращении к API — получайте и обновляйте сущности по внешнему идентификатору вместо внутреннего id
Не храните маппинг UUID — через externalId вы обращаетесь к сущностям напрямую

Пример: проверка существования сотрудника

curl
PowerShell
HTTP

curl -X GET "https://{tenantHost}/api/v1/clients/{clientId}/employees/EMP-42/externalId" \
  -H "Accept: application/json" \
  -H "User-Api-Token: {token}"

Invoke-RestMethod `
  -Uri "https://{tenantHost}/api/v1/clients/{clientId}/employees/EMP-42/externalId" `
  -Method GET `
  -Headers @{
    "Accept"         = "application/json"
    "User-Api-Token" = "{token}"
  }

GET /api/v1/clients/{clientId}/employees/EMP-42/externalId HTTP/1.1
Host: {tenantHost}
Accept: application/json
User-Api-Token: {token}

Если сотрудник с externalId: "EMP-42" существует, сервер вернёт его полные данные. Если нет, вернётся 404 Not Found.

Пример: обновление сотрудника по externalId

Чтобы изменить только отдел, сначала получите текущего сотрудника через GET, измените нужное поле и отправьте PUT со всем набором полей. Иначе остальные поля затрутся в null — см. Поведение PUT.

curl
PowerShell
HTTP

curl -X PUT "https://{tenantHost}/api/v5/clients/{clientId}/employeesByExternalId/EMP-42" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "User-Api-Token: {token}" \
  -d '{
    "version": 3,
    "externalId": "EMP-42",
    "departmentExternalId": "DEP-10",
    "positionExternalId": "POS-05",
    "number": "42",
    "isMainWorkplace": true,
    "tags": ["engineering"]
  }'

$body = @{
  version              = 3
  externalId           = "EMP-42"
  departmentExternalId = "DEP-10"
  positionExternalId   = "POS-05"
  number               = "42"
  isMainWorkplace      = $true
  tags                 = @("engineering")
} | ConvertTo-Json

Invoke-RestMethod `
  -Uri "https://{tenantHost}/api/v5/clients/{clientId}/employeesByExternalId/EMP-42" `
  -Method PUT `
  -Headers @{
    "Accept"         = "application/json"
    "User-Api-Token" = "{token}"
  } `
  -ContentType "application/json" `
  -Body $body

PUT /api/v5/clients/{clientId}/employeesByExternalId/EMP-42 HTTP/1.1
Host: {tenantHost}
Accept: application/json
Content-Type: application/json
User-Api-Token: {token}

{
  "version": 3,
  "externalId": "EMP-42",
  "departmentExternalId": "DEP-10",
  "positionExternalId": "POS-05",
  "number": "42",
  "isMainWorkplace": true,
  "tags": ["engineering"]
}

Не забывайте про version

При обновлении всегда передавайте актуальное значение version — это механизм оптимистической блокировки.

Поведение PUT: полная замена полей

PUT-методы HRlink устроены как полная замена всех полей объекта, а не частичное обновление. Любой атрибут, который вы не передали в теле запроса, сервер интерпретирует как null и сохраняет это значение.

Это касается не только externalId, а всех обновляемых полей: departmentId, positionId, tags, fullTimeEquivalent, number и других.

Типичная ошибка

Вы хотите обновить только отдел сотрудника и передаёте в PUT тело { "version": 3, "departmentExternalId": "DEP-20" }. Результат: отдел обновится, но externalId, positionExternalId, tags, number и другие поля, которых вы не передали, будут затёрты в null. Следующий синк или чтение по externalId сломается.

Правильный паттерн: GET → изменить → PUT

Получить текущее состояние сотрудника через Получить сотрудника по externalId.
Взять из ответа все поля, которые поддерживает PUT-метод.
Изменить нужные.
Отправить весь набор в PUT.

PATCH-методов (частичного обновления) в API HRlink нет. Схема GET → изменить → PUT — единственный безопасный способ обновить одно поле, не затерев остальные.

Немного исключений

Для отдельных полей в некоторых методах действует исключение «null = не трогать» — например, для roleIds в обновлении сотрудника. Исключения оставлены для обратной совместимости. На такое поведение нельзя полагаться как на правило: оно точечное, не отражено в OpenAPI и различается между методами и версиями.

Безопасный подход — всегда передавать в PUT полный набор полей объекта, даже если часть из них не меняется.

Формат externalId

Формат externalId — произвольная строка. Примеры из реальных интеграций:

Внешняя система	Пример externalId	Комментарий
1С	`"000000042"`	Табельный номер
SAP	`"91979974"`	ID сотрудника в SAP
Битрикс24	`"2bd6c38f-1740-11ef-bba5-00155d282200"`	UUID из Битрикс
Кастомная	`"SAFONOVA_NV"`	Строковый код

Когда использовать​

Что нужно заранее​

Типовые сценарии​

Найти сущность по externalId​

Обновить сущность без потери данных​

Ограничения и ошибки​

id — внутренний идентификатор​

externalId — внешний идентификатор​

Поддержка externalId​

Правила приоритета​

При создании​

При обновлении (PUT)​

В запросах с обоими идентификаторами​

Паттерн интеграции на externalId​

Пример: проверка существования сотрудника​

Пример: обновление сотрудника по externalId​

Поведение PUT: полная замена полей​

Правильный паттерн: GET → изменить → PUT​

Немного исключений​

Формат externalId​