Документы

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

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

Документы и заявления

В HRlink есть два основных объекта для подписания: документы (создаёт кадровик) и заявления (создаёт сотрудник). Подробное сравнение вынесено на отдельную страницу: Заявления и документы.

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

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

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

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

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

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

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

Подробный пример с телом запроса и ответами — в гайде Отправка документов на подписание.

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

Для одного документа вызывайте Получить документ или Получить документ по externalId.
Для пачки документов вызывайте Получить реестр документов с фильтром statusLastModifiedDateFrom.
Если нужно остановить подписание, вызовите Прервать подписание документа.
Если подписанный документ нужно отменить, вызовите Аннулировать документ.

Подробный пример polling-цикла — в гайде Отслеживание статуса подписания.

Найти документы после размножения

При создании черновика передайте externalId.
После отправки на подписание вызовите Получить реестр документов с фильтром baseDocumentExternalIds.
В ответе сопоставьте документы с сотрудниками по подписанту EMPLOYEE.

Подробные правила — в разделе Отправка на подписание: размножение документов.

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

Документ создаётся на основании одного файла.
Отправить документ на подписание до завершения PDF/A-конвертации нельзя.
В новых интеграциях используйте signingOrder: ROUTE.
Если в employeeIds несколько сотрудников, HRlink создаёт отдельный документ на каждого сотрудника.
При размножении externalId остаётся на черновике, а созданные документы ищутся через baseDocumentExternalIds.

Типы документов

Тип документа определяет категорию кадрового документа (трудовой договор, приказ, допсоглашение и т.д.).

Поле	Описание
`id`	Идентификатор типа
`russianName`	Название на русском
`externalId`	Идентификатор во внешней системе
`system`	Системный тип (создан HRlink, нельзя удалить)
`visible`	Видимость для пользователей
`mintrudTypeId`	Тип по классификации Минтруда
`signingByEmployeeSesEnabled`	Разрешено ли подписание сотрудником через ПЭП

Типы документов создаёт и настраивает администратор. Через API можно получить список типов, но не создавать новые.

Структура документа

Каждый документ принадлежит одному пространству клиента и одному юридическому лицу.

Поле	Тип	Описание
`id`	UUID	Идентификатор документа
`typeId`	UUID	Тип документа
`legalEntityId`	UUID	Юридическое лицо
`number`	string	Номер документа
`date`	datetime	Дата документа
`notice`	string	Заметка кадровика
`signingOrder`	enum	Порядок подписания
`routeTemplateId`	UUID	Шаблон маршрута (при `signingOrder: ROUTE`)
`externalId`	string	Идентификатор во внешней системе
`hideAfterSigning`	boolean	Скрыть содержимое документа после подписания сотрудником
`rejectionDisabled`	boolean	Запретить отклонение
`deadlineDayCount`	number	Срок подписания в днях
`deadlineDate`	datetime	Дата окончания срока подписания
`baseDocumentId`	UUID	Документ-источник (для связанных документов)

Файлы документа

Документ всегда создаётся на основании одного файла. Прикрепить к документу несколько файлов (вложений) нельзя. Если нужно передать сотруднику дополнительные материалы — создайте отдельный документ для каждого файла.

Допустимые форматы исходного файла: pdf, doc, docx, xls, xlsx, rtf, jpeg, jpg, bmp, png, tiff. После загрузки HRlink автоматически конвертирует файл в PDF/A (подробнее — Конвертация в PDF/A). Отправить документ на подписание до завершения конвертации нельзя.

В ходе жизненного цикла HRlink формирует дополнительные файлы:

Файл	Поле	Когда появляется
Исходный файл	`originalFileId`	При создании черновика документа
PDF/A	`convertedFileId`	После конвертации (подробнее — Конвертация в PDF/A)
Печатная форма	`printFormFileId`	После каждого подписания или отклонения — пересоздаётся с актуальными данными подписей
XML Минтруда	`mintrudXmlFileId`	Для документов, попадающих под приказ №578н
Архив без протокола	`archiveWithoutDocflowProtocolFileId`	После завершения
Архив с протоколом	`archiveWithDocflowProtocolFileId`	После завершения
Файл подписи	`signatureFileId` (у подписанта)	После подписания участником

Подробнее о загрузке и работе с файлами — Работа с файлами.

Порядок подписания

Порядок подписания определяет, кто подписывает документ и в какой очерёдности. Используйте значение ROUTE — очерёдность, состав участников и наблюдателей задаются маршрутом подписания.

Legacy-режимы

В API также доступны значения MANAGER_FIRST, EMPLOYEE_FIRST, EMPLOYEE_ONLY и MANAGER_ONLY. Это предзаполненные маршруты, сохранённые для обратной совместимости. Они не развиваются и не поддерживают новые возможности (гибкие этапы, согласование, множественные участники). В новых интеграциях всегда используйте ROUTE.

Подписанты документа

Каждый участник подписания представлен отдельной записью DocumentSigner, которая хранит тип подписанта, текущий статус и даты действий. При запросе документа подписанты возвращаются в полях headManager, employees и participants:

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "headManager": {
    "id": "a1b2c3d4-0001-0000-0000-000000000001",
    "employeeId": "a1b2c3d4-0002-0000-0000-000000000001",
    "signerType": "HEAD_MANAGER",
    "seenDate": "2026-03-10T10:30:00Z",
    "signedDate": "2026-03-10T11:15:00Z",
    "rejectedDate": null,
    "rejectionComment": null,
    "signingOrder": 1
  },
  "employees": [
    {
      "id": "a1b2c3d4-0001-0000-0000-000000000002",
      "employeeId": "a1b2c3d4-0002-0000-0000-000000000002",
      "signerType": "EMPLOYEE",
      "seenDate": "2026-03-11T09:00:00Z",
      "signedDate": null,
      "rejectedDate": null,
      "rejectionComment": null,
      "signingOrder": 2
    }
  ],
  "participants": []
}

Типы подписантов

Тип	Описание
`HEAD_MANAGER`	Руководитель-подписант — юридически значимая сторона КЭДО (работодатель)
`EMPLOYEE`	Сотрудник-подписант — юридически значимая сторона КЭДО (работник)
`PARTICIPANT`	Участник маршрута подписания (при `signingOrder: ROUTE`)

Ограничение на стороны КЭДО

HEAD_MANAGER и EMPLOYEE — юридически значимые стороны кадрового электронного документооборота. Каждая из этих ролей может присутствовать в документе только один раз. Если документ должны подписать несколько сотрудников, используйте роль PARTICIPANT и порядок подписания ROUTE с маршрутом подписания.

Если сотрудников несколько

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

Статусы подписанта

Статус	Описание	Определяющее поле
`NOT_SEEN`	Документ не просмотрен	`seenDate` = null
`SEEN`	Документ просмотрен	`seenDate` ≠ null
`SIGNED`	Подписан	`signedDate` ≠ null
`REJECTED`	Отклонён	`rejectedDate` ≠ null

При отклонении подписант указывает причину в поле rejectionComment.

Наблюдатели

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

Наблюдателей можно указать при создании документа (watcherIds) или добавить позже. Также можно указать целые отделы через watcherClientDepartmentIds — все сотрудники отдела станут наблюдателями.

Ограничения наблюдателей

Нельзя указывать watcherIds при signingOrder = MANAGER_FIRST или EMPLOYEE_FIRST

Группы документов

DocumentGroup группирует документы в интерфейсе HRlink. При создании документов через API все документы из одного запроса попадают в одну группу и отображаются вместе в реестре.

У группы есть:

id — идентификатор
name — название

Группа помогает показывать связанные документы вместе в интерфейсе.

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

Статус	Описание
`DRAFT`	Черновик — документ создан, но не отправлен на подписание
`IN_PROCESS`	В процессе — документ отправлен, идёт подписание по маршруту
`COMPLETED`	Завершён — все участники выполнили действия
`REJECTED`	Отклонён — один из участников отказался подписывать
`DELETED`	Удалён
`ANNULLED`	Аннулирован — подписан отдельный акт аннулирования этого документа

AWAITING_MY_SIGNING

AWAITING_MY_SIGNING — не отдельный статус, а представление статуса IN_PROCESS для конкретного пользователя, которому сейчас доступно подписание.

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

Создание. Кадровик загружает файл и заполняет реквизиты — документ получает статус DRAFT.
Отправка на подписание. Кадровик отправляет документ — статус меняется на IN_PROCESS, запускается маршрут.
Подписание по этапам. Участники подписывают или согласовывают документ в порядке, определённом маршрутом. Каждый следующий этап начинается после завершения предыдущего.
Завершение. Когда все этапы пройдены — статус COMPLETED, фиксируется docflowFinishedDate.
Отклонение. Если участник на любом этапе отклоняет документ — статус REJECTED.

В ходе документооборота HRlink формирует печатную форму и архив.

Создание документа

Создание документа проходит в два шага: сначала создаётся черновик, затем черновик отправляется на подписание. На каждом шаге свой набор обязательных полей.

Создание черновика

Для создания черновика достаточно трёх полей:

Поле	Альтернатива через externalId	Описание
`fileId`	—	Идентификатор загруженного файла
`legalEntityId`	`legalEntityExternalId`	Юридическое лицо
`typeId`	—	Тип документа

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

Поле	Альтернатива через externalId	Описание
`number`	—	Номер документа
`date`	—	Дата документа
`notice`	—	Заметка кадровика
`signingOrder`	—	Порядок подписания
`headManagerId`	`headManagerExternalId`	Руководитель-подписант
`headManagerLegalEntityId`	`headManagerLegalEntityExternalId`	Юридическое лицо руководителя-подписанта (если отличается от `legalEntityId` документа)
`employeeIds`	`employeeExternalIds`	Список сотрудников-подписантов
`watcherIds`	`watcherExternalIds`	Список наблюдателей
`watcherClientDepartmentIds`	—	Отделы-наблюдатели
`routeTemplateId`	`routeTemplateExternalId`	Шаблон маршрута (при `ROUTE`)
`participants`	—	Участники маршрута (при `ROUTE`)
`externalId`	—	Идентификатор документа во внешней системе
`deadlineDayCount`	—	Срок подписания в днях
`baseDocumentId`	`sourceDocumentExternalId`	Документ-источник

Для полей-ссылок на сущности (юрлицо, сотрудники, шаблон маршрута) можно передать либо внутренний id, либо externalId — идентификатор из внешней системы. Передавать оба поля одновременно не нужно.

Юридическое лицо участников

Сотрудники-подписанты (employeeIds) и наблюдатели (watcherIds) должны относиться к тому же юридическому лицу, что и документ (legalEntityId). Руководитель-подписант (headManagerId) может быть из другого юрлица, если у него есть права руководителя в юрлице документа. В этом случае укажите юрлицо руководителя в поле headManagerLegalEntityId (или headManagerLegalEntityExternalId).

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

Перед отправкой HRlink проверяет, что черновик заполнен полностью. Для отправки нужны:

date — дата документа
signingOrder — порядок подписания (используйте ROUTE)
конвертация файла в PDF/A завершена — convertedFileId заполнен
подписанты назначены согласно маршруту подписания

Если хотя бы одно условие не выполнено, HRlink вернёт ошибку и не отправит документ на подписание.

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

При создании документа в employeeIds можно указать несколько сотрудников. В этом случае HRlink создаёт один черновик (DRAFT), а при отправке на подписание создаёт отдельный документ для каждого сотрудника.

Что происходит при отправке

HRlink помечает черновик как отправленный, и он перестаёт отображаться в реестре черновиков.
Для каждого сотрудника из employeeIds HRlink создаёт отдельный документ.
Каждый созданный документ содержит:
- одного сотрудника-подписанта (EMPLOYEE) из исходного списка;
- того же руководителя-подписанта (HEAD_MANAGER), если он указан в черновике;
- тот же файл — все документы ссылаются на один загруженный файл, копия не создаётся;
- те же реквизиты: номер, дату, тип документа, заметку и порядок подписания.
Поле baseDocumentId каждого созданного документа указывает на исходный черновик.

Особенности

Группа документов. Все документы из одного запроса на создание попадают в одну DocumentGroup и отображаются вместе в реестре.
Маршрут подписания. Каждый созданный документ проходит маршрут независимо — один сотрудник может подписать, а другой отклонить.
externalId. Если сотрудников больше одного, созданные документы получают externalId = null. Внешний идентификатор остаётся на черновике. Если сотрудник один — externalId переносится на созданный документ.
Наблюдатели. Списки наблюдателей (watcherIds, watcherClientDepartmentIds) копируются в каждый созданный документ.

Один сотрудник — без размножения

Если в employeeIds указан один сотрудник, HRlink создаёт ровно один документ.

Как найти созданные документы

Поскольку при размножении у созданных документов externalId: null, прямой поиск по externalId не сработает. Взамен используйте связку «найти по baseDocumentId черновика»:

При создании передайте externalId в черновике (например, DRAFT-195).
После отправки на подписание вызовите Получить реестр документов с фильтром baseDocumentExternalIds: ["DRAFT-195"]. В ответе — все документы, созданные из этого черновика.
Для каждого документа в ответе посмотрите signers[] — там есть конкретный сотрудник-подписант (type: EMPLOYEE, поле employeeId). Сопоставьте с исходным списком employeeIds.

Альтернатива: если черновик сохранили без externalId, но запомнили его UUID — используйте фильтр baseDocumentIds вместо baseDocumentExternalIds.

Всегда передавайте externalId в черновик

Даже если вы не полагаетесь на externalId в своей системе для одиночных документов, при работе с размножением он становится единственным удобным якорем, связывающим ваш запрос с пачкой созданных документов.

Сроки подписания

Документ может иметь срок подписания:

deadlineDayCount — количество дней на подписание (от момента отправки)
deadlineDate — конкретная дата окончания срока

Если срок истёк, документ получает признак deadlineViolated: true, но статус не меняется — документ остаётся в IN_PROCESS. Нарушение срока видно в реестре документов.

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

Аннулирование отменяет подписанный документ. При аннулировании:

Создаётся акт аннулирования — отдельный документ с указанием причины.
Исходный документ переходит в статус ANNULLED.
Акт аннулирования отправляется на подписание участникам.

Аннулировать можно только документ, который:

не в статусе DRAFT
ещё не аннулирован
подписан всеми участниками

Аннулирование — только для документов

Заявления нельзя аннулировать. Заявление можно только отклонить или удалить.

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

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

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

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

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

Найти документы после размножения​

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

Типы документов​

Структура документа​

Файлы документа​

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

Подписанты документа​

Типы подписантов​

Статусы подписанта​

Наблюдатели​

Группы документов​

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

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

Создание документа​

Создание черновика​

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

Отправка на подписание: размножение документов​

Что происходит при отправке​

Особенности​

Как найти созданные документы​

Сроки подписания​

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