Finance settlements

Создать типизированный документ взаиморасчётов

Вид документа определяет обязательные связи и сумму; продажи и закупки требуют статью ОПиУ, распределение оплаты — обязательство и оплату, зачёт аванса — аванс и обязательство. Документ без юрлица принадлежит бизнесу: его передают полем business_id в теле или параметром business; разные значения в теле и параметре — ответ 400. Читает Idempotency-Key — повтор того же запроса с тем же ключом отдаёт созданный документ, а не второй. Продажа и закупка вдобавок узнают повтор по внешнему ключу source_system + source_ref + external_id, но его знает только интеграция, которая его ведёт; остальные виды документов без заголовка ничем от дубля не защищены.

post/api/v1/finance/settlements/documents

Request

Base URL: https://erp.akeda.ru
URL: https://erp.akeda.ru/api/v1/finance/settlements/documents
Auth: one of:
- HTTP bearer
- API key in header X-Api-Key
- OAuth 2 (authorization code, authorization URL https://erp.akeda.ru/oauth2/authorize, token URL https://erp.akeda.ru/oauth2/token, scopes: akeda:delegate)
- HTTP bearer

Query parameters

businessstring uuid

UUID управленческого бизнеса; без параметра — консолидация «Весь бизнес»

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

numberstring

datestring date

company_idstring uuid

business_idstring uuid

Бизнес документа без юрлица; то же, что параметр business, при расхождении — 400

contact_idstring uuid required

currencystring required

amountstring

Положительная decimal string для долгов, авансов, сделок, зачёта и распределения

due_datestring date

Обязательна для долга, продажи и закупки

obligation_idstring uuid

Обязательно для зачёта аванса, распределения оплаты и возврата по продаже (продажа-основание)

payment_idstring uuid

Оплата-источник аванса либо обязательная оплата для распределения

advance_idstring uuid

Обязателен для зачёта аванса и переноса аванса между контрагентами (finance_advance_contact_transfer): переносимый аванс; контрагент документа — получатель, источник — тот, за кем числится остаток

order_idstring uuid

Продажа или закупка: у аванса — его заказ, у переноса аванса между контрагентами — заказ получателя; пусто — без заказа

pnl_item_idstring uuid

Обязательна для продажи и закупки

project_idstring uuid

Путешествие или проект продажи и закупки

side'receivable_advance' | 'payable_advance'

Обязательна только для аванса

stock_return_idstring uuid

Только возврат по продаже: складской возврат от покупателя по этой продаже; без amount сумма — доля продажи по количеству

commentstring

source_systemstring

Ключ идемпотентности сделки (только продажа и закупка): система-источник — учётная система клиента или ключ стороннего приложения

source_refstring

Какая именно база/кабинет клиента внутри source_system; пусто — единственный источник

external_idstring

Идентификатор сделки в source_system; повтор того же (source_system, source_ref, external_id) возвращает уже созданный документ вместо второго

vat_amountstring

Только закупка: «в т.ч. НДС» документа поставщика (ERP-484, подшаг 5.3). Обязательна, если на дату бизнес очищает суммы и юрлицо принимает налог к вычету; 0 — налог не выделен. Вне периода непустое значение — 400

prices_include_vatboolean

Только вместе со строками: цены строк включают налог (умолчание) либо налог начисляется сверху

Response

Черновик документа

idstring uuid required

type_idstring uuid required

type_keystring required

type_namestring required

numberstring required

datestring date required

status'draft' | 'posted' | 'cancelled' required

basis_typestring uuid required

basis_idstring uuid required

basis_numberstring required

entity_refsobject required

payloadobject required

commentstring required

is_marked_deletedboolean required

created_byinteger nullable required

created_by_namestring required

created_atstring date-time required

updated_atstring date-time required

posted_atstring required

cancelled_atstring required

customobject

Значения своих полей кабинета (графы вида core.document.<ключ вида>). Отдаёт карточка документа; списки поле не несут

Changes

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