Главная / Документация / APIAPI: согласованияМаршруты согласования volrix.pm: шаблоны маршрутов, заявки, решения участников, заместители, файлы и лист согласования. Права и примеры.Обновлено 27.09.2026Согласование в volrix.pm строится из двух частей. **Маршрут** (/approval-routes) - шаблон: этапы, участники и требование подписанта. **Заявка** (/approval-requests) - запуск маршрута для конкретного объекта: документа, письма, поручения, задачи и других. Участники принимают решения по своим шагам, после согласования заявку можно передать на подписание.**Что принимает API-ключ.** Маршруты, создание и чтение заявок, файлы, лист согласования и история - по скоупам approval_routes:... и approvals:.... Решения по шагам (согласовать, отклонить, делегировать), отмена заявки и заместители выполняются только в сессии самого участника: решение нельзя принять за другого человека ключом.Базовый адрес, формат ответов и коды ошибок описаны в статье API: адрес, первый запрос и ответы, выпуск ключа и вход под пользователем - в статье API: вход, токен и API-ключи. В примерах ключ лежит в переменной окружения VOLRIX_API_KEY, токен пользователя - в VOLRIX_TOKEN.Типовой сценарий

Выберите маршрут GET /api/v1/approval-routes (approval_routes:read) - нужен route_id.

Запустите заявку POST /api/v1/approval-requests с телом RequestCreate (approvals:create). Обязательны route_id, title и target_type; target_id - согласуемый объект.

Дождитесь решений Участник вызывает POST /approval-requests/{request_id}/steps/{step_id}/approve, .../reject (comment обязателен) или .../delegate.

Следите за ходом GET /api/v1/approval-requests/{request_id} и .../history (approvals:read); лист согласования - GET .../pdf.

Передайте на подпись POST .../send-to-signing (approvals:update) передает согласованную заявку подписанту; в теле можно указать signer_id и comment.

Статус заявки

Значение

in_progress

Идет согласование

approved

Согласовано

on_signing

Согласовано и передано подписанту

signed

Подписано

rejected

Отклонено на одном из этапов

returned_to_initiator

Возвращено инициатору

cancelled

Отменено инициатором

Шаг участника проходит статусы waiting, in_progress, approved, rejected или delegated. Возврат инициатору не мешает новой подаче: прежняя попытка и комментарии остаются в истории (0.110.5).Примеры запросовВсе заявки по объекту, по ключу (скоуп approvals:read):curl --fail-with-body -sS \ -H "X-Api-Key: $VOLRIX_API_KEY" \ "https://ваш-адрес/api/v1/approval-requests?target_type=custom_document&target_id=5d0c..."Решение участника от его имени (сессия):curl --fail-with-body -sS -X POST \ -H "Authorization: Bearer $VOLRIX_TOKEN" \ -H "Content-Type: application/json" \ -d '{"comment": "Замечаний нет"}' \ "https://ваш-адрес/api/v1/approval-requests/{request_id}/steps/{step_id}/approve"МаршрутыКак читать колонку «Доступ»: **скоуп вида users:read** - маршрут принимает API-ключ, если в ключе есть этот скоуп, а у сотрудника, выпустившего ключ, есть такое же право в роли (users.read). Если скоупов несколько через «+», нужны все. **Только сессия** - нужен заголовок Authorization: Bearer, API-ключ получит 403. **Без авторизации** - заголовки не нужны. Доступ к конкретному объекту (участие в проекте, права на папку Диска) сервер проверяет дополнительно. Пути в таблицах указаны полностью, от корня сервера.Маршруты согласования

Метод и путь

Параметры и тело

Доступ (скоуп ключа)

Успешный ответ

GET /api/v1/approval-routes

is_active [query]: boolean / null; family [query]: DocumentFamily / null

approval_routes:read

200: array[RouteListItem]

POST /api/v1/approval-routes

Нет | Тело: application/json: RouteCreate

approval_routes:create

201: object

GET /api/v1/approval-routes/{route_id}

route_id [path обяз.]: string (uuid)

approval_routes:read

200: object

PUT /api/v1/approval-routes/{route_id}

route_id [path обяз.]: string (uuid) | Тело: application/json: RouteUpdate

approval_routes:update

200: object

DELETE /api/v1/approval-routes/{route_id}

route_id [path обяз.]: string (uuid)

approval_routes:delete

204

Заявки на согласование и решения

Метод и путь

Параметры и тело

Доступ (скоуп ключа)

Успешный ответ

POST /api/v1/approval-requests

Нет | Тело: application/json: RequestCreate

approvals:create

201: object

GET /api/v1/approval-requests

only_mine [query]: boolean (default=false); only_assigned [query]: boolean (default=false); target_type [query]: string / null; target_id [query]: string (uuid) / null

approvals:read

200: object

GET /api/v1/approval-requests/eligible-signers

target_type [query обяз.]: string; target_id [query]: string (uuid) / null; power_code [query]: string / null

approvals:create

200: object

POST /api/v1/approval-requests/attachments

Нет | Тело: multipart/form-data: Body_upload_approval_attachment_api_v1_approval_requests_attachments_post

approvals:create

200: object

GET /api/v1/approval-targets/{target_type}/{target_id}

target_type [path обяз.]: string; target_id [path обяз.]: string (uuid)

approvals:read

200: object

GET /api/v1/approval-requests/{request_id}

request_id [path обяз.]: string (uuid)

approvals:read

200: object

POST /api/v1/approval-requests/{request_id}/steps/{step_id}/approve

request_id [path обяз.]: string (uuid); step_id [path обяз.]: string (uuid) | Тело: application/json: _ApproveBody

Только сессия

200: object

POST /api/v1/approval-requests/{request_id}/steps/{step_id}/reject

request_id [path обяз.]: string (uuid); step_id [path обяз.]: string (uuid) | Тело: application/json: _RejectBody

Только сессия

200: object

POST /api/v1/approval-requests/{request_id}/steps/{step_id}/delegate

request_id [path обяз.]: string (uuid); step_id [path обяз.]: string (uuid) | Тело: application/json: _DelegateBody

Только сессия

200: object

POST /api/v1/approval-requests/{request_id}/cancel

request_id [path обяз.]: string (uuid) | Тело: application/json: _CancelBody

Только сессия

200: object

POST /api/v1/approval-requests/{request_id}/send-to-signing

request_id [path обяз.]: string (uuid) | Тело: application/json: _SendToSigningBody

approvals:update

200: object

GET /api/v1/approval-requests/{request_id}/files

request_id [path обяз.]: string (uuid)

approvals:read

200: object

POST /api/v1/approval-requests/{request_id}/files

request_id [path обяз.]: string (uuid) | Тело: multipart/form-data: Body_upload_request_file_api_v1_approval_requests__request_id__files_post

approvals:update

201: object

GET /api/v1/approval-requests/{request_id}/pdf

request_id [path обяз.]: string (uuid)

approvals:read

200: object

GET /api/v1/approval-requests/{request_id}/history

request_id [path обяз.]: string (uuid)

approvals:read

200: object

Заместители

Метод и путь

Параметры и тело

Доступ (скоуп ключа)

Успешный ответ

GET /api/v1/me/substitutes

Нет

Только сессия

200: object

POST /api/v1/me/substitutes

Нет | Тело: application/json: SubstituteCreate

Только сессия

201: object

DELETE /api/v1/me/substitutes/{substitute_id}

substitute_id [path обяз.]: string (uuid)

Только сессия

204

Тела запросовПоля JSON и форм multipart из схемы сервера. «Да» - поле обязательно. Ссылка на другую схему (например, array[QCApproverInput]) означает вложенный объект с теми же полями.RouteCreate: POST /approval-routes

Поле

Обязательно

Тип / значения

Ограничения

name

Да

string

minLength=1; maxLength=255

description

Нет

string / null

is_active

Нет

boolean

default=true

is_default_for_qc

Нет

boolean

default=false

is_default_for_stage

Нет

boolean

default=false

requires_signer

Нет

boolean

default=false

required_signer_power_code

Нет

string / null

family

Нет

string: project, ord, pud, contract, letter, memo, other

default="other"

stages

Нет

array[StageInput]

default=[]

RouteUpdate: PUT /approval-routes/{route_id}

Поле

Обязательно

Тип / значения

Ограничения

name

Нет

string / null

description

Нет

string / null

is_active

Нет

boolean / null

is_default_for_qc

Нет

boolean / null

is_default_for_stage

Нет

boolean / null

requires_signer

Нет

boolean / null

required_signer_power_code

Нет

string / null

family

Нет

string: project, ord, pud, contract, letter, memo, other / null

stages

Нет

array[StageInput] / null

RequestCreate: POST /approval-requests

Поле

Обязательно

Тип / значения

Ограничения

route_id

Да

string (uuid)

title

Да

string

minLength=1; maxLength=500

target_type

Да

string: qc_document, project_task, order, standalone, incoming_letter, outgoing_letter, project, custom_document, change_request, storage_document

target_id

Нет

string (uuid) / null

attached_file_url

Нет

string / null

started_on

Нет

string (date) / null

preamble

Нет

string / null

contractor_id

Нет

string (uuid) / null

signer_id

Нет

string (uuid) / null

signer_poa_id

Нет

string (uuid) / null

extra_participants

Нет

array[RequestExtraParticipant]

default=[]

Форма multipart: POST /approval-requests/attachments

Поле

Обязательно

Тип / значения

Ограничения

file

Да

string (binary)

_ApproveBody: POST /approval-requests/{request_id}/steps/{step_id}/approve

Поле

Обязательно

Тип / значения

Ограничения

comment

Нет

string / null

_RejectBody: POST /approval-requests/{request_id}/steps/{step_id}/reject

Поле

Обязательно

Тип / значения

Ограничения

comment

Да

string

_DelegateBody: POST /approval-requests/{request_id}/steps/{step_id}/delegate

Поле

Обязательно

Тип / значения

Ограничения

substitute_employee_id

Да

string (uuid)

comment

Нет

string / null

_CancelBody: POST /approval-requests/{request_id}/cancel

Поле

Обязательно

Тип / значения

Ограничения

comment

Нет

string / null

_SendToSigningBody: POST /approval-requests/{request_id}/send-to-signing

Поле

Обязательно

Тип / значения

Ограничения

signer_id

Нет

string (uuid) / null

comment

Нет

string / null

Форма multipart: POST /approval-requests/{request_id}/files

Поле

Обязательно

Тип / значения

Ограничения

file

Да

string (binary)

comment

Нет

string / null

kind

Нет

string

default="revision"

SubstituteCreate: POST /me/substitutes

Поле

Обязательно

Тип / значения

Ограничения

substitute_employee_id

Да

string (uuid)

Вложенный объект StageInput

Поле

Обязательно

Тип / значения

Ограничения

name

Да

string

minLength=1; maxLength=255

stage_type

Да

string: parallel, sequential

purpose

Нет

string: approve, consult, inform

default="approve"

sort_order

Да

integer

duration_days

Нет

integer

default=3; minimum=0.0; maximum=365.0

participants

Нет

array[ParticipantInput]

default=[]

Вложенный объект RequestExtraParticipant

Поле

Обязательно

Тип / значения

Ограничения

stage_sort_order

Да

integer

employee_id

Да

string (uuid)

is_required

Нет

boolean

default=true

Вложенный объект ParticipantInput

Поле

Обязательно

Тип / значения

Ограничения

participant_type

Да

string: role, employee

role_code

Нет

string / null

employee_id

Нет

string (uuid) / null

is_required

Нет

boolean

default=true

sort_order

Нет

integer

default=0

Значения перечислений

Тип

Допустимые значения

DocumentFamily

project, ord, pud, contract, letter, memo, primary, other

Если не получается

Что видно

Причина и что сделать

403 «API-ключи не поддерживаются на этом эндпоинте»

У маршрута в таблице указано «Только сессия». Выполните его с заголовком Authorization: Bearer от имени сотрудника, см. вход под пользователем.

422 на target_type

Значение вне списка RequestCreate: qc_document, project_task, order, standalone, incoming_letter, outgoing_letter, project, custom_document, change_request, storage_document.

422 «Этот шаг назначен другому сотруднику»

Решение принимает только участник шага. Выполните запрос под его токеном или делегируйте шаг (POST .../delegate).

422 «Этап не активен» или «Заявка в статусе ...»

Шаг еще не наступил или заявка уже завершена. Перечитайте заявку: GET /approval-requests/{request_id}.

403 «API-ключ не имеет права (...)»

В ключе нет скоупа из колонки «Доступ». Скоупы после создания не меняются: выпустите новый ключ с нужным скоупом в «Администрирование» → «Настройки продукта» → «Интеграции» и отзовите старый.

403 «Недостаточно прав (...)»

У пользователя или у сотрудника, выпустившего ключ, нет названного права в роли (с 0.110.6 для ключа проверяются и скоуп, и право владельца). Добавьте право в роль: «Администрирование» → «Доступ» → «Роли и права».

423 на POST, PUT, PATCH или DELETE, чтение работает

Нет действующей лицензии (в ответе license_status: expired, invalid, missing или mismatch). Изменения заблокированы до загрузки файла лицензии, см. Лицензия.

Согласования

Маршруты согласования

Подписание

Запустить маршрут и принять решениеЭтапы, участники и контрольный запускПодготовка рабочего места и проверка

Интеграции и REST API

Функциональная карта