> ## Documentation Index
> Fetch the complete documentation index at: https://platform.doodocs.kz/llms.txt
> Use this file to discover all available pages before exploring further.
# Документы: обзор и жизненный цикл
> Что такое документ, его статусы и структура объекта
Документ в Doodocs People — это кадровый приказ или иной акт, созданный из
**шаблона** либо из [загруженного вами PDF](/ru/guides/documents/uploads). У него
есть **субъекты** (`subject_employee_ids` — сотрудники, о которых документ),
**маршрут** из шагов согласования и подписания и набор **файлов** (печатная
форма, подписанный PDF, карточка КЭД).
Работа с документами через Developer API — это два набора областей: `documents:read`
для чтения и скачивания файлов и `documents:write` для создания, маршрутизации,
отправки и подписания.
Эффективный доступ — это пересечение областей ключа и профиля прав его владельца.
Область необходима, но не достаточна: вы видите только то, что видит роль владельца
ключа. Одиночный документ, недоступный ключу, возвращает тот же `404`
`DOCUMENT_NOT_FOUND`, что и несуществующий, — по коду ответа проверить наличие
скрытого документа нельзя.
## Жизненный цикл
Черновик наполняется маршрутом (статус при этом не меняется), затем запускается
отправкой. Дальше документ проходит согласование и/или подписание и приходит к
завершению — либо обрывается отклонением, запросом изменений или отзывом.
```mermaid theme={null}
%%{init: {'theme':'neutral'}}%%
stateDiagram-v2
[*] --> DRAFT
DRAFT --> ON_APPROVAL: _send
DRAFT --> ON_SIGN: _send
ON_APPROVAL --> ON_SIGN: согласовано
ON_APPROVAL --> COMPLETED: согласовано
ON_SIGN --> COMPLETED: подписано
ON_APPROVAL --> REJECTED: _reject
ON_SIGN --> REJECTED: _reject
ON_APPROVAL --> CHANGE_REQUESTED: _request_changes
ON_SIGN --> CHANGE_REQUESTED: _request_changes
ON_APPROVAL --> REVOKED: _revoke
ON_SIGN --> REVOKED: _revoke
COMPLETED --> [*]
```
Значения `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[]`.
```json theme={null}
{
"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 сотрудников](/ru/guides/employees/model) своим ключом.
## Видимость в списке
`GET /documents` показывает документы по инициатору и области прав владельца ключа.
Документ, доступный ключу только через участие в маршруте (грант участника), в
списке **не появится** — но `GET /documents/{document_id}` его вернёт.
Не полагайтесь на список как на полный реестр видимых документов. Если у вас есть
идентификатор (например из вебхука), забирайте документ напрямую через
`GET /documents/{document_id}`.
## Дальше
Найдите шаблон и прочитайте его `variable_schema`.
Создать → маршрут → отправить → подписать → скачать.
Вебхуки `document.*` и реакция на смену статуса.