Работа с заявлениями

Заявление — это документ, инициируемый сотрудником (заявление на отпуск, увольнение и т.п.), в отличие от документа, который создаёт кадровик. Заявления проходят маршрут согласования и подписания.

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

После выполнения сценария HRlink создаст группу заявлений, заполнит заявление по выбранному типу и передаст его по маршруту согласования и подписания.

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

Что нужно	Где получить
tenantHost	Адрес тенантаTenantЭкземпляр системы HRlink на отдельном домене (например, company.hr-link.ru). Внутри одного тенанта может быть несколько пространств клиентов. HRlink
clientId	Текущий пользователь
Токен	Аутентификация
Тип заявления	Получить типы заявлений
Значения полей заявления	Из формы внешней системы или данных сотрудника
Пользователь, от имени которого создаётся заявление	Заголовки impersonation при мастер-токенеMaster-Api-TokenМастер-токен для M2M-интеграций. Позволяет выполнять запросы от имени любого пользователя системы через заголовки Impersonated-User-Id. Получается через ESA с помощью сертификата интегратора.

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

Шаг	Метод
Получить типы заявлений	Получить типы заявлений
Создать группу заявлений	Создать заявление
Подготовить файл к подписанию	Конвертировать файл для подписания
Подписать ПЭППЭП (Простая электронная подпись). Простая электронная подпись (SES). Подтверждает факт подписания, но не гарантирует неизменность документа после подписания.	Подать заявление (ПЭП)
Подписать УНЭПУНЭП (Усиленная неквалифицированная электронная подпись). Усиленная неквалифицированная электронная подпись (CLOUD_NQES). Облачная подпись, обеспечивающая целостность документа.	Подать заявление (УНЭП) и Подтвердить подписание УНЭП
Получить список заявлений	Получить реестр заявлений кадровика

Чем заявление отличается от документа

Заявление в HRlink — это экземпляр типа заявления, заранее настроенного администратором клиента. Тип определяет бланк, поля для заполнения и маршрут согласования-подписания. Всё это — в отличие от документа, где маршрут выбирается при создании — встроено в тип заявления.

	Документ	Заявление
Инициатор	Кадровик / делопроизводитель	Сотрудник
Маршрут	SIGNING	APPROVING + SIGNING
Привязка маршрута	Выбирается при создании	Встроен в тип заявления (signingRouteTemplate внутри ApplicationType)
Получать маршрут отдельно	Да — через метод	Нет — уже внутри типа
Тип участника ROLE	Не поддерживается	Поддерживается
API-группа	documentsGroups	applicationsGroups

Практический вывод для интегратора: для создания заявления достаточно выбрать нужный тип — маршрут подтянется автоматически.

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

Метод Получить типы заявлений возвращает все типы заявлений клиента. Типы бывают двух видов:

• Из шаблона docx (templatable: true) — большинство типов. Основа заявления — заранее загруженный docx-шаблон с полями, которые сотрудник заполняет при подаче. Поля описаны в templateFields.
• Из файла (templatable: false) — один специальный тип, когда сотрудник сам прикладывает файл заявления. Полей для заполнения нет.

curl

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

PowerShell

Invoke-RestMethod `
  -Uri "https://{tenantHost}/api/v1/applicationTypes" `
  -Method GET `
  -Headers @{
    "Accept"         = "application/json"
    "User-Api-Token" = "{token}"
  }

HTTP

GET /api/v1/applicationTypes HTTP/1.1
Host: {tenantHost}
Accept: application/json
User-Api-Token: {token}

Пример сокращённого ответа:

{
  "result": true,
  "applicationTypes": [
    {
      "id": "c4d2f1a8-9b3e-4c7d-8a2f-5b6d9e3c7a1b",
      "name": "Заявление на отпуск",
      "templatable": true,
      "active": true,
      "fileId": "f1e2d3c4-1111-2222-3333-444455556666",
      "signingRouteTemplate": {
        "id": "7a2e8b5c-1d4f-4a9e-b3c7-8f6a2d5e1b4c",
        "name": "Согласующий и кадровик"
      },
      "signingByEmployeeSesEnabled": true
    },
    {
      "id": "e8a1b3d5-1111-2222-3333-444455556666",
      "name": "Произвольное заявление из файла",
      "templatable": false,
      "active": true
    }
  ]
}

Что запомнить из ответа:

• id нужного типа передавайте как typeId при создании группы заявлений (следующий раздел)
• active: false означает, что администратор выключил тип — не используйте его в интеграции
• signingRouteTemplate.id — уже привязанный маршрут, отдельно его получать не нужно

Создание группы заявлений

typeId в запросе — это id типа заявления, выбранного в предыдущем разделе. Доступны несколько версий метода. Рекомендуется использовать последнюю.

Почему в запросе объект application

В текущей модели HRlink одна ApplicationGroup содержит одно заявление, поэтому applicationGroupCreateV3 принимает объект application, а не массив.

curl

curl -X POST "https://{tenantHost}/api/v3/clients/{clientId}/applicationGroups" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "User-Api-Token: {token}" \
  -d '{
    "typeId": "{UUID типа заявления}",
    "date": "2026-04-15T00:00:00",
    "application": {
      "legalEntityId": "{UUID юрлица}",
      "fileId": "{UUID загруженного файла}",
      "participants": []
    }
  }'

PowerShell

$body = @{
  typeId      = "{UUID типа заявления}"
  date        = "2026-04-15T00:00:00"
  application = @{
    legalEntityId = "{UUID юрлица}"
    fileId        = "{UUID загруженного файла}"
    participants  = @()
  }
} | ConvertTo-Json -Depth 4

Invoke-RestMethod `
  -Uri "https://{tenantHost}/api/v3/clients/{clientId}/applicationGroups" `
  -Method POST `
  -Headers @{
    "Accept"         = "application/json"
    "User-Api-Token" = "{token}"
  } `
  -ContentType "application/json" `
  -Body $body

HTTP

POST /api/v3/clients/{clientId}/applicationGroups HTTP/1.1
Host: {tenantHost}
Accept: application/json
Content-Type: application/json
User-Api-Token: {token}

{
  "typeId": "{UUID типа заявления}",
  "date": "2026-04-15T00:00:00",
  "application": {
    "legalEntityId": "{UUID юрлица}",
    "fileId": "{UUID загруженного файла}",
    "participants": []
  }
}

Версии метода

Версия	Эндпоинт	Примечание
v1	POST /api/v1/clients/{clientId}/applicationGroups	Базовая
v2	POST /api/v2/clients/{clientId}/applicationGroups	Расширенная
v3	POST /api/v3/clients/{clientId}/applicationGroups	Рекомендуется

Подготовка файла к подписанию

После создания или изменения черновика вызовите Конвертировать файл для подписания. Этот шаг обязателен перед первым подписанием заявления сотрудником через ПЭППЭП (Простая электронная подпись). Простая электронная подпись (SES). Подтверждает факт подписания, но не гарантирует неизменность документа после подписания., УНЭПУНЭП (Усиленная неквалифицированная электронная подпись). Усиленная неквалифицированная электронная подпись (CLOUD_NQES). Облачная подпись, обеспечивающая целостность документа., Госключ или портал «Работа России».

Метод возвращает состояние в convertedFileProcess.state:

Значение	Что делать
IN_PROGRESS	Конвертация идёт. Повторите вызов метода и снова проверьте состояние
FINISHED	Файл готов. Переходите к подписанию
FAILED	Конвертация завершилась ошибкой. Проверьте исходный файл и поля заявления, исправьте данные и вызовите метод повторно

Не вызывайте метод подписания, пока состояние не изменилось на FINISHED. Иначе сервер вернёт 400 Bad Request, код 13.862 и сообщение «Файлы в группе заявлений сотрудника ещё не сконвертировались».

Подписание заявлений

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

ПЭП (простая электронная подпись)

Для первичной подписи сотрудником-заявителем вызовите Подать заявление (ПЭП) после завершения подготовки файла. Метод подписывает группу заявлений, не требует тела запроса и запускает маршрут.

Для последующего согласования участником маршрута вызовите Согласовать заявление (ПЭП). В теле передайте participantId участника активного этапа и текущую version заявления из ответа метода получения заявления:

curl

curl -X POST "https://{tenantHost}/api/v1/clients/{clientId}/applications/{applicationId}/signBySes" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "User-Api-Token: {token}" \
  -d '{"participantId":"{UUID участника маршрута}","version":1}'

PowerShell

$body = @{
  participantId = "{UUID участника маршрута}"
  version       = 1
} | ConvertTo-Json

Invoke-RestMethod `
  -Uri "https://{tenantHost}/api/v1/clients/{clientId}/applications/{applicationId}/signBySes" `
  -Method POST `
  -Headers @{
    "Accept"         = "application/json"
    "User-Api-Token" = "{token}"
  } `
  -ContentType "application/json" `
  -Body $body

HTTP

POST /api/v1/clients/{clientId}/applications/{applicationId}/signBySes HTTP/1.1
Host: {tenantHost}
Accept: application/json
Content-Type: application/json
User-Api-Token: {token}

{"participantId":"{UUID участника маршрута}","version":1}

УНЭП (усиленная неквалифицированная)

УНЭПУНЭП (Усиленная неквалифицированная электронная подпись). Усиленная неквалифицированная электронная подпись (CLOUD_NQES). Облачная подпись, обеспечивающая целостность документа. подписывает группу заявлений в два шага. До первого шага подготовьте файл по инструкции Подготовка файла к подписанию. Затем сотрудник получает код в текущий канал подписания (SMS или email) и передаёт его в API. Подробнее о канале подписания — Выпуск УНЭП.

1. Инициировать подписание группы заявлений УНЭП — POST /api/v1/clients/{clientId}/applicationGroups/{applicationGroupId}/sign/nqes. В ответе signingRequestId.
2. Подтвердить подписание группы заявлений УНЭП — PUT на тот же URL с кодом в теле.

Предусловие: у сотрудника должен быть выпущен УНЭПУНЭП (Усиленная неквалифицированная электронная подпись). Усиленная неквалифицированная электронная подпись (CLOUD_NQES). Облачная подпись, обеспечивающая целостность документа. (NqesIssuingState = FINISHED) — см. Выпуск УНЭП. Автоподписание УНЭПУНЭП (Усиленная неквалифицированная электронная подпись). Усиленная неквалифицированная электронная подпись (CLOUD_NQES). Облачная подпись, обеспечивающая целостность документа. от лица сотрудника не поддерживается — код физически приходит сотруднику.

Через Госключ

Подпись через Госключ инициирует метод Подписать заявление через Госключ — POST /api/v1/clients/{clientId}/applications/{applicationId}/sign/govKey. Само подтверждение сотрудник проходит в мобильном приложении «Госключ».

Предусловие: у сотрудника включено право ENABLE_SIGNING_THROUGH_GOV_KEY (подписание через Госключ).

Автоподписание от лица сотрудника

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

1. Создать заявление от имени сотрудника
2. Подписать ПЭППЭП (Простая электронная подпись). Простая электронная подпись (SES). Подтверждает факт подписания, но не гарантирует неизменность документа после подписания. от имени сотрудника
3. Заявление уходит на согласование руководителю

Заголовки для работы от имени пользователя обязательны

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

Согласование заявлений

Согласование — этап маршрута с actionType: APPROVING. В публичном API HRlink нет отдельного метода «одобрить заявление»: с точки зрения API одобрение согласующим и подписание подписантом устроены одинаково — через тот же Подписать заявление ПЭП или подпись УНЭПУНЭП (Усиленная неквалифицированная электронная подпись). Усиленная неквалифицированная электронная подпись (CLOUD_NQES). Облачная подпись, обеспечивающая целостность документа. / Госключ. Сервер сам понимает, что участник находится на этапе APPROVING, и трактует вызов как одобрение.

Для отказа в согласовании есть отдельный метод Отклонить заявление. В теле передайте participantId, текущую version заявления и comment с причиной отклонения:

curl

curl -X PUT "https://{tenantHost}/api/v1/clients/{clientId}/applications/{applicationId}/reject" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "User-Api-Token: {token}" \
  -d '{"participantId":"{UUID участника маршрута}","version":2,"comment":"Некорректные даты отпуска"}'

PowerShell

$body = @{
  participantId = "{UUID участника маршрута}"
  version       = 2
  comment       = "Некорректные даты отпуска"
} | ConvertTo-Json

Invoke-RestMethod `
  -Uri "https://{tenantHost}/api/v1/clients/{clientId}/applications/{applicationId}/reject" `
  -Method PUT `
  -Headers @{
    "Accept"         = "application/json"
    "User-Api-Token" = "{token}"
  } `
  -ContentType "application/json" `
  -Body $body

HTTP

PUT /api/v1/clients/{clientId}/applications/{applicationId}/reject HTTP/1.1
Host: {tenantHost}
Accept: application/json
Content-Type: application/json
User-Api-Token: {token}

{"participantId":"{UUID участника маршрута}","version":2,"comment":"Некорректные даты отпуска"}

Реестры заявлений

Реестры возвращают страницу заявлений с учётом ролевых ограничений: кадровик видит все заявления своих юрлиц, сотрудник — только свои. Оба метода используют POST для чтения — потому что фильтры сложные (набор UUID, диапазоны дат, статусы) и не помещаются в query-параметры.

Доступные поля фильтрации (все опциональные):

Поле	Назначение
applicationTypeIds	Фильтр по типам заявлений
applicationStatuses	Фильтр по статусам (ApplicationStatus)
legalEntityIds	Фильтр по юрлицам (кадровик передаёт юрлица, на которые у него есть права)
employeeIds	Фильтр по сотрудникам-заявителям
clientDepartmentIds	Фильтр по отделам
applicationDateFrom / applicationDateTo	Диапазон дат самих заявлений
applicationCreatedDateFrom / applicationCreatedDateTo	Диапазон дат создания
applicationDocflowFinishedDateFrom / applicationDocflowFinishedDateTo	Диапазон дат завершения документооборота
applicationIds	Явный список UUID заявлений
clientUserParticipantIds	Фильтр по участникам маршрута
clientUserResponsibleIds	Фильтр по ответственным
limit, offset	Пагинация

Реестр кадровика

Получить реестр заявлений кадровика — все заявления клиента. Требует прав кадровика хотя бы на одно юрлицо.

curl

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

PowerShell

$body = @{
  legalEntityIds = @("{UUID юрлица}")
  limit          = 50
  offset         = 0
} | ConvertTo-Json

Invoke-RestMethod `
  -Uri "https://{tenantHost}/api/v2/clients/{clientId}/applicationGroups/getHrRegistry" `
  -Method POST `
  -Headers @{
    "Accept"         = "application/json"
    "User-Api-Token" = "{token}"
  } `
  -ContentType "application/json" `
  -Body $body

HTTP

POST /api/v2/clients/{clientId}/applicationGroups/getHrRegistry HTTP/1.1
Host: {tenantHost}
Accept: application/json
Content-Type: application/json
User-Api-Token: {token}

{
  "legalEntityIds": ["{UUID юрлица}"],
  "limit": 50,
  "offset": 0
}

Реестр сотрудника

Получить реестр заявлений сотрудника — заявления текущего сотрудника (как заявителя, участника маршрута или ответственного).

curl

curl -X POST "https://{tenantHost}/api/v2/clients/{clientId}/applicationGroups/getEmployeeRegistry" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "User-Api-Token: {token}" \
  -d '{"limit": 50, "offset": 0}'

PowerShell

$body = @{
  limit  = 50
  offset = 0
} | ConvertTo-Json

Invoke-RestMethod `
  -Uri "https://{tenantHost}/api/v2/clients/{clientId}/applicationGroups/getEmployeeRegistry" `
  -Method POST `
  -Headers @{
    "Accept"         = "application/json"
    "User-Api-Token" = "{token}"
  } `
  -ContentType "application/json" `
  -Body $body

HTTP

POST /api/v2/clients/{clientId}/applicationGroups/getEmployeeRegistry HTTP/1.1
Host: {tenantHost}
Accept: application/json
Content-Type: application/json
User-Api-Token: {token}

{"limit": 50, "offset": 0}