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

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

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

После выполнения сценария 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). Подтверждает факт подписания, но не гарантирует неизменность документа после подписания. подписывает одно заявление. Вызовите Подписать заявление ПЭП. В теле передайте 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}