Перейти к основному содержимому

Отслеживание статусов подписания

После отправки документа на подпись получайте изменения через webhook. Периодический polling реестра найдёт изменения, которые ваша система пропустила после длительного сбоя обработчика или деактивации подписки.

Что получится в конце​

Ваша система будет получать события об отправке, действиях участников и обновлении печатной формыпечатная формаPDF-документ с визуальным оттиском подписей, который система формирует после завершения документооборота. Печатная форма доступна для скачивания и используется для архивного хранения.. Периодическая сверка найдёт документы, изменения которых ваша система не обработала через webhook.

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

Что нужноГде получить
Подписка webhookПодключение и приём событий
tenantHostАдрес тенантаTenantЭкземпляр системы HRlink на отдельном домене (например, company.hr-link.ru). Внутри одного тенанта может быть несколько пространств клиентов. HRlink
clientIdТекущий пользователь
ТокенАутентификация
documentId или externalIdИз ответа на создание документа или из внешней системы
Права на документыАвторизация и права доступа
Поле lastSyncAtХраните в своей системе для инкрементального polling

Как выбрать способ​

СпособДля чего использовать
WebhookПолучать изменения без постоянного опроса API
Short pollingСразу после запуска автоматической операции без участия человека дождаться её результата
Incremental pollingПериодически сверять реестр и восстанавливать пропущенные изменения

Форматы входящих событий описаны на странице События и поля.

Какие методы используются​

СценарийМетод
Проверить один документПолучить документ
Проверить документ по внешнему IDexternalIdВнешний идентификатор сущности — произвольная строка, задаваемая интегратором при создании. Связывает сущность HRlink с записью во внешней системе (1С, SAP и др.) без хранения маппинга UUID.Получить документ по externalId
Получать изменения пачкамиПолучить реестр документов
Остановить подписаниеПрервать подписание документа
Аннулировать подписанный документАннулировать документ

Способы получения статуса​

1. Получить конкретный документ​

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

2. Реестр документов кадровика​

curl -X POST "https://{tenantHost}/api/v1/clients/{clientId}/documents/hrRegistry" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "User-Api-Token: {token}" \
  -d '{
    "legalEntityIds": ["{UUID юрлица}"],
    "limit": 50,
    "offset": 0
  }'

Основные фильтры реестра:

ПолеНазначение
legalEntityIdsФильтр по юрлицам
documentTypeIdsФильтр по типам документов
documentStatusesФильтр по статусам документов (DocumentStatus)
documentDateFrom / documentDateToДиапазон дат самих документов (поле date документа)
createdDateFrom / createdDateToДиапазон дат создания документа в HRlink
statusLastModifiedDateFrom / statusLastModifiedDateToДиапазон дат последнего изменения статуса для инкрементального polling
employeeIdsФильтр по сотрудникам-подписантам
baseDocumentExternalIdsФильтр по externalIdexternalIdВнешний идентификатор сущности — произвольная строка, задаваемая интегратором при создании. Связывает сущность HRlink с записью во внешней системе (1С, SAP и др.) без хранения маппинга UUID. черновика (для работы с размножением документов)

Полный список фильтров — в OpenAPI-спецификации.

Статусы документа​

Значения enum DocumentStatus:

СтатусОписание
DRAFTЧерновик — ожидает отправки на подписание
IN_PROCESSДокумент в процессе подписания (ожидает действий участников)
AWAITING_MY_SIGNINGДокумент ожидает подписания текущим пользователем
COMPLETEDПодписание завершено на всех этапах маршрута
REJECTEDОтклонён одним из участников
ANNULLEDАннулирован
DELETEDУдалён

Определение статуса по маршруту​

Детали прогресса подписания — в поле route документа:

{
  "route": {
    "stages": [
      {
        "id": "0d07668b-4e28-40a7-b25f-7a5a2a0a3b4c",
        "indexNumber": 0,
        "type": "SIGNING",
        "completenessCondition": "ALL",
        "participants": [
          {
            "id": "9a35f510-9a7c-4f2f-b5a3-8a8f87170f22",
            "type": "EMPLOYEE",
            "actionType": "SIGNING",
            "signedDate": "2025-01-16T10:30:00Z",
            "rejectedDate": null,
            "seenDate": "2025-01-16T10:25:00Z"
          }
        ]
      },
      {
        "id": "07b8b2fa-7cf7-4d4a-a01e-fb110044c5ef",
        "indexNumber": 1,
        "type": "SIGNING",
        "participants": [
          {
            "id": "74c60239-d6f5-42f8-bf56-cfb680600415",
            "type": "EMPLOYER",
            "actionType": "SIGNING",
            "signedDate": null,
            "rejectedDate": null,
            "seenDate": null
          }
        ]
      }
    ]
  }
}

Как читать данные маршрута​

Для каждого участника (route.stages[n].participants[m]):

ПолеЗначениеЧто означает
signedDateне nullУчастник подписал
rejectedDateне nullУчастник отклонил
seenDateне nullУчастник просмотрел документ
Все null—Участник ещё не получил документ или не принял решение

Логика определения текущего состояния​

Стратегия polling​

Polling дополняет webhook. Используйте два сценария:

  • Short polling — сразу после запуска автоматической операции без участия человека дождаться её результата;
  • Incremental polling — периодически сверять изменения по всему реестру.

Short polling: конкретный документ​

Используйте short polling сразу после запуска автоматической операции, которая не требует действия человека, например автоподписания. Чтобы дождаться результата, вызывайте Получить документ или Получить документ по externalId.

ПараметрЗначение
Первый опросЧерез 30–60 секунд после отправки (время на конвертацию в PDF/A)
Стартовый интервал10–15 секунд
Увеличение интервалаЭкспоненциальное (×1.5), с jitter ±20%
Максимальный интервал5 минут
Общий таймаутВаша система задаёт конечный таймаут. После его истечения ваша система прекращает short polling и ожидает событие через webhook либо выполняет периодическую сверку реестра
При 429Экспоненциальный backoff по правилам раздела Ограничения

Short polling применяйте только к автоматическим операциям, результат которых нужен сразу. Действия человека отслеживайте через webhook и периодическую сверку реестра.

Incremental polling: изменения по реестру​

Сценарий: у вас тысячи документов и нужно подтягивать изменения статусов в вашу систему. Вызывайте Получить реестр документов с фильтром statusLastModifiedDateFrom.

Алгоритм:

  1. Прочитайте из своего хранилища значение lastSyncAt, записанное после последнего успешно завершённого цикла. Для первого цикла задайте начальную точку синхронизации в UTC.
  2. Перед опросом запомните currentSyncAt = now().
  3. Вызовите реестр с statusLastModifiedDateFrom = lastSyncAt - ε, где ε — небольшой буфер (например, 30 секунд) против рассинхрона часов и событий на границе.
  4. Запрашивайте страницы через limit/offset: после каждой страницы увеличивайте offset на limit. Остановитесь, когда реестр вернёт меньше limit документов.
  5. После успешной обработки всех страниц сохраните lastSyncAt = currentSyncAt.
ПараметрЗначение
Интервал между циклами1–5 минут для активных процессов, 15–30 минут для архивных
limit на страницу50 (по умолчанию) или меньше — для снижения нагрузки на один запрос
Буфер ε перекрытия30–60 секунд — защита от граничных событий между запросами
ФильтрыВсегда задавайте legalEntityIds. Добавьте documentStatuses, если ваша система отслеживает не все статусы
При 429Пропустите цикл и увеличьте интервал перед следующим опросом по правилам раздела Ограничения

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

Большие реестры

Если реестр содержит больше 45 000 документов, разбивайте запросы по юрлицам и временным окнам. Без фильтров сервер обрабатывает больше документов, что повышает риск таймаутов и перегрузки вашей системы.

Пример incremental polling​

Запрос документов, у которых статус изменился с момента последнего опроса.

curl -X POST "https://{tenantHost}/api/v1/clients/{clientId}/documents/hrRegistry" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "User-Api-Token: {token}" \
  -d '{
    "legalEntityIds": ["{UUID юрлица}"],
    "statusLastModifiedDateFrom": "2025-01-15T12:00:00Z",
    "documentStatuses": ["COMPLETED", "REJECTED", "ANNULLED"],
    "limit": 50,
    "offset": 0
  }'

Аннулирование документа​

Чтобы отозвать документ после отправки на подпись, вызовите Аннулировать документ:

curl -X POST "https://{tenantHost}/api/v1/clients/{clientId}/documents/{documentId}/annul" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "User-Api-Token: {token}" \
  -d '{
    "reason": "Документ оформлен с ошибкой"
  }'

Прерывание подписания​

Чтобы прервать процесс подписания без аннулирования, вызовите Прервать подписание документа:

curl -X POST "https://{tenantHost}/api/v1/clients/{clientId}/documents/{documentId}/sign/interrupt" \
  -H "Accept: application/json" \
  -H "User-Api-Token: {token}"
Разница между аннулированием и прерыванием
  • Аннулирование — документ становится недействительным, нельзя продолжить подписание
  • Прерывание — процесс подписания останавливается, но документ можно отправить заново