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

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

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

Выберите шаблон

Найдите активный шаблон приказа и запомните template_id и template_version. Схему переменных (variable_schema) для template_values возьмите из карточки шаблона — подробнее в руководстве по шаблонам.

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

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

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

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.

Задайте маршрут подписания

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

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 — маршрут пока только описан.

Отправьте по маршруту

Запустите маршрут. По умолчанию initial_action = SEND_INITIAL_ACTION_SEND_ONLY: документ уходит подписанту, а статус переходит в DOCUMENT_STATUS_ON_SIGN.

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" }'

Подпишите

Подпись всегда формируется на стороне клиента: сервер её только проверяет и записывает. Ахмет подписывает своим ключом через NCALayer (десктоп) или eGov Mobile, получает готовую base64 CMS/ЭЦП и передаёт её в _sign.participant_id — это идентификатор активного слота подписанта; возьмите его из route.steps[].participants[].id, прочитав документ через GET /documents/{id}.

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"
  }'

Как получить base64-подпись из NCALayer или eGov Mobile — в руководстве по подписанию. Здесь важно одно: готовую ЭЦП вы передаёте в signature, а сервер её валидирует.

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

Скачайте подписанный PDF

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

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.

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

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

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

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

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

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"] }'

Дальше

Подписание

NCALayer, eGov Mobile и формирование base64-ЭЦП.

Шаблоны документов

Как читать variable_schema и заполнять template_values.

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

Сотрудники

Документы

Рецепты

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

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

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

Дальше

Подписание

Шаблоны документов

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

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

​Дальше

Подписание

Шаблоны документов

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

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

Дальше