Документы: обзор и жизненный цикл

Документ в Doodocs People — это кадровый приказ или иной акт, созданный из шаблона либо из загруженного вами PDF. У него есть субъекты (subject_employee_ids — сотрудники, о которых документ), маршрут из шагов согласования и подписания и набор файлов (печатная форма, подписанный PDF, карточка КЭД). Работа с документами через Developer API — это два набора областей: documents:read для чтения и скачивания файлов и documents:write для создания, маршрутизации, отправки и подписания.

Эффективный доступ — это пересечение областей ключа и профиля прав его владельца. Область необходима, но не достаточна: вы видите только то, что видит роль владельца ключа. Одиночный документ, недоступный ключу, возвращает тот же 404 DOCUMENT_NOT_FOUND, что и несуществующий, — по коду ответа проверить наличие скрытого документа нельзя.

Жизненный цикл

Черновик наполняется маршрутом (статус при этом не меняется), затем запускается отправкой. Дальше документ проходит согласование и/или подписание и приходит к завершению — либо обрывается отклонением, запросом изменений или отзывом.

Переходы статусов документа (DocumentStatus)

Значения status в поле status. Переживайте незнакомые значения — набор может пополняться в пределах v1.

`status`	Значение
`DOCUMENT_STATUS_DRAFT`	Черновик. Маршрут можно задавать и менять, документ ещё не запущен
`DOCUMENT_STATUS_ON_APPROVAL`	На согласовании — активен шаг согласования
`DOCUMENT_STATUS_ON_SIGN`	На подписании — активен шаг подписания
`DOCUMENT_STATUS_COMPLETED`	Все шаги пройдены, документ подписан и завершён
`DOCUMENT_STATUS_REJECTED`	Отклонён участником маршрута
`DOCUMENT_STATUS_CHANGE_REQUESTED`	Участник запросил изменения — документ вернулся на доработку
`DOCUMENT_STATUS_REVOKED`	Отозван инициатором или руководителем
`DOCUMENT_STATUS_ARCHIVED`	Документ в архиве

Объект документа

Полный объект отдаёт GET /documents/{document_id} — вместе с файлами и маршрутом. Списковая ручка GET /documents возвращает только скалярные поля (без files и route).

Поле	Тип	Значение
`id`	UUID	Идентификатор документа
`title`	string	Заголовок
`status`	DocumentStatus	Текущий статус (таблица выше)
`type_id`	UUID	Тип документа
`initiator_employee_id`	UUID	Инициатор — сотрудник владельца ключа
`subject_employee_ids`	UUID[]	Субъекты документа
`number`	string	Номер (может быть пустым до присвоения)
`date`	`YYYY-MM-DD`	Дата документа
`organization_id`	UUID	Организация
`department_id`	UUID	Подразделение
`files`	File[]	Файлы документа (см. ниже)
`route`	Route	Маршрут согласования и подписания (см. ниже)
`create_time`	RFC 3339	Момент создания
`update_time`	RFC 3339	Момент последнего изменения
`completed_at`	RFC 3339 \| null	Момент завершения; `null`, пока документ не завершён

Файлы

Каждый элемент files[] — это { "file_id": "…", "file_type": "…" }. Скачать файл по типу можно через GET /documents/{document_id}/download?file_type=….

`file_type`	Что это
`FILE_TYPE_PDF`	Подписанный PDF (значение по умолчанию при скачивании)
`FILE_TYPE_PREVIEW`	Печатная форма
`FILE_TYPE_DDCARD`	Карточка КЭД
`FILE_TYPE_DOCX`	Исходный DOCX
`FILE_TYPE_JSON`	JSON-представление

Маршрут

route описывает согласование и подписание: { "id", "status", "active", "steps": [] }. Каждый шаг — это step_type (STEP_TYPE_APPROVAL или STEP_TYPE_SIGNING), rule (STEP_RULE_ALL — нужны все, STEP_RULE_ANY_ONE — достаточно одного) и список participants[].

{
  "id": "8c2d…",
  "title": "Приказ о приёме — Куляш Байсеитова",
  "status": "DOCUMENT_STATUS_ON_SIGN",
  "type_id": "t1…",
  "initiator_employee_id": "3f2a9c7e-…",
  "subject_employee_ids": ["3f2a9c7e-…"],
  "number": "ПР-2026-014",
  "date": "2026-02-10",
  "organization_id": "org1…",
  "department_id": "d1…",
  "files": [
    { "file_id": "f1…", "file_type": "FILE_TYPE_PREVIEW" },
    { "file_id": "f2…", "file_type": "FILE_TYPE_PDF" }
  ],
  "route": {
    "id": "r1…",
    "status": "ROUTE_STATUS_ACTIVE",
    "active": true,
    "steps": [
      {
        "step_type": "STEP_TYPE_SIGNING",
        "rule": "STEP_RULE_ALL",
        "participants": [
          {
            "id": "p1…",
            "employee_id": "9b7f…",
            "key_type": "INDIVIDUAL",
            "status": "PARTICIPANT_STATUS_PENDING"
          }
        ]
      }
    ]
  },
  "create_time": "2026-02-10T08:00:00Z",
  "update_time": "2026-02-10T09:15:00Z",
  "completed_at": null
}

Участники маршрута описаны только идентификаторами: id, employee_id, key_type и status. Имён, ИИН и должностей объект документа не содержит — чтобы получить данные сотрудника по employee_id, читайте его через API сотрудников своим ключом.

Видимость в списке

GET /documents показывает документы по инициатору и области прав владельца ключа. Документ, доступный ключу только через участие в маршруте (грант участника), в списке не появится — но GET /documents/{document_id} его вернёт.

Не полагайтесь на список как на полный реестр видимых документов. Если у вас есть идентификатор (например из вебхука), забирайте документ напрямую через GET /documents/{document_id}.

Дальше

Шаблоны

Найдите шаблон и прочитайте его variable_schema.

Подписание

Создать → маршрут → отправить → подписать → скачать.

События

Вебхуки document.* и реакция на смену статуса.

Начало работы

Сотрудники