Согласовать документ как участник

Интегратор не всегда создаёт документы — часто он действует на стороне согласующего: система на вашей стороне решает, согласовать приказ или вернуть его на доработку, и должна сделать это через API. Всё ниже требует области documents:write, а чтение документа — documents:read.

Документ, доступный вам только через участие в маршруте, не появляется в GET /documents: реестр перечисляет документы по инициатору и по правам. Поэтому единственный надёжный вход в этот сценарий — события. Подробнее в Списке документов.

Подпишитесь на события согласования

curl -X POST -H "X-API-Key: $DOODOCS_API_KEY" -H "Content-Type: application/json" \
  https://app.doodocs.kz/api/developer/v1/webhook_endpoints \
  -d '{
    "url": "https://ваш-сервер/hooks/doodocs",
    "event_types": ["document.approval_started", "document.change_requested", "document.completed"]
  }'

Событие приносит {"document_id": "…"} — этого достаточно, чтобы прочитать документ своим ключом.

Прочитайте документ вместе с маршрутом

curl -H "X-API-Key: $DOODOCS_API_KEY" \
  https://app.doodocs.kz/api/developer/v1/documents/8c2d5a91-…

{
  "document": {
    "id": "8c2d5a91-…",
    "status": "DOCUMENT_STATUS_ON_APPROVAL",
    "route": {
      "is_active": true,
      "steps": [
        {
          "id": "st_1…",
          "index": 0,
          "step_type": "STEP_TYPE_APPROVAL",
          "rule": "STEP_RULE_ALL",
          "status": "STEP_STATUS_ACTIVE",
          "participants": [
            {
              "id": "pt_9f…",
              "employee_id": "3f2a9c7e-…",
              "status": "PARTICIPANT_STATUS_ACTIVE"
            }
          ]
        }
      ]
    }
  }
}

Найдите свой слот

Нужен участник, у которого employee_id совпадает с карточкой владельца ключа, а status равен PARTICIPANT_STATUS_ACTIVE. Именно его id передаётся в действие.

def my_active_slot(document: dict, my_employee_id: str) -> str | None:
    for step in document["route"]["steps"]:
        if step["status"] != "STEP_STATUS_ACTIVE":
            continue
        for p in step["participants"]:
            if p["employee_id"] == my_employee_id and p["status"] == "PARTICIPANT_STATUS_ACTIVE":
                return p["id"]
    return None

Эндпоинта «кто я» в Developer API нет. Сохраните employee_id владельца ключа в конфигурации интеграции — он не меняется, пока владелец работает в той же организации.

Выполните действие

curl -X POST -H "X-API-Key: $DOODOCS_API_KEY" -H "Content-Type: application/json" \
  https://app.doodocs.kz/api/developer/v1/documents/8c2d5a91-…/_approve \
  -d '{ "participant_id": "pt_9f…", "comment": "Согласовано" }'

Действие	Эндпоинт	Комментарий	Результат
Согласовать	`_approve`	не обязателен	шаг движется дальше
Отклонить	`_reject`	обязателен	`DOCUMENT_STATUS_REJECTED`
Вернуть на доработку	`_request_changes`	обязателен	`DOCUMENT_STATUS_CHANGE_REQUESTED`

Правила прохождения шага

rule определяет, когда шаг закрывается:

STEP_RULE_ALL — нужны действия всех участников шага;
STEP_RULE_ANY_ONE — достаточно одного, остальные слоты получат PARTICIPANT_STATUS_SKIPPED.

Поэтому не считайте, что ваше согласование завершит шаг: после ответа перечитайте документ либо дождитесь document.signing_started или document.completed.

Ошибки, которые стоит обработать

Ситуация	Что вернётся
Слот уже отработал или шаг не активен	`400`, ошибка состояния документа
Передан чужой `participant_id`	`404` `DOCUMENT_NOT_FOUND`
Документ недоступен ключу	`404` `DOCUMENT_NOT_FOUND`
Нет области `documents:write`	`403` `DEVELOPER.SCOPE_INSUFFICIENT`

Повторный _approve на отработавшем слоте безопасен: он не создаёт второго согласования, а возвращает ошибку состояния.

Дальше

События документов

Полный список событий и что делать по каждому.

Подписание

Если ваш слот — подписывающий, а не согласующий.

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

Сотрудники

Документы

Рецепты

Согласовать документ как участник

Правила прохождения шага

Ошибки, которые стоит обработать

Дальше

События документов

Подписание

​Правила прохождения шага

​Ошибки, которые стоит обработать

​Дальше

События документов

Подписание

Правила прохождения шага

Ошибки, которые стоит обработать

Дальше