Как читать API Reference

API Reference содержит точное описание методов HRlink: параметры, тело запроса, ответы, коды ошибок и operationId. Используйте его как спецификацию, а сценарии и concept-страницы — как объяснение порядка действий.

Где смотреть доступ

Если метод требует токен, передайте его в заголовке запроса:

Способ доступа	Заголовок	Когда использовать
User-Api-Token	User-Api-Token: {token}	ручная проверка API или интеграция от имени одного пользователя
Мастер-токен	Authorization: Bearer {integratorToken}	серверная интеграция, которая выполняет запросы от имени разных пользователей

При работе через мастер-токенMaster-Api-Token Мастер-токен для M2M-интеграций. Позволяет выполнять запросы от имени любого пользователя системы через заголовки Impersonated-User-Id. Получается через ESA с помощью сертификата интегратора. также передайте заголовки для работы от имени пользователя: Impersonated-User-Id и Impersonated-User-Id-Type.

Если API возвращает 401 или 403, проверьте ошибки аутентификации и права доступа.

Где взять clientId

clientId — идентификатор пространства клиента внутри тенантаTenant Экземпляр системы HRlink на отдельном домене (например, company.hr-link.ru). Внутри одного тенанта может быть несколько пространств клиентов. HRlink. Большинство методов содержит clientId в пути.

Получите clientId через Текущий пользователь: в ответе найдите currentUser.clientUsers[].client.id.

Если пользователь относится к нескольким пространствам клиента, выберите тот clientId, с которым должна работать интеграция.

Как читать страницу метода

На странице метода смотрите эти блоки:

Блок	Что проверять
Path parameters	значения в URL, например clientId, documentId, employeeId
Query parameters	фильтры, пагинация, флаги вроде includeDeactivated
Request body	JSON-тело запроса и обязательные поля
Responses	успешный ответ и варианты ошибок
Schemas	структура вложенных объектов и enum-значения

Если метод возвращает список, проверьте параметры limit и offset. В API HRlink используется пагинация через смещение, а не page и size.

Как пользоваться operationId

operationId нужен для поиска метода в OpenAPI и для стабильных ссылок из документации. В ручных гайдах названия методов пишутся по-русски, но ссылка ведёт на страницу с operationId.

Пример:

[Создать группу и отправить на подписание](/public/api/hrlink/document-group-create-and-send-to-signing)

В этом примере documentGroupCreateAndSendToSigning превращается в slug document-group-create-and-send-to-signing.

Где искать сценарий

Если вы ещё не знаете точный метод, начните не с API Reference, а со страницы сущности или гайда:

Задача	Где начать
Отправить документ	Документы или Отправка документов на подписание
Отследить статус подписания	Документы или Отслеживание статуса подписания
Синхронизировать сотрудников	Синхронизация сотрудников
Создать заявление	Заявления или Работа с заявлениями
Загрузить или скачать файл	Работа с файлами

Как разбирать ошибки

При ошибке смотрите не только HTTP-статус, но и поля ответа:

Поле	Что означает
errorCode	код для программной обработки ошибки
errorId	идентификатор ошибки для обращения в поддержку
errorMessage	текстовое описание причины
errorData	дополнительные данные, если сервер их вернул

Типовые причины и решения собраны на странице Коды ошибок.