Core trade

Завести продажу

Заводит черновик продажи (серия ЗКЛ); confirm: true сразу подтверждает его той же транзакцией — обязательство встаёт в регистр «Продажи и закупки». Номер пустой — его выдаёт счётчик вида, свой номер берётся как есть. Скидка продажи раскладывается по строкам пропорционально их суммам до разложения НДС. Читает Idempotency-Key: повтор с тем же ключом отдаёт заведённую продажу, а не вторую. Ответ — карточка продажи.

post/api/v1/core/sales

Request

  • Base URL: https://erp.akeda.ru
  • URL: https://erp.akeda.ru/api/v1/core/sales
  • 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

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

side'sale' | 'purchase' required
numberstring

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

datestring date required
business_idstring uuid
company_idstring uuid
contact_idstring uuid
contract_idstring uuid
channel_idstring uuid
price_below_min_reasonstring

Причина продажи ниже минимальной цены; принимается только с правом core.price_below_min и пишется в журнал продажи

project_idstring uuid
department_idstring uuid
cfo_idstring uuid
pnl_item_idstring uuid
warehouse_idstring uuid
basis_idstring uuid
titlestring
currencystring required
prices_include_vatboolean

Цены с НДС («в том числе»); по умолчанию true

discountstring

Скидка на продажу или закупку целиком; раскладывается по строкам пропорционально их суммам до НДС

delivery_datestring date
due_datestring date
scenario'one_off_sale' | 'contract_sale' | 'self_service'
manager_notestring
warehouse_notestring
commentstring
cabinet_status_idstring uuid
confirmboolean

Сразу подтвердить созданный продажу или закупку

Response

Карточка заведённой продажи

idstring uuid required
side'sale' | 'purchase' required
type_key'customer_order' | 'supplier_order' required
numberstring required
datestring date required
document_status'draft' | 'posted' | 'cancelled' required
state'draft' | 'confirmed' | 'executing' | 'executed' | 'closed' | 'cancelled' required
business_idstring uuid required
company_idstring uuid
contact_idstring uuid required
business_namestring
company_namestring
contact_namestring
contract_idstring uuid
channel_idstring uuid
channel_namestring
contract_numberstring

Номер договора продажи или закупки — для экрана

contract_datestring date

Дата договора продажи или закупки — для экрана

project_idstring uuid
department_idstring uuid
cfo_idstring uuid
pnl_item_idstring uuid
execution_cutoverboolean

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

warehouse_idstring uuid
basis_idstring uuid
titlestring required
currencystring required
prices_include_vatboolean required
discountstring required

Скидка на продажу или закупку целиком, как её ввели; в суммах строк уже учтена

delivery_datestring date
due_datestring date
scenariostring required
manager_notestring
warehouse_notestring
commentstring
source_kind'manual' | 'app' | 'import' | 'marketplace' | 'crm' | 'migration' | 'contract' required

Откуда продажа или закупка. contract — продажа или закупка периода регулярного договора документооборота (commerce-cycle.md § 2.6): его external_id — «<id договора>/<период>» (2026-10, 2026-Q4, 2026-W41), и загрузка с тем же внешним номером отвечает core.trade.foreign_source.

source_systemstring
external_idstring
cabinet_status_idstring uuid
cabinet_status_namestring
sale_order_idstring uuid
sale_order_numberstring

Номер этой продажи

funnel_idstring uuid
versioninteger required
closed_atstring
closed_reasonstring
close_document_idstring uuid
migrated_fromstring
created_byinteger
created_atstring date-time required
updated_atstring date-time required
posted_atstring
cancelled_atstring
unchangedboolean

Только в ответах команд подтверждения, отмены и возврата в работу: true — команде нечего было делать (подтверждена уже, отменена уже, не закрыта), заказ не изменился. Повтор команды отвечает той же карточкой, а не ошибкой

Changes

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