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

Отправка документов на подписание

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

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

После выполнения сценария HRlink создаст группу документов, поставит файлы в очередь на конвертацию PDF/A и отправит документы первым участникам маршрута подписания.

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

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

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

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

Общая схема​

Шаг 1. Загрузить файл​

Метод Загрузить файл загружает файл и возвращает fileId. Файлы принимаются только через multipart/form-data. Подробнее — в разделе Работа с файлами.

curl -X POST "https://{tenantHost}/api/v1/files" \
  -H "Accept: application/json" \
  -H "User-Api-Token: {token}" \
  -F "file=@/path/to/document.pdf"

Ответ:

{
  "result": true,
  "files": [
    {
      "id": "677de23d-088a-4454-847a-95ba8be522df",
      "name": "document.pdf",
      "createdDate": "2026-04-15T10:30:00Z"
    }
  ]
}

Сохраните files[0].id — это fileId, который понадобится на шаге 4.

Допустимые форматы: .pdf, .doc, .docx, .rtf, .xls, .xlsx, .jpeg, .jpg, .bmp, .png, .tiff

Только form-data

Не передавайте файл как rawdata JSON — это не работает. Используйте исключительно multipart/form-data. Это частая ошибка при интеграции с SAP и 1С.

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

Метод Получить шаблоны маршрутов возвращает все шаблоны маршрутов клиента. В ответе смешаны маршруты документов и заявлений — для отправки документа нужен только первый тип. Укажите фильтр signingObjectType=DOCUMENT, чтобы сервер вернул только маршруты документов. Параметр includeDeactivated=false (значение по умолчанию) отсекает деактивированные маршруты.

curl -X GET "https://{tenantHost}/api/v1/clients/{clientId}/routeTemplates?signingObjectType=DOCUMENT&includeDeactivated=false" \
  -H "Accept: application/json" \
  -H "User-Api-Token: {token}"

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

{
  "result": true,
  "signingRouteTemplates": [
    {
      "id": "7a2e8b5c-1d4f-4a9e-b3c7-8f6a2d5e1b4c",
      "name": "Стандартный маршрут: сотрудник → руководитель",
      "signingObjectType": "DOCUMENT",
      "externalId": "ROUTE-STANDARD",
      "legalEntities": [
        { "id": "a1b2c3d4-1111-2222-3333-444455556666", "name": "ООО «Альфа»" }
      ],
      "stages": [
        {
          "id": "b3c4d5e6-1111-2222-3333-444455556666",
          "indexNumber": 0,
          "type": "SIGNING",
          "participants": [
            { "id": "4e2b6a8c-1111-2222-3333-444455556666", "type": "EMPLOYEE", "actionType": "SIGNING" }
          ]
        },
        {
          "id": "c4d5e6f7-1111-2222-3333-444455556666",
          "indexNumber": 1,
          "type": "SIGNING",
          "participants": [
            { "id": "9c7f1a2b-1111-2222-3333-444455556666", "type": "EMPLOYER", "actionType": "SIGNING" }
          ]
        }
      ]
    }
  ]
}

Из ответа запомните:

  • id маршрута → это routeTemplateId для шага 4
  • stages[].participants[].id → это participantId (нужен только для участников типа SELECTABLE_EMPLOYEE, для других типов не требуется)
Маршрут должен поддерживать юрлицо документа

Маршруты документов привязаны к юридическим лицам через поле legalEntities. Выбирайте маршрут, у которого среди legalEntities есть то же юрлицо, что вы передадите в legalEntityId на шаге 4. Если не совпадёт — система отклонит запрос. Подробнее: Привязка маршрутов.

Сверяйтесь с version перед отправкой

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

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

Шаг 3. Получить тип документа​

Метод Получить типы документов возвращает все типы документов клиента. Типы бывают двух видов: системные (system: true) — поставляются с HRlink и соответствуют классификации Минтруда, и пользовательские — создаются администратором клиента под внутренние процессы.

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

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

{
  "result": true,
  "documentTypes": [
    {
      "id": "c4d2f1a8-9b3e-4c7d-8a2f-5b6d9e3c7a1b",
      "name": "Трудовой договор",
      "externalId": "TYPE-LABOR-CONTRACT",
      "system": true,
      "visible": true,
      "signingByEmployeeSesEnabled": true
    },
    {
      "id": "e8a1b3d5-1111-2222-3333-444455556666",
      "name": "Приказ об отпуске",
      "system": false,
      "visible": true
    }
  ]
}

Из ответа запомните id нужного типа → это typeId для шага 4. В отличие от юрлица и сотрудников, тип документа передаётся только по UUID — external-вариант поля здесь не поддерживается.

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

Два способа​

МетодОписание
Создать группу документовСоздать группу без отправки на подпись (черновик)
Создать группу и отправить на подписаниеСоздать группу и сразу отправить на подпись

Если документ сразу идёт в работу, используйте documentGroupCreateAndSendToSigning — создание и отправка в одном запросе.

Ответ 200 OK не означает, что документы созданы

Создание группы — асинхронная операция. После ответа 200 OK сервер конвертирует файлы в PDF/A и создаёт документы в фоне. Если конвертация завершится ошибкой, сервер не создаст документы, а создателю уйдёт уведомление на email.

Чтобы программно убедиться, что документы созданы, передайте externalId для каждого документа при создании и опросите результат (см. ниже «Как убедиться, что документы созданы»).

Пример: документ с маршрутом (ROUTE, рекомендуется)​

curl -X POST "https://{tenantHost}/api/v1/clients/{clientId}/documentGroups/sendToSigning" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "User-Api-Token: {token}" \
  -d '{
    "name": "Приказ об отпуске",
    "creatorExternalId": "HR-001",
    "documents": [
      {
        "fileId": "677de23d-088a-4454-847a-95ba8be522df",
        "externalId": "DOC-195",
        "legalEntityExternalId": "LE-001",
        "typeId": "{UUID типа документа}",
        "number": "ПР-042",
        "date": "2025-01-15",
        "signingOrder": "ROUTE",
        "routeTemplateId": "{UUID маршрута}",
        "participants": [
          {
            "id": "{participantId для SELECTABLE_EMPLOYEE}",
            "employeeExternalId": "EMP-042"
          }
        ]
      }
    ]
  }'

Пример: legacy-порядок (EMPLOYEE_FIRST)​

Только для обратной совместимости

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

{
  "name": "Трудовой договор",
  "documents": [
    {
      "fileId": "677de23d-088a-4454-847a-95ba8be522df",
      "legalEntityId": "{UUID юрлица}",
      "typeId": "{UUID типа документа}",
      "number": "ТД-001",
      "date": "2025-01-15",
      "signingOrder": "EMPLOYEE_FIRST",
      "headManagerId": "{UUID сотрудника-руководителя}",
      "employeeIds": ["{UUID сотрудника-подписанта}"]
    }
  ]
}

Поля CreateDocumentDTO​

Обязательные поля​

ПолеТипОписание
fileIdUUIDIDid Внутренний идентификатор сущности в формате UUID, генерируемый HRlink при создании. Неизменяемый, используется во всех внутренних операциях. загруженного файла (из шага 1)
legalEntityId или legalEntityExternalIdUUID / stringЮрлицо документа
typeIdUUIDТип документа (из шага 3)
signingOrderstringПорядок подписания

Поля участников​

ПолеКогда использовать
headManagerId / headManagerExternalIdПри EMPLOYEE_FIRST, MANAGER_FIRST, MANAGER_ONLY
employeeIds / employeeExternalIdsПри EMPLOYEE_FIRST, MANAGER_FIRST, EMPLOYEE_ONLY
watcherIds / watcherExternalIdsТолько при MANAGER_ONLY
routeTemplateId / routeTemplateExternalIdПри ROUTE
participantsПри ROUTE — для участников типа SELECTABLE_EMPLOYEE

Дополнительные поля​

ПолеТипОписание
numberstringНомер документа
datedateДата документа (ГГГГ-ММ-ДД)
noticestringЗаметка о документе
externalIdstringIDid Внутренний идентификатор сущности в формате UUID, генерируемый HRlink при создании. Неизменяемый, используется во всех внутренних операциях. документа во внешней системе
deadlineDayCountintegerСрок подписания в днях

Как убедиться, что документы созданы​

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

Одиночный документ (один сотрудник в employeeIds). Передайте externalId при создании и периодически вызывайте Получить документ по externalId — GET /api/v1/clients/{clientId}/documents/byExternalId/{externalId}. Как только метод вернёт документ с заполненным baseDocumentId — документ создан и отправлен на подписание. Пока возвращается 404 — обработка ещё идёт.

Размножение (несколько сотрудников в employeeIds). externalId остаётся на черновике, у созданных документов он null — прямой опрос по externalIdexternalId Внешний идентификатор сущности — произвольная строка, задаваемая интегратором при создании. Связывает сущность HRlink с записью во внешней системе (1С, SAP и др.) без хранения маппинга UUID. не подойдёт. Вызывайте Получить реестр документов с фильтром baseDocumentExternalIds: [externalId]: как только в реестре появились документы — они созданы. Подробнее: Отправка на подписание: размножение документов.

Интервалы опроса

Конвертация занимает от секунд до десятков секунд, в зависимости от размера и формата файла. Рекомендуемый стартовый интервал — 2-3 секунды, с экспоненциальным увеличением до 30 секунд и таймаутом 5-10 минут.

Ограничения и правила​

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

Совместимость signingOrder и полей​

signingOrderheadManagerheadManager Руководитель отдела — назначается на уровне подразделения (Department). Один руководитель на отдел. Все сотрудники отдела видят этого руководителя в своих данных.employeesEmployee Связь пользователя пространства клиента с юрлицом — пара (clientUserId, legalEntityId). Один пользователь может иметь несколько записей Employee в разных юрлицах или даже в одном.watchersrouteTemplateparticipants
EMPLOYEE_FIRSTДаДаНетНетНет
MANAGER_FIRSTДаДаНетНетНет
EMPLOYEE_ONLYНетДаНетНетНет
MANAGER_ONLYДаНетДаНетНет
ROUTEЗависит от маршрутаЗависит от маршрутаЗависит от маршрутаДаДа

Типичные ошибки​

ОшибкаПричинаРешение
Нельзя указывать участников маршрута подписания для выбранного порядка подписанияparticipants указан при signingOrder != ROUTEУберите participants или используйте ROUTE
Не указаны получатели документа (13.1551)Для маршрута с этапом RECEIVING не указаны watcherIds / watcherExternalIdsДобавьте наблюдателей в watcherExternalIds и соответствующий participants
400 при создании группыНевалидная структура JSON, отсутствие обязательных полейПроверьте наличие fileId, legalEntityId, typeId, signingOrder
participantIdparticipantId Уникальный идентификатор участника в маршруте подписания. Может измениться при обновлении маршрута — перед созданием документа всегда запрашивайте актуальные данные маршрута. изменилсяАдминистратор обновил маршрут между получением и использованиемПолучите маршрут заново перед отправкой
Файл не конвертируется в PDF/AФайл повреждён или формат не поддерживаетсяПроверьте файл, загрузите через UI для проверки

Что дальше​