> ## 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.

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

> Создать приказ, провести по маршруту и получить подписанный PDF

Пройдём весь путь на живом примере: ТОО «Керуен» выпускает приказ о приёме на
работу для Куляш Байсеитовой, отправляет его на подпись руководителю
Ахмету Байтурсынову и скачивает готовый PDF.

<Note>
  Чтение справочников и документа требует области `documents:read`, а создание,
  маршрут, отправка и подпись — `documents:write`.
</Note>

<Steps>
  <Step title="Выберите шаблон">
    Найдите активный шаблон приказа и запомните `template_id` и `template_version`.
    Схему переменных (`variable_schema`) для `template_values` возьмите из карточки
    шаблона — подробнее в [руководстве по шаблонам](/ru/guides/documents/templates).

    ```bash theme={null}
    curl -H "X-API-Key: ddp_ВАШ_КЛЮЧ" \
      "https://app.doodocs.kz/api/developer/v1/document_templates?search=Приказ%20о%20приёме"
    ```
  </Step>

  <Step title="Создайте документ">
    Соберите документ из шаблона. Значения в `template_values` должны
    соответствовать `variable_schema`, а получатель приказа задаётся в
    `subject_employee_ids`. Инициатором станет сотрудник — владелец ключа
    (определяется сервером, подменить нельзя).

    ```bash theme={null}
    curl -X POST -H "X-API-Key: ddp_ВАШ_КЛЮЧ" -H "Content-Type: application/json" \
      https://app.doodocs.kz/api/developer/v1/documents \
      -d '{
        "title": "Приказ о приёме на работу",
        "type_id": "5c9e…",
        "template_id": "t7…",
        "template_version": 3,
        "template_values": { "position": "HR-менеджер", "start_date": "2026-03-01" },
        "subject_employee_ids": ["3f2a9c7e-…"]
      }'
    ```

    В ответе придёт документ со статусом `DOCUMENT_STATUS_DRAFT` и его `id`.
  </Step>

  <Step title="Задайте маршрут подписания">
    Черновику нужен маршрут. Для приказа достаточно одного шага подписания,
    назначенного на руководителя Ахмета Байтурсынова.

    ```bash theme={null}
    curl -X PUT -H "X-API-Key: ddp_ВАШ_КЛЮЧ" -H "Content-Type: application/json" \
      https://app.doodocs.kz/api/developer/v1/documents/a1b2c3d4-…/route \
      -d '{
        "steps": [
          { "step_type": "STEP_TYPE_SIGNING", "rule": "STEP_RULE_ALL", "employee_ids": ["9a4f…"] }
        ]
      }'
    ```

    Документ остаётся в `DOCUMENT_STATUS_DRAFT` — маршрут пока только описан.
  </Step>

  <Step title="Отправьте по маршруту">
    Запустите маршрут. По умолчанию `initial_action` = `SEND_INITIAL_ACTION_SEND_ONLY`:
    документ уходит подписанту, а статус переходит в `DOCUMENT_STATUS_ON_SIGN`.

    ```bash theme={null}
    curl -X POST -H "X-API-Key: ddp_ВАШ_КЛЮЧ" -H "Content-Type: application/json" \
      https://app.doodocs.kz/api/developer/v1/documents/a1b2c3d4-…/_send \
      -d '{ "initial_action": "SEND_INITIAL_ACTION_SEND_ONLY" }'
    ```
  </Step>

  <Step title="Подпишите">
    Подпись всегда формируется на стороне клиента: сервер её только проверяет и
    записывает. Ахмет подписывает своим ключом через NCALayer (десктоп) или eGov
    Mobile, получает готовую base64 CMS/ЭЦП и передаёт её в `_sign`.

    `participant_id` — это идентификатор активного слота подписанта; возьмите его из
    `route.steps[].participants[].id`, прочитав документ через
    `GET /documents/{id}`.

    ```bash theme={null}
    curl -X POST -H "X-API-Key: ddp_ВАШ_КЛЮЧ" -H "Content-Type: application/json" \
      https://app.doodocs.kz/api/developer/v1/documents/a1b2c3d4-…/_sign \
      -d '{
        "participant_id": "p1…",
        "signature": "MIIF…base64-CMS…",
        "sign_method": "SIGN_METHOD_NCALAYER"
      }'
    ```

    <Tip>
      Как получить base64-подпись из NCALayer или eGov Mobile — в
      [руководстве по подписанию](/ru/guides/documents/signing). Здесь важно одно:
      готовую ЭЦП вы передаёте в `signature`, а сервер её валидирует.
    </Tip>

    Когда подписан последний требуемый шаг, документ переходит в
    `DOCUMENT_STATUS_COMPLETED`.
  </Step>

  <Step title="Скачайте подписанный PDF">
    Для завершённого документа запросите presigned-ссылку на итоговый файл.

    ```bash theme={null}
    curl -H "X-API-Key: ddp_ВАШ_КЛЮЧ" \
      "https://app.doodocs.kz/api/developer/v1/documents/a1b2c3d4-…/download?file_type=FILE_TYPE_PDF"
    ```

    В ответе — временная ссылка на подписанный PDF. Другие представления доступны
    через `file_type`: `FILE_TYPE_PREVIEW` (печатная форма), `FILE_TYPE_DDCARD`
    (карточка КЭД), `FILE_TYPE_DOCX`, `FILE_TYPE_JSON`.
  </Step>
</Steps>

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

```
DRAFT ──задать маршрут──▶ DRAFT ──_send──▶ ON_SIGN ──подписан последний шаг──▶ COMPLETED
```

Отклонение переводит документ в `DOCUMENT_STATUS_REJECTED`, запрос правок — в
`DOCUMENT_STATUS_CHANGE_REQUESTED`, отзыв инициатором — в `DOCUMENT_STATUS_REVOKED`.

## Узнавать о завершении

Чтобы не опрашивать статус, подпишитесь на событие `document.completed` и
скачивайте PDF по факту. События документов приходят по каждому документу тенанта и
несут только `document_id` и тайминги — не содержимое; доступ по-прежнему проверяет
`GET /documents/{id}`.

```bash theme={null}
curl -X POST -H "X-API-Key: ddp_ВАШ_КЛЮЧ" -H "Content-Type: application/json" \
  https://app.doodocs.kz/api/developer/v1/webhook_endpoints \
  -d '{ "url": "https://keruen.example/hooks/doodocs", "event_types": ["document.completed"] }'
```

## Дальше

<Columns cols={2}>
  <Card title="Подписание" icon="pen-nib" href="/ru/guides/documents/signing">
    NCALayer, eGov Mobile и формирование base64-ЭЦП.
  </Card>

  <Card title="Шаблоны документов" icon="file-lines" href="/ru/guides/documents/templates">
    Как читать `variable_schema` и заполнять `template_values`.
  </Card>
</Columns>