Docflow flow

Выполнить команду правки документа

Все правки идут одной командой с полем action, и каждая принятая команда рождает НОВУЮ неизменяемую редакцию — прежняя остаётся читаемой по своему адресу. Правка снимков задним числом не бывает.

Поле expected_version обязательно в каждой команде: это защита от одновременной правки, и передаётся она полем ТЕЛА, а не заголовком. Разошлась с текущей версией — 409 docflow.flow.version_conflict, и клиент обязан перечитать документ, а не повторять с тем же числом.

Команда custom меняет только свои поля кабинета — у черновика и у зарегистрированной карточки: это пометки кабинета, а не текст бумаги, и каждая правка остаётся редакцией в истории.

Команды save, link, unlink и remove_file работают только по черновику; register переводит его в зарегистрированный, revise возвращает в черновик, archive и restore ведут архив. Стороны и вид документа, уже закреплённые зарегистрированной редакцией или учётной связью, не меняются вовсе — отказ docflow.flow.identity_locked.

Команда articles вписывает ручной артикул и код товара строк своего счёта, акта, накладной, УПД или УКД (line_articles: line_id, article до 50 знаков, code до 100; пустое значение снимает правку). Работает у черновика и у зарегистрированной бумаги до своей КЭП под файлом и до отправки по ЭДО — после 409 docflow.flow.line_articles_locked. Ручной артикул сильнее настройки покупателя и уходит в XML и графу «Код» бланка.

Команда delete удаляет ТОЛЬКО чистый черновик: без учётных связей, без связи-основания с другой карточкой (в любую сторону), без отправки по ЭДО и без согласования. Во всех остальных случаях — 409 docflow.flow.state_conflict. Файлы карточки уходят из объектного хранилища отдельным шагом после команды; сама карточка помечается статусом deleted и больше не читается ни одним обычным путём — физического удаления строки нет, редакция остаётся следом в истории/аудите кабинета.

Заголовок Idempotency-Key обязателен, как и у остальных команд крыла.

post/api/v1/docflow/flow/documents/{id}/commands

Request

  • Base URL: https://erp.akeda.ru
  • URL: https://erp.akeda.ru/api/v1/docflow/flow/documents/{id}/commands
  • Auth: one of:
    • HTTP bearer
    • OAuth 2 (authorization code, authorization URL https://erp.akeda.ru/oauth2/authorize, token URL https://erp.akeda.ru/oauth2/token, scopes: akeda:delegate)

Path parameters

idstring uuid required

Headers

X-Tenantstring required

Slug выбранного кабинета; кабинет не является юрлицом

Idempotency-Keystring

Ключ одной логической попытки команды. Единственная форма идемпотентности на уровне HTTP; читают его только операции, у которых этот параметр объявлен.

Повтор ТОГО ЖЕ запроса (метод, адрес с параметрами, тело) с тем же ключом не выполняет команду второй раз, а отдаёт первый успешный ответ с заголовком Idempotent-Replay: true. Тот же ключ с другим запросом — отказ 422 idempotency.key_mismatch, а не чужой ответ. Пока первая попытка ещё выполняется, повтор получает 409 idempotency.in_progress и Retry-After: он не ждёт и не выполняется второй раз.

Ключ принадлежит предъявителю в кабинете: человеку, кабинетному API-ключу или установке приложения. Одинаковый ключ у соседа — другая попытка.

Отказ 4xx ключ ОСВОБОЖДАЕТ: запрос отклонён до работы, в кабинете не изменилось ничего, и исправленный запрос с тем же ключом выполняется. Отказ 5xx ключ ЗАПИРАЕТ: записалось или нет — неизвестно, коммит мог случиться, а ответ до вас не доехать. Повтор с тем же ключом получает тот же статус и тот же машинный код, а команда второй раз не выполняется. Чтобы попробовать снова, прочитайте отдельным запросом, появился ли результат, и возьмите НОВЫЙ ключ.

И ответ, и запомненный отказ живут сутки; после этого тот же ключ — новая попытка, и команда выполняется заново. Ответы, несущие секрет (выдача токена, аренда секрета настройки), заголовок не читают: секрет отдаётся ровно один раз. Хранилище недоступно — 503 idempotency.unavailable, команда без защиты не выполняется; этот отказ приходит ДО заявки на ключ и потому ключ не тратит.

Для естественного ключа интеграции годится любая строка вида crm:order:123:create; UUID не обязателен.

Request body

expected_versioninteger required

Версия, которую видел клиент. Разошлась — 409 docflow.flow.version_conflict

action'save' | 'link' | 'unlink' | 'remove_file' | 'register' | 'revise' | 'archive' | 'restore' | 'delete' | 'custom' | 'articles' required
customobject

Для action=custom: значения своих полей целиком. Правятся у черновика и зарегистрированной карточки; значение, не подходящее к типу графы, — 422 с названиями граф

company_idstring uuid
contact_idstring uuid
kind'contract' | 'specification' | 'amendment' | 'invoice' | 'act' | 'upd' | 'goods_waybill' | 'transport_waybill' | 'consignment_note' | 'transport_order' | 'tax_invoice' | 'correction' | 'return' | 'discrepancy_act' | 'reconciliation_act' | 'power_of_attorney' | 'other'

Вид документа внутреннего контура. Вид называет бумагу, а не учётную операцию: продажу и закупку из бумаги делают отдельные команды.

direction'incoming' | 'outgoing' | 'internal'
file_idstring uuid
relation_idstring uuid

Response

Документ после команды

idstring uuid required
company_idstring uuid required
business_idstring uuid

Бизнес бумаги. У бумаги без юрлица (company_id — нулевой id) он один называет сторону «мы»; в печати стоит его название

execution_cutoverboolean

Бизнес юрлица бумаги прошёл отсечку этапа 4: мастер «Принять акт» и «Создать продажу / закупку» у бумаги сняты

company_namestring required
contact_idstring uuid required
contact_namestring required
kind'contract' | 'specification' | 'amendment' | 'invoice' | 'act' | 'upd' | 'goods_waybill' | 'transport_waybill' | 'consignment_note' | 'transport_order' | 'tax_invoice' | 'correction' | 'return' | 'discrepancy_act' | 'reconciliation_act' | 'power_of_attorney' | 'other' required

Вид документа внутреннего контура. Вид называет бумагу, а не учётную операцию: продажу и закупку из бумаги делают отдельные команды.

direction'incoming' | 'outgoing' | 'internal' required
status'draft' | 'registered' | 'archived' required
archived_from'draft' | 'registered'

Из какого состояния бумага ушла в архив

versioninteger required
identity_editableboolean required

Ложь означает: стороны и вид уже закреплены редакцией или связью и не меняются

gapsstring[]

Чего карточке не хватает до полноты: содержательного файла, подтверждённой суммы, срока действия (последний — только у договора и дополнительного соглашения). Считается при чтении одной карточки и в редакцию не пишется. Пустой список у карточки из ЭДО означает, что приёмка зарегистрировала её сразу; непустой — что карточка осталась черновиком и ждёт подтверждения человека.

created_atstring date-time required
updated_atstring date-time required
updated_byinteger required

Changes

No recorded changes to this operation across all 1 revision of this API.