Пользовательские справочники и признаки сотрудника

Пользовательский справочник помогает классифицировать сотрудников. Например, по региону, проекту или рабочей группе. Есть возможность создать справочник «Площадка» с элементами «Москва» и «Казань». Когда кадровик выбирает «Москва» для сотрудника, этот элемент становится его признаком.

У сотрудника может быть несколько признаков, но не больше одного элемента из каждого справочника. Например, «Площадка: Москва» и «Проект: Альфа» совместимы, а «Площадка: Москва» и «Площадка: Казань» одновременно — нет. Признаки относятся к конкретному месту работы (employee); у одного пользователя HRlink может быть несколько таких записей. Подробнее — Модель данных.

Как пользоваться справочниками в интерфейсе

Администратор или пользователь с правами настройщика открывает Справочники → Пользовательские справочники, создаёт справочник, задаёт название, описание и цвет.
Внутри справочника он добавляет элементы. У элемента можно выбрать родителя из того же справочника и руководителя. Так получается иерархия: например, «Россия → Москва».
В карточке сотрудника кадровик открывает Место работы → Редактировать признаки, выбирает нужные элементы и сохраняет изменения.
В реестрах сотрудников, документов и заявлений кадровик использует фильтр Признак сотрудника. При выборе нескольких признаков интерфейс показывает записи, где у сотрудника есть хотя бы один выбранный признак.

Созданные справочники и их элементы можно редактировать; удаление на данный момент не поддерживается. Снять признак с сотрудника можно — сам элемент при этом остаётся в справочнике. Пошаговые действия со скриншотами приведены в пользовательской инструкции.

Что подготовить для API

Данные	Как использовать
`tenantHost` и `clientId`	Адрес тенанта и UUID клиента; `clientId` можно получить методом Текущий пользователь
Токен	Примеры ниже используют User-Api-Token пользователя с нужными правами
ID сотрудника	Для единичного назначения нужен UUID `employeeId`; для массового — внешний ID сотрудника, а не пользователя клиента
Внешние ID справочников и элементов	Стабильные ключи из вашей системы, которые не меняются при переименовании
Руководители и родители элементов	Сначала создайте сотрудников-руководителей и родительские элементы, на которые будете ссылаться

Замените значения в фигурных скобках своими данными. Если используете мастер-токен, замените заголовок User-Api-Token во всех запросах на:

Master-Api-Token: {masterApiToken}
Impersonated-User-Id: {clientUserExternalId}
Impersonated-User-Id-Type: EXTERNAL_ID

Здесь clientUserExternalId идентифицирует пользователя, от имени которого выполняется запрос. Он не задаёт сотрудника, которому назначают признак.

Права

Операция	Права
Создать справочник или элемент единичным методом	`CUSTOM_STRUCTURES_CREATE` на уровне пользователя клиента
Изменить справочник или элемент	`CUSTOM_STRUCTURES_UPDATE` на уровне пользователя клиента
Прочитать справочники для управления	`CUSTOM_STRUCTURES`; передайте `permissionContext=CUSTOM_STRUCTURES`
Создать массовую задачу	`BULK_DATA_SYNC_TASKS_CREATE`; для `CUSTOM_STRUCTURES` дополнительно нужны `CUSTOM_STRUCTURES_CREATE` и `CUSTOM_STRUCTURES_UPDATE`
Прочитать статус массовой задачи	`BULK_DATA_SYNC_TASKS`
Изменить признаки сотрудника	`EMPLOYEES_UPDATE`, доступ к его юрлицу и отделу; при изменении набора нужен доступ ко всем текущим и новым элементам

Токен не расширяет права пользователя. Настройка доступных кадровику элементов справочников — отдельная операция от назначения признаков сотруднику. Общие правила приведены в разделе Авторизация.

Выберите способ управления

Задача интеграции	Способ
Загрузить или обновить несколько справочников с элементами	Создать задачу синхронизации, тип `CUSTOM_STRUCTURES`
Назначить признаки нескольким сотрудникам	Тот же метод синхронизации, тип `EMPLOYEE_CUSTOM_STRUCTURE_ELEMENTS`
Создать или отредактировать один справочник либо элемент	Единичные методы
Заменить или снять признаки одного сотрудника	Заменить элементы сотрудника

Определите, где ведутся данные: в вашей системе или в HRlink. Если справочником управляет интеграция, следующая загрузка может перезаписать ручные изменения названия, цвета, родителя или руководителя у переданных объектов. Согласуйте с администраторами порядок таких изменений.

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

id — UUID объекта в HRlink; externalId — ключ объекта в вашей системе.
Внешний ID справочника уникален в пределах клиента. Имя справочника также должно быть уникальным в клиенте.
Внешний ID элемента должен быть уникальным внутри справочника. Для массового назначения используйте ключи элементов, уникальные среди всех справочников клиента, например site-moscow и project-alpha.
В массовом назначении передавайте пару externalId элемента и customStructureExternalId справочника. Если внешние ID элементов уже повторяются в разных справочниках, используйте единичное назначение с UUID элемента: текущая реализация массового назначения может выбрать неверный элемент даже при указанном customStructureExternalId.
Для сотрудника передавайте его externalId и legalEntityExternalId, если внешний ID сотрудника неоднозначен в пределах клиента. Не подставляйте вместо него внешний ID пользователя клиента.

Шаг 1. Загрузить справочник и элементы

Вызовите Создать задачу синхронизации с типом CUSTOM_STRUCTURES. Пример создаёт новый справочник «Площадка» с двумя элементами:

curl -X POST "https://{tenantHost}/api/v1/clients/{clientId}/bulkDataSyncTasks" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "User-Api-Token: {token}" \
  -d '{
    "type": "CUSTOM_STRUCTURES",
    "data": [
      {
        "name": "Площадка",
        "description": "Место работы сотрудника",
        "externalId": "sites",
        "colourSchema": {"background": "#E7E9ED", "text": "#576175"},
        "version": 0,
        "elements": [
          {"name": "Москва", "externalId": "site-moscow", "version": 0},
          {"name": "Казань", "externalId": "site-kazan", "version": 0}
        ]
      }
    ]
  }'

version: 0 в этом примере предназначена для новых объектов. Перед обновлением существующих справочника и элементов прочитайте их методом Получить справочник по внешнему ID и передайте актуальные version каждого объекта. Не повторяйте первичный запрос с нулевыми версиями как универсальное обновление.

Поле	Правило
`name` справочника	Непустое название, до 150 символов
`description`	Необязательное описание, до 1000 символов
`externalId`	Обязателен для справочника и каждого элемента в массовой синхронизации
`colourSchema`	Пара цветов фона и текста из разрешённых комбинаций; произвольные HEX-цвета не подходят
`elements[].parentExternalId`	Внешний ID родительского элемента того же справочника; для корня пропустите поле
`elements[].headManagerExternalId`	Внешний ID сотрудника-руководителя; для элемента без руководителя пропустите поле

Для создания иерархии используйте единичное создание элемента: сначала создайте корень, затем дочерние элементы со ссылкой на него. При массовом создании дочернего элемента включайте уже существующего родителя в тот же elements, с его актуальными полями и version. Одной ссылки parentExternalId на родителя вне массива недостаточно: текущая реализация может создать новый элемент без родителя. Элемент не может быть своим родителем; перенос под собственного потомка создаёт недопустимый цикл.

Массовая загрузка создаёт объекты с новыми внешними ID и обновляет объекты с известными внешними ID. Она не удаляет справочники и элементы, которых нет в запросе. elements: [], elements: null или отсутствие elements также не очищают справочник.

Цвета

Используйте согласованную пару из таблицы. Сервер проверяет сочетание фона и текста по своей конфигурации.

Фон `background`	Текст `text`
`#E7E9ED`	`#576175`
`#E1E7FE`	`#242365`
`#D7F8FF`	`#1F4B56`
`#F6E9FD`	`#591E58`
`#FDEDD8`	`#753B2D`
`#E3FCE9`	`#254B32`
`#EFFCD0`	`#455622`
`#FCFACA`	`#6B4E22`
`#F7E4E0`	`#661C1B`

Шаг 2. Дождаться результата

Ответ на создание задачи содержит её UUID:

{
  "result": true,
  "bulkDataSyncTask": {"id": "91a2a5fb-2f74-4cf1-9f3c-e3327f4bc3e0"}
}

Этот ответ подтверждает создание задачи, а не завершение загрузки. Вызовите Статус задачи синхронизации, подставив полученный UUID:

curl "https://{tenantHost}/api/v1/clients/{clientId}/bulkDataSyncTasks/{taskId}" \
  -H "Accept: application/json" \
  -H "User-Api-Token: {token}"

Пока bulkDataSyncTask.state равен QUEUED или IN_PROGRESS, повторяйте чтение статуса с паузой.
После FINISHED проверьте counts.failed и каждую запись data[]. Для нужных объектов ожидайте state: "SYNCED"; одного статуса задачи недостаточно.
При ошибке изучите data[].errorCode, errorMessage и errorData. При FAILED проверьте также bulkDataSyncTask.errorMessage.
Перед назначением признаков перечитайте справочник по внешнему ID и убедитесь, что нужные элементы существуют.

Не считайте пакет единой транзакцией: часть записей может завершиться успешно, а часть — с ошибками. Исправьте ошибочные записи, перечитайте версии уже существующих объектов и только затем повторите загрузку.

Шаг 3. Назначить признаки сотрудникам

Создайте отдельную задачу синхронизации с типом EMPLOYEE_CUSTOM_STRUCTURE_ELEMENTS. В примере employee-001 и company-001 — внешние ID уже созданных сотрудника и юрлица:

curl -X POST "https://{tenantHost}/api/v1/clients/{clientId}/bulkDataSyncTasks" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "User-Api-Token: {token}" \
  -d '{
    "type": "EMPLOYEE_CUSTOM_STRUCTURE_ELEMENTS",
    "data": [
      {
        "externalId": "employee-001",
        "legalEntityExternalId": "company-001",
        "customStructureElements": [
          {"externalId": "site-moscow", "customStructureExternalId": "sites"}
        ]
      }
    ]
  }'

customStructureElements заменяет весь набор признаков указанного сотрудника. Если у сотрудника уже был признак из справочника «Проект», приведённый запрос снимет его. Чтобы сохранить проект, включите его элемент в тот же массив вместе с site-moscow.

Содержимое запроса	Результат
Один или несколько элементов	У сотрудника остаётся ровно переданный набор, по одному элементу из каждого справочника
`customStructureElements: []`	HRlink снимает все признаки этого сотрудника
Сотрудника нет в `data`	Его признаки не меняются
Нет обязательного `customStructureElements`	Некорректный запрос; для снятия признаков передайте явный пустой массив

В стандартной конфигурации в одной задаче допустимо до 500 сотрудников. Каждую пару externalId и legalEntityExternalId указывайте один раз. Если внешний ID сотрудника неоднозначен, обязательно задайте внешний ID юрлица. Запускайте задачи последовательно и проверяйте результат каждой. В статусе этой задачи поле type должно содержать EMPLOYEE_CUSTOM_STRUCTURE_ELEMENTS.

Для проверки назначений вызовите Получить сотрудника. В ответе найдите нужное место работы в employee.legalEntities[] и проверьте его customStructureElements.

Единичные операции

Действие	Метод
Получить список справочников	Получить справочники
Получить справочник с элементами и версиями	По UUID или по внешнему ID
Создать справочник	Создать справочник
Обновить справочник	По UUID или по внешнему ID
Создать элемент	В справочнике по UUID или по внешнему ID справочника
Обновить элемент	По UUID или по внешним ID
Получить данные известных элементов	Получить элементы, с обязательным массивом UUID `ids` и подходящим `permissionContext`
Заменить признаки сотрудника	Заменить элементы сотрудника

Создание и редактирование

Для создания справочника передайте объект с name, description, externalId и colourSchema, без оболочки type/data из массовой задачи. Обязательны name и colourSchema; внешний ID задайте сразу, если планируете синхронизацию.

Для создания элемента передайте name и externalId. Родителя можно указать через parentId или parentExternalId, руководителя — через headManagerId или headManagerExternalId. Выбирайте один способ идентификации для каждой ссылки. UUID и внешний ID руководителя относятся к сотруднику.

Перед изменением получите справочник с элементами:

curl "https://{tenantHost}/api/v1/clients/{clientId}/customStructuresByExternalId/sites?permissionContext=CUSTOM_STRUCTURES" \
  -H "Accept: application/json" \
  -H "User-Api-Token: {token}"

Используйте customStructure.version для изменения справочника и customStructure.elements[].version для изменения выбранного элемента. Передавайте полное нужное состояние редактируемого объекта, включая сохраняемые описание, внешний ID, родителя и руководителя. Пропуск необязательного поля не стоит использовать как команду «оставить прежнее значение».

Если версия устарела, перечитайте объект и согласуйте изменения с новыми данными. Не убирайте version ради обхода конфликта: так можно перезаписать чужое изменение.

Заменить или снять признаки одного сотрудника

Метод Заменить элементы сотрудника принимает UUID сотрудника в пути и полный набор элементов в теле. В спецификации он назван «Добавить сотруднику элементы пользовательского справочника», но фактически выполняет замену.

curl -X PUT "https://{tenantHost}/api/v1/clients/{clientId}/employees/{employeeId}/customStructureElements" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "User-Api-Token: {token}" \
  -d '{
    "customStructureElements": [
      {"id": "0f4b4b6e-68c0-4aa9-a195-2f8f8786b111"}
    ]
  }'

Замените UUID из примера на ID нужного элемента из ответа Получить справочник. Чтобы снять один признак, передайте все остальные. Чтобы снять все, отправьте тем же методом:

{"customStructureElements": []}

Ошибки и контроль результата

Ситуация	Что проверить или изменить
Нет доступа	Проверьте пользователя токена, права операции, доступ к юрлицу, отделу и текущим/новым элементам
Справочник или элемент не найден	Проверьте клиента и пару внешних ID; дождитесь завершения загрузки справочников
Совпадают внешние ID элементов в разных справочниках	Назначайте по UUID единичным методом либо обеспечьте уникальность внешних ID в клиенте
Два элемента одного справочника у сотрудника	Оставьте один элемент этого справочника
Конфликт версии	Прочитайте объект заново и передайте его текущую `version`
Недопустимая цветовая схема (`13.5454`)	Используйте разрешённую пару; при отличиях конфигурации ориентируйтесь на `permittedHexColourCodes` в данных ошибки
После назначения исчез другой признак	В запросе был неполный набор; восстановите полный набор с учётом актуальных данных сотрудника
Элемент остался после исключения из загрузки	Это ожидаемо: синхронизация справочников не выполняет удаление

После загрузки проверьте состав и версии справочника, затем назначения у сотрудников и отображение признаков в интерфейсе. При повторной синхронизации убедитесь, что интеграция сохраняет признаки из других справочников, которыми она не управляет.

Как пользоваться справочниками в интерфейсе​

Что подготовить для API​

Права​

Выберите способ управления​

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

Шаг 1. Загрузить справочник и элементы​

Цвета​

Шаг 2. Дождаться результата​

Шаг 3. Назначить признаки сотрудникам​

Единичные операции​

Создание и редактирование​

Заменить или снять признаки одного сотрудника​

Ошибки и контроль результата​