Часто задаваемые вопросы
Аутентификация
Как получить мастер-токен, если система установлена давно?
Обратитесь к клиентскому менеджеру или в Службу заботы. Вам потребуется сгенерировать пару ключей и сертификат, после чего отправить сертификат в поддержку. Подробнее — в разделе Мастер-токен.
Какой тип токена лучше для продакшна?
Мастер-токенMaster-Api-Token Мастер-токен для M2M-интеграций. Позволяет выполнять запросы от имени любого пользователя системы через заголовки Impersonated-User-Id. Получается через ESA с помощью сертификата интегратора. — вы контролируете срок жизни сертификата и можете выполнять запросы от имени любого пользователя. Пользовательский токен действует 1 год и привязан к одному пользователю.
Нужна ли MFA для API-интеграции?
Нет. При интеграции через мастер-токенMaster-Api-Token Мастер-токен для M2M-интеграций. Позволяет выполнять запросы от имени любого пользователя системы через заголовки Impersonated-User-Id. Получается через ESA с помощью сертификата интегратора. или пользовательский токен прохождение MFA не требуется.
Мастер-токен истекает?
Да. Срок жизни мастер-токенаMaster-Api-Token Мастер-токен для M2M-интеграций. Позволяет выполнять запросы от имени любого пользователя системы через заголовки Impersonated-User-Id. Получается через ESA с помощью сертификата интегратора. по умолчанию — 10 минут, при регистрации интегратора его можно увеличить до суток. Когда токен истечёт, выпустите новый тем же способом. Сертификат и приватный ключ используйте повторно — до окончания срока действия самого сертификата.
Идентификаторы
В чём разница между employeeId и employeeExternalId?
employeeId — внутренний UUID в HRlink, генерируется автоматически. employeeExternalId — строковый IDid Внутренний идентификатор сущности в формате UUID, генерируемый HRlink при создании. Неизменяемый, используется во всех внутренних операциях. из вашей системы (1С, SAP и т.п.), задаётся при создании. Подробнее — в разделе Идентификаторы.
Если указаны оба ID — какой приоритетнее?
id всегда имеет приоритет над externalId. Если вы передали id, сервер игнорирует externalId.
Маршруты подписания
Почему participantId изменился?
participantId меняется, когда администратор обновляет маршрут в интерфейсе HRlink. Всегда получайте актуальный маршрут непосредственно перед созданием документа. Подробнее — в разделе participantId.
Можно ли создать маршрут подписания через API?
Нет. Маршруты создают только администраторы — через интерфейс HRlink или через Службу заботы. Через API вы получаете список существующих маршрутов и используете их при создании документов.
Документы и файлы
Почему файл не конвертируется при загрузке из 1С?
Чаще всего проблема в формировании multipart/form-data запроса — двоичные данные повреждаются при передаче. Попробуйте загрузить тот же файл через интерфейс HRlink: если загружается — проблема в коде интеграции. Подробнее — в разделе Работа с файлами.
Как узнать статус подписания документа?
Получите документ через Получить документ или реестр через Получить реестр документов и проверьте поле route.stages[n].participants[m] — наличие signedDate, rejectedDate, seenDate. Подробнее — в разделе Отслеживание статусов.
Можно ли передать файл как JSON (base64)?
Нет. Файлы отправляйте только через multipart/form-data. Это особенно актуально для интеграций с SAP.
Работа от имени пользователя
Как работает impersonation?
При использовании мастер-токенаMaster-Api-Token Мастер-токен для M2M-интеграций. Позволяет выполнять запросы от имени любого пользователя системы через заголовки Impersonated-User-Id. Получается через ESA с помощью сертификата интегратора. вы указываете, от чьего имени выполняется запрос, через заголовки Impersonated-User-Id и Impersonated-User-Id-Type. Результат запроса зависит от прав этого пользователя. Подробнее — в разделе Заголовки для работы от имени пользователя.
Какой Impersonated-User-Id-Type использовать?
EXTERNAL_ID— если при синхронизации задавалиexternalIdдля пользователейHR_LINK_ID— если знаете внутренний UUID пользователяSNILS— если знаете СНИЛС пользователя
Синхронизация
PUT-запрос затирает данные — что делать?
В PUT-запросе сервер обнуляет все поля, которые вы не передали. Перед обновлением получите актуальные данные через GET и передайте все поля, даже неизменившиеся. Не забывайте про поле version.
Какую версию updateEmployee использовать?
Используйте V5 — updateEmployeeByExternalIdV5. Это последняя версия с полной поддержкой всех полей.
Сколько элементов можно передать в bulk sync?
Максимум — 500 элементов в одном запросе. Если записей больше, разбивайте их на пакеты по 500 штук и отправляйте последовательно.