Важные замечания

Пользовательская инструкция доступна по ссылке https://wiki.hr-link.ru/bin/view/Main/Administrator-/Spravochniki-/Pol%D1%8Czovatel%D1%8Cskie-spravochniki/
В примерах используется массовая синхронизация пользовательских справочников, но управление справочниками доступно и через единичные методы https://docs.myhrlink.ru/public/openapi/hr-link/#tag/directoriesCustomStructures
У администратора в UI HRlink есть возможность изменять загруженные справочники и их элементы. Изменения, которые внесет администратор в синхронизированных справочниках, будут потеряны при следующей выгрузке справочников через АПИ.
В примерах используется аутентификация через мастер-токен, но допускается использовать User-Api-Token (токен администратора/кадровика, который получается под аватаркой в UI)
В заголовках имперсонализации используются внешние идентификаторы пользователя, но допускается использовать другой доступный идентификатор (HRlink, из указанной системы и пр.).

Postman collection

Выгрузить пользовательские справочники в HRlink

Создать задачу массовой синхронизации данных

Переменная

Описание

Обязательность

tenantHost

Хост тенанта, на который должен быть выполнен запрос

да

clientId

ИД клиента HRlink

да

clientUserExternalId

Внешний ИД пользователя клиента

да

Название пользовательского справочника

-

да

Описание пользовательского справочника

-

нет

Внешний ИД пользовательского справочника

-

да

colourSchema

Цвет ярлыка и текста в нем. Для отображения на UI HRlink.

Значение ограничено комбинациями:

{ "background": "#E7E9ED", "text": "#576175" }, 
{ "background": "#E1E7FE", "text": "#242365" }, 
{ "background": "#D7F8FF", "text": "#1F4B56" }, 
{ "background": "#F6E9FD", "text": "#591E58" }, 
{ "background": "#FDEDD8", "text": "#753B2D" }, 
{ "background": "#E3FCE9", "text": "#254B32" }, 
{ "background": "#EFFCD0", "text": "#455622" }, 
{ "background": "#FCFACA", "text": "#6B4E22" }, 
{ "background": "#F7E4E0", "text": "#661C1B" }

да

Название элемента пользовательского справочника

-

да

Внешний идентификатор элемента пользовательского справочника

-

да

Внешний идентификатор руководителя элемента пользовательского справочника

-

нет

Внешний идентификатор родительского относительно текущего элемента пользовательского справочника

-

нет

curl --location 'https://{{tenantHost}}/api/v1/clients/{{clientId}}/bulkDataSyncTasks' \
--header 'Impersonated-User-Id: {{clientUserExternalId}}' \
--header 'Impersonated-User-Id-Type: EXTERNAL_ID' \
--data '{
    "type": "CUSTOM_STRUCTURES",
    "data": [
        {
            "name": "{{Название пользовательского справочника}}",
            "description": "{{Описание пользовательского справочника}}",
            "externalId": "{{Внешний ИД пользовательского справочника}}",
            "colourSchema": {
                "background": "#E7E9ED",
                "text": "#576175"
            },
            "elements": [
                {
                    "name": "{{Название элемента пользовательского справочника}}",
                    "externalId": "{{Внешний идентификатор элемента пользовательского справочника}}",
                    "headManagerExternalId": "{{Внешний идентификатор руководителя элемента пользовательского справочника}}",
                    "parentExternalId": "{{Внешний идентификатор родительского относительно текущего элемента пользовательского справочника}}"
                }
            ]
        }
    ]
}'

Пример ответа

{
    "result": true,
    "bulkDataSyncTask": {
        "id": "{{ИД задачи массовой синхронизации данных}}"
    }
}

Получить статус задачи массовой синхронизации

curl --location 'https://{{tenantHost}}/api/v1/clients/{{clientId}}/bulkDataSyncTasks/{{ИД задачи массовой синхронизации данных}}' \
--header 'Impersonated-User-Id: {{clientUserExternalId}}' \
--header 'Impersonated-User-Id-Type: EXTERNAL_ID' \
--header 'Master-Api-Token: {{masterApiToken}}'

Пример ответа

{
    "result": true,
    "bulkDataSyncTask": {
        "id": "{{ИД задачи массовой синхронизации данных}}",
        "type": "CUSTOM_STRUCTURES",
        "state": "FINISHED",
        "counts": {
            "total": 1,
            "succeeded": 1,
            "failed": 0
        },
        "createdDate": "{{Дата создания задачи массовой синхронизации данных}}",
        "data": [
            {
                "id": "{{ИД справочника в HRlink}}",
                "externalId": "{{ИД справочника во внешней системе}}",
                "state": "SYNCED",
                "result": "UPDATED"
            }
        ]
    }
}

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

Переменная	Описание	Обязательность
tenantHost	Хост тенанта, на который должен быть выполнен запрос	да
clientId	ИД клиента HRlink	да
clientUserExternalId	Внешний ИД пользователя клиента	да
employeeExternalId	Внешний ИД сотрудника пользователя клиента	да
legalEntityExternalId	Внешний ИД юрлица клиента	нет
elementExternalId	Внешний ИД элемента пользовательского справочника	да
customStructureExternalId	Внешний ИД пользовательского справочника	да
parentExternalId	Внешний ИД элемента пользовательского справочника, который будет являться родительским текущему элементу	нет
headManagerExternalId	Внешний ИД сотрудника-руководителя, который будет являться руководителем элемента (для использования в связанной функциональности)	нет

curl --location 'https://{{tenantHost}}/api/v1/clients/{{clientId}}/bulkDataSyncTasks' \
--header 'Impersonated-User-Id: {{clientUserExternalId}}' \
--header 'Impersonated-User-Id-Type: EXTERNAL_ID' \
--data '{
    "type": "EMPLOYEE_CUSTOM_STRUCTURE_ELEMENTS",
    "data": [
        {
            "externalId": "{{employeeExternalId}}",
            "legalEntityExternalId": "{{legalEntityExternalId}}",
            "customStructureElements": [
                {
                    "externalId": "{{elementExternalId}}",
                    "customStructureExternalId": "{{customStructureExternalId}}"
                }
            ]
        }
    ]
}'

Пример ответа

{
    "result": true,
    "bulkDataSyncTask": {
        "id": "{{ИД задачи массовой синхронизации данных}}"
    }
}

Получить статус задачи массовой синхронизации

curl --location 'https://{{tenantHost}}/api/v1/clients/{{clientId}}/bulkDataSyncTasks/{{ИД задачи массовой синхронизации данных}}' \
--header 'Impersonated-User-Id: {{clientUserExternalId}}' \
--header 'Impersonated-User-Id-Type: EXTERNAL_ID' \
--header 'Master-Api-Token: {{masterApiToken}}'

Пример ответа

{
    "result": true,
    "bulkDataSyncTask": {
        "id": "{{ИД задачи массовой синхронизации данных}}",
        "type": "CUSTOM_STRUCTURES",
        "state": "FINISHED",
        "counts": {
            "total": 1,
            "succeeded": 1,
            "failed": 0
        },
        "createdDate": "{{Дата создания задачи массовой синхронизации данных}}",
        "data": [
            {
                "id": "{{employeeId}}",
                "externalId": "{{employeeExternalId}}",
                "state": "SYNCED",
                "result": "UPDATED"
            }
        ]
    }
}