Документація API/Продажі/Замовлення

Замовлення

Замовлення клієнтів: із сайту, маркетплейсу чи від менеджера. З нього виставляються рахунки й відвантаження. Право ролі: order.

Маршрути

GET/order

Список замовлень з пагінацією, фільтрами й total.

право: order.view2 очк.

GET/order/{id}

Одна картка.

право: order.view1 очк.

GET/order/count

Лише кількість за тими самими фільтрами (голе число).

право: order.view2 очк.

POST/order

Створити.

право: order.create10 очк.

PUT/order/{id}

Оновити.

право: order.update10 очк.

DELETE/order/{id}

Видалити.

право: order.delete10 очк.

GET/order/document-products/{id}

Позиції з уже виставленою/відвантаженою й доступною кількістю, для часткових документів.

право: order.view2 очк.

POST/order/create-invoice/{id}

Виставити рахунок із замовлення.

право: invoice.create5 очк.

POST/order/create-shipment/{id}

Створити відвантаження.

право: shipment.create5 очк.

GET/order/deleted?since=...

Видалені записи, див. розділ Синхронізація.

право: order.view2 очк.

Усі поля

Обов’язкове лише name; валюта, статус і склад підставляються за замовчуванням. Теги й доп. поля описані в розділі Вкладені дані.

Поле	Тип	Обмеження	Опис
`name`обов.	рядок	≤ 60 симв.	Назва замовлення.
`external_id`	рядок	≤ 64 симв.	Ключ запису у вашій системі. Унікальний; пошук: filter[external_id;eq]. Див. «Синхронізація».
`exchange_rate`	десяткове (рядок)		Курс валюти до гривні на дату документа: десяткове число рядком, напр. "41.250000". Для гривні завжди 1; якщо для валюти курс не передано, береться курс довідника.
`repeat`	ціле	0 \| 1	Повторний (1) чи перший (0) продаж.
`description`	рядок	≤ 1024 симв.	Опис / коментар.
`is_reserved`	bool		Товар зарезервовано на складі.
`date`	дата-час		Дата замовлення.
`closed_date`	дата-час		Дата закриття.
`status_id`	id		Статус (/lookup?type=ord_status). Якщо не передано, ставиться статус за замовчуванням.
`vat_id`	id		Ставка ПДВ (/lookup?type=tax).
`price_includes_vat`	bool		Ціни вказано з ПДВ.
`currency_id`	id		Валюта (/currency).
`address_id`	id		Адреса доставки (/address).
`source_id`	id		Джерело (/lookup?type=source).
`owner_id`	id		Відповідальний користувач (/user). Якщо не передано, це користувач токена.
`contact_id`	id		Контакт (/contact).
`stock_id`	id		Склад відвантаження. Якщо не передано, береться склад за замовчуванням.
`account_id`	id		Контрагент (/account).
`lead_order_id`	id		Лід, з якого створено замовлення.
`project_id`	id		Проєкт. Задається лише при створенні; спроба змінити через PUT поверне 422.
`project_stage_id`	id		Етап проєкту (разом із project_id). Лише при створенні.
`is_archived`	bool		В архіві. Архівні записи приховує параметр is_archived=true.
`is_completed`	bool		Виконано.
`tags`	масив Tag		Теги: [{"id": 3}] або [{"name": "VIP"}]. Передані замінюють усі теги запису. Див. «Вкладені дані».
`id`лише читання	ціле		Ідентифікатор запису.
`cost`лише читання	ціле, копійки		Сума позицій у копійках, рахує сервер.
`payment`лише читання	ціле, копійки		Сплачено, у копійках; рахує сервер.
`created_by_id`лише читання	id		Хто створив запис.
`shop_id`лише читання	id		Магазин (філія), ставиться з профілю користувача.
`created_at`лише читання	дата-час		Час створення.
`updated_at`лише читання	дата-час		Час останньої зміни, на ньому будується інкрементальна синхронізація.
`deleted_at`лише читання	дата-час		Час видалення (у звичайних відповідях завжди null).
`tasks`лише читання	масив Task		Завдання запису (лише у відповіді).
`updated_user`лише читання	об’єкт User		Хто змінив запис останнім.
`sub`лише читання	рядок		Службове поле, ігноруйте.
`version`лише читання	ціле		Службовий лічильник змін запису.

Вкладені масиви

order_extra_fields: пишеться в тілі POST/PUT, формат див. у розділі Вкладені дані.

Повʼязані обʼєкти для ?expand= (14)

Без expand приходять як null; писати їх не можна, передавайте відповідне *_id.

Status → LookupVat → LookupCurrency → CurrencyAddress → AddressSource → LookupOwner → UserCreatedBy → UserShop → ShopContact → ContactStock → StockAccount → AccountLead → LeadProject → ProjectProjectStage → ProjectStage

Службові поля у відповіді, ігноруйте: OldOrder.

Позиції документа

Товари й послуги документа. Власного права в позицій немає: читати їх може той, хто бачить документ, а змінювати той, хто може змінювати документ. Сума документа перераховується автоматично.

GET/order/{id}/items

Позиції з товаром і одиницею, з total.

право: order.view2 очк.

POST/order/{id}/items

Додати позицію.

право: order.update10 очк.

PUT/order/{id}/items/{item_id}

Змінити кількість, ціну, знижку.

право: order.update10 очк.

DELETE/order/{id}/items/{item_id}

Видалити позицію.

право: order.update10 очк.

Поле	Тип	Обмеження	Опис
`entity_type`обов.лише читання	рядок		Тип документа, береться зі шляху.
`entity_id`обов.лише читання	id		Id документа, береться зі шляху.
`product_id`обов.	id		Товар. Для kind=custom не потрібен.
`name`	рядок	≤ 120 симв.	Назва рядка. Для kind=custom обов’язкова, для товару береться з картки.
`kind`	рядок	product \| custom, ≤ 10 симв.	product (товар) або custom (довільний рядок без товару, напр. доставка чи послуга).
`cost_price`	ціле, копійки		Собівартість одиниці, копійки. Вводиться лише для kind=custom; у товарного рядка береться з партій і в запиті ігнорується.
`cost_source`	рядок	none \| manual \| product \| batch, ≤ 10 симв.	Звідки собівартість: none, manual, product, batch.
`unit_label`	рядок	≤ 30 симв.	Підпис одиниці.
`input_unit_id`	id		Одиниця введення / упаковка (/product/{id}/units).
`input_quantity`	ціле, ×1000		Кількість в упаковках, ×1000.
`input_price`	ціле, копійки		Ціна упаковки, копійки.
`price`	ціле, копійки		Ціна за одиницю, копійки. При додаванні ставиться базова ціна товару; змінюйте PUT рядка.
`quantity`	ціле, ×1000		Кількість, ×1000.
`discount_amount`	ціле, копійки		Знижка сумою, копійки.
`discount`	ціле	≤ 10000	Знижка, соті частки % (1000 = 10 %). Якщо не передано, діє персональна знижка клієнта.
`exchange_rate`	десяткове (рядок)		Курс перерахунку ціни товару у валюту документа (службове).
`reason_id`	id		Причина (для повернень).
`price_book_id`	id		Прайс-лист, з якого взято ціну.
`status`	рядок		Статус рядка (службове).
`description`	рядок	≤ 255 симв.	Коментар до рядка.
`id`лише читання	ціле		Ідентифікатор запису.
`unit_id`лише читання	id		Одиниця товару (лише у відповіді).
`input_factor`лише читання	десяткове (рядок)		Скільки базових одиниць в упаковці, береться з картки товару.
`product_units`лише читання	масив ProductUnit		Одиниці товару (лише у відповіді).
`total`лише читання	ціле, копійки		Підсумок рядка, рахує сервер.
`created_at`лише читання	дата-час		Час створення.
`updated_at`лише читання	дата-час		Час останньої зміни, на ньому будується інкрементальна синхронізація.
`updated_user`лише читання	об’єкт User		Хто змінив запис останнім.
`sub`лише читання	рядок		Службове поле, ігноруйте.
`version`лише читання	ціле		Службовий лічильник змін запису.

Вкладені масиви

batches: лише у відповіді (expand=Batches).
serial_numbers: лише у відповіді (expand=SerialNumbers).

Повʼязані обʼєкти для ?expand= (4)

Без expand приходять як null; писати їх не можна, передавайте відповідне *_id.

InputUnit → LookupProduct → ProductReason → LookupPriceBook → PriceBook

Службові поля у відповіді, ігноруйте: UserId, OldEntityProduct.

Додати товар

POST /api/v1/order/85/items
Idempotency-Key: order-85-add-258

{ "product_id": 258, "quantity": 3000 }

Змінити ціну й знижку рядка

PUT /api/v1/order/85/items/323
{ "price": 145000, "discount": 500 }

Документ і рядок беруться зі шляху: entity_type / entity_id у тілі ігноруються. Рядок чужого документа в цьому шляху дає 404. Закритий обліковий період, недостатній залишок чи вже проведений документ дають 422 з поясненням (див. Помилки).

Замовлення з сайту: повний сценарій

1. Знайти або створити клієнта

GET /api/v1/contact?filter[channels.phone;like]=671234567&fields=id
# немає — POST /api/v1/contact (див. «Контакти»)

2. Створити замовлення

POST /api/v1/order
Idempotency-Key: site-order-1001

{ "name": "Сайт №1001", "external_id": "site-1001", "contact_id": 42, "source_id": 3 }

3. Додати позиції

POST /api/v1/order/85/items
{ "product_id": 258, "quantity": 2000 }

4. Виставити рахунок на все замовлення

POST /api/v1/order/create-invoice/85
{}

Частковий рахунок: лише частина позицій

GET /api/v1/order/document-products/85     # id позицій і available_quantity
POST /api/v1/order/create-invoice/85
{ "products": [ { "id": 323, "quantity": 1000 } ], "provider_id": 1 }

provider_id означає вашу юрособу (ФОП/ТОВ), від якої виставляється документ. Якщо його не передано, береться юрособа із замовлення або основна.