Маршруты подписания

Маршрут подписания определяет, кто, в каком порядке и каким способом подписывает документ или заявление. Без понимания маршрута нельзя корректно отправить документ на подпись.

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

Интеграция сможет выбрать шаблон маршрута, сопоставить участников с сотрудниками, передать participantId при создании документа и обработать изменение шаблона без ручного разбора ошибки.

Когда использовать

Используйте эту страницу, когда интеграция выбирает шаблон маршрута, заполняет участников документа, сопоставляет participantId или разбирает статусы подписания по этапам.

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

Что нужно	Где получить
`clientId`	Текущий пользователь
Токен	Аутентификация
Шаблон маршрута	Получить шаблоны маршрутов
Юрлицо документа или тип заявления	Документы или Заявления
Сотрудники-участники	Модель данных

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

Сценарий	Метод
Получить шаблон маршрута	Получить шаблоны маршрутов
Создать документ с маршрутом	Создать группу и отправить на подписание
Проверить маршрут документа	Получить документ или Получить документ по externalId
Взять заявление в работу	Взять заявление в работу

Типовые сценарии

Выбрать маршрут для документа

Вызовите Получить шаблоны маршрутов с signingObjectType=DOCUMENT.
Выберите маршрут, привязанный к нужному юрлицу.
Передайте routeTemplateId и signingOrder: ROUTE при создании документа.

Заполнить участников маршрута

Найдите участников с типом SELECTABLE_EMPLOYEE или другим типом, где сотрудник задаётся при создании.
Возьмите participantId из шаблона.
Передайте participantId и сотрудника в массиве participants.

Обработать изменение шаблона

Сохраняйте version шаблона вместе с participantId.
Перед отправкой документа перечитайте шаблон.
Если version изменилась, обновите participantId.

Ограничения и ошибки

Маршруты нельзя создавать или редактировать через публичный API.
participantId пересоздаётся при любом сохранении шаблона маршрута.
Тип участника ROLE работает только в маршрутах заявлений.
Ошибка 13.1914 означает, что клиент передал устаревший или неверный participantId.
В новых интеграциях для документов используйте signingOrder: ROUTE.

Структура маршрута

SigningRouteTemplate (шаблон маршрута)
  └─ stages[] (этапы)
       ├─ Stage 1 (например: подписание сотрудником)
       │    ├─ type: SIGNING
       │    ├─ completenessCondition: ALL
       │    └─ participants[] (участники)
       │         ├─ Participant (type: EMPLOYEE, actionType: SIGNING)
       │         └─ Participant (type: SELECTABLE_EMPLOYEE, actionType: APPROVING)
       └─ Stage 2 (например: подписание руководителем)
            ├─ type: SIGNING
            ├─ completenessCondition: ALL
            └─ participants[]
                 └─ Participant (type: EMPLOYER, actionType: SIGNING)

Этапы (stages)

Каждый этап имеет тип и условие завершения.

Типы этапов

Тип	Описание
`SIGNING`	Подписание — участники подписывают или согласовывают документ
`RECEIVING`	Получение — участники получают документ для ознакомления

Условие завершения этапа

Условие	Описание
`ALL`	Все участники этапа должны выполнить действие
`ANY`	Любой участник этапа должен выполнить действие

Этапы выполняются последовательно: следующий этап начинается только после завершения предыдущего.

Типы участников

В шаблоне маршрута 6 типов участников (SigningRouteParticipantType). При создании документа они материализуются в подписантов с более компактным набором из 3 типов (DocumentSignerType) — подробнее в разделе Шаблон маршрута и маршрут документа.

Тип в шаблоне	Описание	Как определяется сотрудник	В документе приходит как
`EMPLOYEE`	Сотрудник-подписант	При создании документа	`EMPLOYEE`
`EMPLOYER`	Представитель работодателя	Передаётся в поле `headManagerId` при создании документа, или автоматически через правило автозаполнения из шаблона	`HEAD_MANAGER`
`FIXED_EMPLOYEE`	Конкретный сотрудник, указанный в шаблоне маршрута	Не нужно — уже зафиксирован в маршруте	`PARTICIPANT`
`SELECTABLE_EMPLOYEE`	Сотрудник, которого выбирают при создании документа	При создании документа	`PARTICIPANT`
`ROLE`	Сотрудник с одной из ролей `EmployeeRoleType`: `HEAD_MANAGER` (руководитель), `HR` (кадровик) или `CLERK` (делопроизводитель)	Система выбирает сотрудника по его ролям (только для заявлений)	`PARTICIPANT`
`RESPONSIBLE`	Один из «ответственных» за заявление — их назначают методом Взять заявление в работу. Работает на этапе с `responsibleEnabled: true` (только для заявлений)	Система берёт сотрудника из списка ответственных заявления	`PARTICIPANT`

Типы действий участников

Действие	Описание
`SIGNING`	Подписание документа
`APPROVING`	Согласование документа
`RECEIVING`	Получение (ознакомление)
`PROCESSING`	Обработка

Шаблон маршрута и маршрут документа

В API HRlink работают две связанные, но разные модели:

Шаблон маршрута (SigningRouteTemplate) — разметка процесса: какие этапы есть, какого типа участники их проходят и в каком порядке. Шаблон настраивается администратором один раз и переиспользуется.
Маршрут документа (route внутри документа) — материализованный снимок шаблона на момент отправки документа на подписание: с конкретными сотрудниками, датами действий и текущим статусом каждого участника.

Когда документ отправляется на подписание, 6 типов участников шаблона сворачиваются в 3 типа подписантов документа:

Тип в шаблоне	Тип в документе	Почему
`EMPLOYEE`	`EMPLOYEE`	Роль «подписант-сотрудник» сохраняется как есть
`EMPLOYER`	`HEAD_MANAGER`	Роль «подписант от работодателя» — в документе это конкретный руководитель
`FIXED_EMPLOYEE`, `SELECTABLE_EMPLOYEE`, `ROLE`, `RESPONSIBLE`	`PARTICIPANT`	В шаблоне эти типы описывают как выбрать сотрудника. После создания документа выбор уже сделан, и все четыре обобщаются в одного «участника этапа»

Для сопоставления подписанта документа с участником шаблона используется participantId — он одинаков в обоих представлениях. Подробнее — в разделе participantId — критически важная деталь.

Что это значит для интегратора

Если вы читаете шаблон через getSigningRouteTemplates — увидите SigningRouteParticipantType. Если читаете документ через getDocument — увидите DocumentSignerType. Это не баг и не разные версии API, а разные модели для разных этапов жизненного цикла.

Порядок подписания (DocumentSigningOrder)

При создании документа передайте signingOrder:

Порядок	Описание
`EMPLOYEE_FIRST`	Первым подписывает сотрудник, затем руководитель
`MANAGER_FIRST`	Первым подписывает руководитель, затем сотрудник
`EMPLOYEE_ONLY`	Подписывает только сотрудник
`MANAGER_ONLY`	Подписывает только руководитель
`ROUTE`	Очерёдность задаёт маршрут подписания (этапы)

Когда использовать ROUTE

В новых интеграциях всегда используйте ROUTE. Значения EMPLOYEE_FIRST, MANAGER_FIRST, EMPLOYEE_ONLY и MANAGER_ONLY сохранены для обратной совместимости.

participantId — критически важная деталь

participantId пересоздаётся при любом изменении шаблона

participantId каждого участника полностью пересоздаётся каждый раз, когда администратор сохраняет изменения шаблона маршрута — даже если изменилось только название. Внутри HRlink обновление шаблона устроено как «удалить все этапы и участников, создать заново», поэтому никакие ID не сохраняются.

Как работает participantId

Получаете шаблон маршрута через Получить шаблоны маршрутов.
В ответе у каждого участника есть поле id — это и есть participantId.
При создании документа передаёте participantId в массиве participants — для тех типов участников, где это требуется (см. Когда participantId нужен).
Если между шагами 1 и 3 администратор сохранил шаблон, все participantId стали другими. Запрос вернёт ошибку 13.1914.

Стратегия защиты через поле version

У каждого шаблона маршрута есть поле version (long). Оно увеличивается при любом изменении шаблона — и только тогда. Это даёт надёжный способ детектить изменения без сравнения полей:

Если ваша сохранённая version совпадает с version в свежем ответе — participantId гарантированно те же, можно использовать кэшированные значения.
Если version изменилась — перечитайте участников из свежего ответа перед отправкой.

Рекомендуемый алгоритм перед каждой отправкой документа:

Получить шаблоны маршрутов с фильтром по нужному шаблону, забрать version.
Если version совпадает с ранее сохранённой — использовать кэшированные participantId.
Если version отличается — обновить кэш, пересопоставить своих сотрудников с новыми участниками шаблона (по порядку этапов, типам участников, isMultipleSigners — стабильных альтернативных идентификаторов у участника нет).
Отправить документ.

Обработка ошибки 13.1914

Если запрос на подписание вернул ошибку 13.1914 (HTTP 404, «По заданному ID не найден участник этапа маршрута подписания») — это означает, что шаблон изменили между вашими шагами 1 и 3, и кэш устарел. Действия:

Перезапросить шаблон, забрать новый version и участников.
Пересопоставить своих сотрудников с новыми participantId.
Повторить запрос на подписание.

Эта ошибка по природе временная и retryable, в отличие от настоящих ошибок валидации — её имеет смысл обрабатывать отдельной веткой.

Когда participantId нужен

participantId обязательно передавать в массиве participants только для типов участников, где конкретный сотрудник определяется при создании документа:

SELECTABLE_EMPLOYEE — всегда
EMPLOYEE — если в маршруте не один единственный подписант-сотрудник
EMPLOYER — если явно назначаете через participants, а не через headManagerId

Для остальных типов participantId не нужен — система подставит сотрудника сама:

FIXED_EMPLOYEE — сотрудник уже зафиксирован в шаблоне
RESPONSIBLE — система возьмёт сотрудника из назначенных ответственных
ROLE — система найдёт сотрудника по его роли
Участники с автозаполнением (AutoSelectParticipantRuleType) — система выберет сотрудника по оргструктуре

Иными словами, если в вашем маршруте нет SELECTABLE_EMPLOYEE — про participantId можно забыть: все остальные механизмы устойчивы к переизданию шаблона.

Где найти participantId в ответе

В ответах getDocument и getHrDocumentsRegistry маршрут документа доступен в поле route:

{
  "route": {
    "stages": [
      {
        "id": "0d07668b-4e28-40a7-b25f-7a5a2a0a3b4c",
        "indexNumber": 0,
        "type": "SIGNING",
        "participants": [
          {
            "id": "9a35f510-9a7c-4f2f-b5a3-8a8f87170f22",
            "type": "EMPLOYEE",
            "actionType": "SIGNING"
          },
          {
            "id": "74c60239-d6f5-42f8-bf56-cfb680600415",
            "type": "SELECTABLE_EMPLOYEE",
            "actionType": "APPROVING",
            "isMultipleSigners": false
          }
        ]
      }
    ]
  }
}

Если в ответе есть данные об участниках или сотрудниках с полем participantId, по нему можно сопоставить сотрудника с конкретным участником и этапом маршрута.

У каждого участника в route.stages[].participants[] есть:

id — тот самый participantId, через который связываются шаблон и документ
type — DocumentSignerType (EMPLOYEE, HEAD_MANAGER или PARTICIPANT), как эта роль материализовалась в документе
actionType — что участник делает на этапе (SIGNING, APPROVING, RECEIVING, PROCESSING)

Как определить статус подписания

Чтобы понять текущее состояние маршрута, анализируйте данные из route.stages:

route.stages[n].participants[m] → у каждого участника:
  - signedDate    → если не null, участник подписал
  - rejectedDate  → если не null, участник отклонил
  - seenDate      → если не null, участник просмотрел

Состояния операции подписания

Состояние	Описание
`IN_PROGRESS`	Подписание в процессе
`WAITING_CODE`	Ожидается ввод кода для подписания
`CONFIRMING`	Выполняется подтверждение запроса
`WRONG_CODE`	Введён неверный код
`SUCCEEDED`	Запрос завершился успешно
`FAILED`	Запрос завершился неуспешно
`EXPIRED`	Запрос истёк

Способы подписания (RouteSigningType)

Общее сравнение видов подписей и правовой базы см. на странице Подписи.

Способ	Описание
`SES`	ПЭП — простая электронная подпись
`CLOUD_NQES`	Облачный УНЭП — усиленная неквалифицированная электронная подпись
`QES`	УКЭП — усиленная квалифицированная электронная подпись
`PRR`	Через портал «Работа России»
`GOV_KEY`	Госключ
`ANY_APPLICABLE`	Любой подходящий способ из доступных

УКЭП и HRlink

HRlink не хранит закрытый ключ УКЭП — он находится на ПК пользователя. API только инициирует процесс подписания и получает подтверждение.

Ограничения

Маршруты нельзя создавать через API

Маршруты подписания создаются и настраиваются только через UI или Службу заботы. Через API можно:

получить список существующих маршрутов через getSigningRouteTemplates
использовать маршрут при создании документа
но нельзя создать новый маршрут или изменить существующий

ROLE — только для заявлений

Тип участника ROLE работает только в маршрутах заявлений. В маршрутах документов этот тип использовать нельзя.

Прочие ограничения

Один сотрудник не может быть представлен более чем одним участником на одном этапе маршрута
На момент создания документа все участники маршрута должны быть действующими сотрудниками: уволенных участников система не пропустит
Нельзя указывать participants, если signingOrder не равен ROUTE
При MANAGER_FIRST и EMPLOYEE_FIRST нельзя указывать watcherIds
При EMPLOYEE_ONLY нельзя указывать headManagerId
При MANAGER_ONLY нельзя указывать employeeIds

Жизненный цикл документа в маршруте

Пример: отправка документа на подпись с маршрутом

Шаг 1. Получить доступные маршруты

curl
PowerShell
HTTP

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

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

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

Шаг 2. Найти нужный participantId

В ответе найдите нужный шаблон маршрута и его этапы. Для участников типа SELECTABLE_EMPLOYEE сохраните id: это participantId, который понадобится при создании документа.

Шаг 3. Создать группу документов

{
  "documents": [
    {
      "fileId": "{загруженный fileId}",
      "externalId": "DOC-195",
      "legalEntityExternalId": "LE-001",
      "typeId": "{UUID типа документа}",
      "number": "001",
      "date": "2024-12-17T00:00:00",
      "signingOrder": "ROUTE",
      "routeTemplateId": "{UUID маршрута}",
      "participants": [
        {
          "id": "{participantId для SELECTABLE_EMPLOYEE}",
          "employeeExternalId": "EMP-042"
        },
        {
          "id": "{participantId для другого участника}",
          "employeeExternalId": "EMP-099"
        }
      ]
    }
  ]
}

Один participantId — несколько сотрудников

Если участник маршрута типа SELECTABLE_EMPLOYEE помечен флагом «произвольное количество» (isMultipleSigners: true), можно передать несколько объектов с одинаковым participantId, но разными сотрудниками:

{
  "participants": [
    {"id": "28059a0c-9b7e-4df4-8bd6-8a78d7df2a31", "employeeExternalId": "913"},
    {"id": "28059a0c-9b7e-4df4-8bd6-8a78d7df2a31", "employeeExternalId": "6308"}
  ]
}

Все участники — из одного юрлица

Все сотрудники, указанные в документе, включая подписантов и наблюдателей, должны относиться к одному юридическому лицу.

Маршруты документов и заявлений

Маршруты подписания используются и для документов, и для заявлений, но правила для них различаются.

Тип маршрута (SigningObjectType)

У каждого шаблона маршрута есть тип: DOCUMENT или APPLICATION. Шаблон маршрута для документов нельзя использовать для заявлений, и наоборот.

Привязка маршрутов

	Документы	Заявления
Привязка маршрута	К юридическим лицам	К типу заявления (`templateRouteId`)
Выбор маршрута	При создании документа	Задаётся типом заявления

Системные маршруты заявлений

Ключ	Описание
`APPROVER_AND_HR`	Согласующий и кадровик
`ONLY_HR`	Только кадровик
`TWO_HR_AND_APPROVER`	Два кадровика и согласующий
`TWO_APPROVER_AND_HR`	Два согласующих и кадровик
`EMPLOYEE_FUNCTIONAL_HEAD_MANAGER_AND_HR`	Управленческий руководитель и кадровик
`EMPLOYEE_FUNCTIONAL_HEAD_MANAGER_DEPARTMENT_HEAD_MANAGER_AND_HR`	Управленческий руководитель, руководитель отдела и кадровик
`EMPLOYEE_DEPARTMENT_HEAD_MANAGER_FUNCTIONAL_HEAD_MANAGER_AND_HR`	Руководитель отдела, управленческий руководитель и кадровик

Различия в этапах и участниках

Возможность	Документы	Заявления
Тип участника `ROLE`	Нет	Да
`responsibleEnabled` на этапе	Нет	Да
`canDeleteBeforeStageCompleted` на этапе	Нет	Да
`rejectionDisabled` у участника	Да	Нет
`forbiddenSelectYourself` у участника	Нет	Да
`unchangeable` у участника	Нет	Да

Автозаполнение участников

Участники маршрута могут заполняться автоматически по правилам:

Правило	Описание
`DEPARTMENT_HEAD_MANAGER`	Руководитель отдела сотрудника. При цепочке автозаполнений (несколько этапов подряд) следующим выбирается руководитель отдела, к которому относится предыдущий руководитель
`HIERARCHICAL_DEPARTMENT_HEAD_MANAGER`	Руководитель отдела сотрудника. При цепочке автозаполнений следующим выбирается руководитель родительского отдела по иерархии оргструктуры — независимо от того, к какому отделу относится сам руководитель
`FUNCTIONAL_HEAD_MANAGER`	Управленческий (функциональный) руководитель сотрудника

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

Когда использовать​

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

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

Типовые сценарии​

Выбрать маршрут для документа​

Заполнить участников маршрута​

Обработать изменение шаблона​

Ограничения и ошибки​

Структура маршрута​

Этапы (stages)​

Типы этапов​

Условие завершения этапа​

Типы участников​

Типы действий участников​

Шаблон маршрута и маршрут документа​

Порядок подписания (DocumentSigningOrder)​

participantId — критически важная деталь​

Как работает participantId​

Стратегия защиты через поле version​

Обработка ошибки 13.1914​

Когда participantId нужен​

Где найти participantId в ответе​

Как определить статус подписания​

Состояния операции подписания​

Способы подписания (RouteSigningType)​

Ограничения​

Маршруты нельзя создавать через API​

ROLE — только для заявлений​

Прочие ограничения​

Жизненный цикл документа в маршруте​

Пример: отправка документа на подпись с маршрутом​

Шаг 1. Получить доступные маршруты​

Шаг 2. Найти нужный participantId​

Шаг 3. Создать группу документов​

Маршруты документов и заявлений​

Тип маршрута (SigningObjectType)​

Привязка маршрутов​

Системные маршруты заявлений​

Различия в этапах и участниках​

Автозаполнение участников​