Docflow flow

Открыть сессию загрузки файла в документ

Файл кладётся прямо в хранилище кабинета по подписанному адресу, мимо API: так прикладывает файл агент по MCP и клиент с крупным файлом. Ожидаемая версия документа передаётся в теле, заголовок Idempotency-Key обязателен: оба называются сейчас, а проверяются командой документа при завершении. Один ключ — одна сессия: повтор ключа отвечает 422 docflow.flow.idempotency_conflict. Ответ называет путь байтов: post — один multipart POST на upload.url с полями upload.fields и файлом последним полем upload.file_field; parts — PUT каждой части на upload.direct_urls; api — хранилище подписывать не умеет, байты идут PUT на upload.url этого API с авторизацией. Затем docflowFinishFlowUploadSession. Предел файла 100 МБ, файлов у документа не больше ста; уже изменённый документ отвечает 409 docflow.flow.version_conflict.

post/api/v1/docflow/flow/documents/{id}/upload-sessions

Request

Base URL: https://erp.akeda.ru
URL: https://erp.akeda.ru/api/v1/docflow/flow/documents/{id}/upload-sessions
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

Ожидаемая версия документа

replace_idstring uuid

namestring required

Имя файла с расширением, без пути

mime_typestring

size_bytesinteger required

Точный размер файла в байтах

sha256string

Необязательная контрольная сумма SHA-256 строчными шестнадцатеричными знаками

Response

Сессия и адрес для байтов

idstring uuid required

owner_typestring required

owner_idstring

namestring required

mime_typestring required

size_bytesinteger required

sha256string

attributesobject

status'pending' | 'processing' | 'attached' | 'failed' | 'expired' required

failure_detailstring

scan_status'pending' | 'clean' | 'infected' | 'skipped'

scan_verdictstring

published_refstring

Номер строки, заведённой по файлу; у почты — id загрузки для upload_ids

expires_atstring date-time required

created_atstring date-time required

completed_atstring date-time

Changes

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