Замовлення: адреси й поля
Тіло замовлення поле за полем, перевірка й створення замовлення, список замовлень, усі поля відповіді, причини відмови та коди помилок.
На цій сторінці
Тут описано адреси замовлень: тіло замовлення поле за полем, відповіді, коди помилок і всі причини, через які магазин не приймає замовлення. Як магазин приймає замовлення партнера, за якими цінами його рахує і як не створити замовлення двічі, описано на сторінці «Замовлення партнера».
| Адреса | Право | Список |
|---|---|---|
POST /api/v1/orders/check |
orders:create |
ні |
POST /api/v1/orders |
orders:create |
ні |
GET /api/v1/orders |
orders:read |
так |
GET /api/v1/orders/{id} |
orders:read |
ні |
У прикладах адреса магазину shop.example.ua, ключ видано контакту
«Коваленко Олег» (номер 418), а вітрина №1 продає в гривнях українською.
Тіло замовлення
POST /orders/check і POST /orders приймають однакове тіло: об’єкт JSON.
Спершу надішліть його на перевірку, потім те саме на створення. Перевірка
теж приймає external_id і заздалегідь повідомляє, чи не зайнятий цей
номер.
Магазин читає тіло як JSON, хоч би який був заголовок Content-Type. Якщо
тіло не є об’єктом JSON (непорожній список, рядок, розмітка з помилкою),
відповідь 400 з кодом bad_json. Порожнє тіло й порожній список []
вважаються порожнім об’єктом, і на них прийде 422 з повідомленням, що
позицій немає.
У цих двох адрес у рядку запиту можна передати лише locale, мову текстів
помилок. Будь-який інший параметр, наприклад ?storefront_id=2, отримує 422 з
кодом validation_failed: усі дані замовлення передаються в тілі.
{
"storefront_id": 1,
"external_id": "A-1024",
"items": [
{ "product_id": 1045, "sku_id": 2108, "qty": "2" }
],
"comment": "Запакуйте як подарунок",
"expected_total": "416.64",
"locale": "uk"
}
Поля тіла
| Поле | Тип | Потрібне | Що означає |
|---|---|---|---|
items |
список | так | позиції замовлення, від 1 до 100, описано нижче |
comment |
рядок або null |
ні | коментар до замовлення, до 2000 знаків. Менеджер бачить його в замовленні |
external_id |
рядок або null |
ні | номер замовлення у вашій системі, до 64 знаків. Унікальний у межах ключа API, докладніше на сторінці «Замовлення партнера» |
expected_total |
рядок або число | ні | підсумок, який ви очікуєте, у валюті вітрини, до двох знаків після крапки: "416.64". Якщо підсумок магазину інший, замовлення не створюється, докладніше на сторінці «Замовлення партнера» |
storefront_id |
ціле | ні | номер вітрини замовлення. Від вітрини залежать валюта й мова. Якщо не передати, замовлення піде на основну вітрину, а якщо її вимкнено, на першу ввімкнену. Номери вітрин віддає /storefronts |
locale |
рядок | ні | мова замовлення, одна з мов вітрини. Нею в замовлення записуються назви товарів. Якщо не передати, береться основна мова вітрини |
Інших полів немає. Доставку (shipping), спосіб оплати
(payment_method_id), отримувача (recipient) і промокод (coupon) через
API не передають, їх призначає менеджер у панелі. Такі поля отримують 422, як
будь-яке невідоме поле.
Зважайте на кілька правил:
- Номери (
storefront_id,product_id,sku_id) приймаються цілим числом або рядком із цифр:5і"5". Номер із крапкою ("5.0") не підходить. - Рядки обрізаються від пробілів по краях. Порожній рядок у
external_idіcommentозначає те саме, що поле не передано. - Поле, якого магазин не знає, — помилка, а не пропуск. Магазин відповідає 422 і перелічує допустимі поля.
- Мова замовлення (
localeу тілі) і мова відповіді (?locale=в адресі чи заголовокAccept-Language) — різні речі. Мова відповіді впливає лише на тексти помилок, причин відмови й попереджень. - Вітрину магазин перевіряє першою. Якщо
storefront_idнеправильний, відповідь називає лише цю помилку, решта полів не перевіряється.
Позиція items
| Поле | Тип | Потрібне | Що означає |
|---|---|---|---|
product_id |
ціле | так | номер товару, поле id товару в /products |
sku_id |
ціле | так | номер артикула цього товару, поле id артикула в /products або /skus |
qty |
рядок або число | так | кількість в одиницях продажу товару (поле unit), більша за нуль і не більша за 1 000 000, до трьох знаків після крапки: "2", "1.5", "0.250" |
Обидва номери обов’язкові, і артикул має належати товару. Код артикула
(sku) чи штрихкод замість номера магазин не приймає: знайдіть номер через
/skus з параметром sku або
barcode.
Один артикул — одна позиція. Якщо передати артикул двічі, магазин відповість 422 і назве позицію, де він уже є: додайте кількості самі. Інших полів позиція не має: ціну, упаковку чи послугу передати не можна.
Кількість має відповідати правилам продажу артикула: не менша за його
qty_min і від мінімуму кратна qty_step. Обидва поля є в артикула в
каталозі. Якщо кількість не
підходить, магазин не округлює її, а відмовляє з причиною qty_not_allowed
і називає найближчу відповідну кількість.
Помилки тіла
На помилки в тілі магазин відповідає 422 з кодом validation_failed. У полі
errors приходять усі помилки одразу, за шляхом до поля: items.2.qty,
items.0.product_id. Ключ повтору за такої помилки не займається, і
виправлений запит можна надіслати з тим самим Idempotency-Key.
{
"type": "https://cartixx.com/docs/api/errors#validation-failed",
"title": "Дані не пройшли перевірку",
"status": 422,
"detail": "Дані не пройшли перевірку. Подробиці в полі errors.",
"code": "validation_failed",
"request_id": "K2M7QX4D",
"errors": {
"shipping": ["Такого поля тут немає. Допустимі поля: storefront_id, external_id, items, comment, expected_total, locale."],
"items.0.sku_id": ["У полі sku_id потрібен номер з адреси /products, ціле число більше за нуль. Код артикула й штрихкод магазин тут не приймає."],
"items.1.product_id": ["Передайте поле product_id. Цей номер віддає адреса /products."]
}
}
| Коли | Поле в errors |
Повідомлення |
|---|---|---|
параметр у рядку адреси, крім locale |
назва параметра | «Такого параметра в цієї адреси немає. Допустимі параметри: locale.» |
поле, якого немає в тілі, зокрема shipping, payment_method_id, recipient, coupon |
назва поля | «Такого поля тут немає. Допустимі поля: storefront_id, external_id, items, comment, expected_total, locale.» |
| поле, якого немає в позиції | шлях до поля, наприклад items.1.price |
«Такого поля тут немає. Допустимі поля: product_id, sku_id, qty.» |
| вітрини з таким номером немає або її вимкнено | storefront_id |
«Вітрини з таким номером немає або її вимкнено. Номери вітрин віддає адреса /storefronts.» |
| у магазину немає жодної ввімкненої вітрини | storefront_id |
«У магазину немає жодної ввімкненої вітрини.» |
items немає, він порожній або не є списком |
items |
«Передайте позиції замовлення списком items: від 1 до 100 позицій.» |
| позицій більше 100 | items |
«В одному замовленні може бути не більше 100 позицій.» |
| позиція не є об’єктом | items.N |
«Тут потрібен об’єкт JSON.» |
product_id чи sku_id не передано або він дорівнює null |
items.N.product_id, items.N.sku_id |
«Передайте поле product_id. Цей номер віддає адреса /products.» з назвою поля |
product_id чи sku_id не є цілим додатним числом, наприклад код артикула |
items.N.product_id, items.N.sku_id |
«У полі sku_id потрібен номер з адреси /products, ціле число більше за нуль. Код артикула й штрихкод магазин тут не приймає.» з назвою поля |
| артикул уже є в іншій позиції | items.N.sku_id |
«Цей артикул уже є в items.0. Передайте його однією позицією із загальною кількістю.» |
| неправильна кількість | items.N.qty |
«Кількість — число більше нуля й не більше 1000000, до трьох знаків після крапки, наприклад "2" або "1.5".» |
| мови немає у вітрини | locale |
«Цієї мови у вітрини немає. Допустимі мови: uk, ru.» |
external_id чи comment не рядок |
назва поля | «Значення має бути одним рядком.» |
external_id довший за 64 знаки, comment довший за 2000 |
назва поля | «Довжина — не більше 64 знаків.» з межею поля |
expected_total не є сумою |
expected_total |
«Сума — число не менше нуля, до двох знаків після крапки, наприклад "1250.00".» |
POST /api/v1/orders/check
Рахує замовлення, нічого не створюючи. Право: orders:create. Відповідає
цінами позицій для вашого контакту, знижками, подарунками за акцією й
підсумком. Головне у відповіді — поле can_place і список problems: чи
можна створити таке замовлення, а якщо ні, то чому.
Перевірка не залишає в магазині нічого: ні замовлення, ні кошика, ні
зайнятого номера external_id. Товар вона не резервує, тому
can_place: true не обіцяє, що товар ніхто не купить раніше за вас.
Заголовок Idempotency-Key перевірці не потрібен.
Тіло те саме, що в POST /orders, і перевіряється так само суворо: помилки в
полях тіла приходять відповіддю 422 validation_failed, а не в problems.
Якщо поля тіла пройшли перевірку, відповідь завжди 200, навіть коли
замовлення створити не можна.
Доставки, оплати, отримувача й промокоду в розрахунку немає: їх призначає менеджер у панелі, і в підсумок доставка не входить.
curl https://shop.example.ua/api/v1/orders/check \
-X POST \
-H "Authorization: Bearer <ключ>" \
-H "Content-Type: application/json" \
-d @order.json
Відповідь на тіло з прикладу вище. Знижок на цей товар у магазині немає, тому
підсумок дорівнює сумі товарів і збігається з expected_total:
{
"data": {
"can_place": true,
"storefront_id": 1,
"locale": "uk",
"currency": "UAH",
"rate": "1.000000",
"base_currency": "UAH",
"items": [
{
"index": 0,
"product_id": 1045,
"sku_id": 2108,
"name": "Крем для рук 50 мл",
"qty_requested": "2.000",
"qty": "2.000",
"price": "208.32",
"compare_price": "320.00",
"total": "416.64",
"is_gift": false,
"problems": []
}
],
"discounts": [],
"totals": {
"items_total": "416.64",
"services_total": "0.00",
"discount_total": "0.00",
"total": "416.64"
},
"problems": []
}
}
Поля відповіді перевірки
| Поле | Тип | Що означає |
|---|---|---|
can_place |
логічне | true — таке замовлення POST /orders прийме, якщо до створення в магазині нічого не зміниться. false — не прийме, причини в problems |
storefront_id |
ціле | вітрина замовлення: з тіла або вибрана магазином |
locale |
рядок | мова замовлення. Нею приходять назви товарів у цій відповіді |
currency |
рядок | валюта замовлення, код ISO 4217. Усі суми відповіді в ній |
rate |
рядок | курс: скільки одиниць основної валюти коштує одна одиниця валюти замовлення, шість знаків після крапки |
base_currency |
рядок | основна валюта магазину |
items |
список | позиції, описано нижче |
discounts |
список | знижки, що ввійшли в замовлення: name — назва знижки, amount — її сума |
totals |
об’єкт | суми замовлення, описано нижче |
problems |
список | причини, через які замовлення не прийняти. Порожній, якщо can_place дорівнює true. Описано в розділі «Причини відмови» |
Позиція в items. Спершу йдуть ваші позиції в порядку запиту, за ними
подарунки, які поклав магазин.
| Поле | Тип | Що означає |
|---|---|---|
index |
ціле або null |
номер позиції в items запиту, з нуля. null у подарунка |
product_id |
ціле або null |
номер товару, як у запиті. У подарунка — номер товару подарунка |
sku_id |
ціле або null |
номер артикула, як у запиті. У подарунка буває null |
name |
рядок або null |
назва позиції мовою замовлення. null, якщо артикула немає в каталозі |
qty_requested |
рядок або null |
скільки ви замовили. null у подарунка |
qty |
рядок | скільки ввійшло в замовлення. "0.000", якщо позиція в замовлення не ввійшла |
price |
рядок або null |
ціна однієї одиниці для вашого контакту. null, якщо позиція в замовлення не ввійшла |
compare_price |
рядок або null |
стара, закреслена ціна одиниці |
total |
рядок | сума позиції: ціна, помножена на кількість, до знижок замовлення |
is_gift |
логічне | позицію поклав магазин за акцією |
problems |
список | причини відмови, що стосуються цієї позиції. Ті самі, що в загальному problems, лише без поля field |
Суми totals. Усі у валюті замовлення, два знаки після крапки.
| Поле | Що означає |
|---|---|
items_total |
сума позицій до знижок замовлення |
services_total |
сума послуг. Через API послуги не передаються, тому "0.00" |
discount_total |
сума знижок замовлення |
total |
підсумок замовлення: товари після знижок, без доставки. З ним порівнюється expected_total |
Нижче відповідь для випадку, коли замовлення не прийняти: замовлено п’ять штук, а на складі дві.
{
"data": {
"can_place": false,
"...": "...",
"items": [
{
"index": 0,
"product_id": 1045,
"sku_id": 2108,
"name": "Крем для рук 50 мл",
"qty_requested": "5.000",
"qty": "0.000",
"price": null,
"compare_price": null,
"total": "0.00",
"is_gift": false,
"problems": [
{ "code": "out_of_stock", "product_id": 1045, "sku_id": 2108, "available": "2.000", "message": "На складі менше, ніж у замовленні: доступно 2.000." }
]
}
],
"problems": [
{ "field": "items.0.qty", "code": "out_of_stock", "product_id": 1045, "sku_id": 2108, "available": "2.000", "message": "На складі менше, ніж у замовленні: доступно 2.000." }
]
}
}
POST /api/v1/orders
Створює замовлення. Право: orders:create. Тіло описано вище.
Замовлення створюється без доставки, оплати й отримувача: їх призначає
менеджер у панелі.
| Заголовок запиту | Потрібен | Що дає |
|---|---|---|
Idempotency-Key |
завжди | рядок до 255 друкованих знаків ASCII, свій у кожного замовлення. За ним магазин розпізнає повтор і не створює замовлення двічі. Докладно на сторінці «Замовлення партнера» |
Content-Type: application/json |
бажано | тіло — JSON |
curl https://shop.example.ua/api/v1/orders \
-X POST \
-H "Authorization: Bearer <ключ>" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: drop-A-1024" \
-d @order.json
Відповідь 201 Created:
| Заголовок відповіді | Що означає |
|---|---|
Location |
повна адреса замовлення в API: https://shop.example.ua/api/v1/orders/5120 |
Idempotent-Replayed: true |
приходить, якщо це повтор запиту й замовлення створено раніше. У першій відповіді заголовка немає |
{
"data": {
"id": 5120,
"number": "#1005120",
"external_id": "A-1024",
"status": "new",
"...": "усі поля замовлення"
},
"warnings": []
}
У data приходить замовлення повністю, його поля описано в розділі
«Поля замовлення». Відповідь приходить і ключу без права
orders:read.
У warnings магазин повідомляє, що вам варто знати про прийняте замовлення.
Замовлення при цьому створено.
code |
Додаткові поля | Коли |
|---|---|---|
backorder |
sku_id, qty |
частина товару чекає надходження на склад: у магазині дозволено замовлення понад залишок. qty — скільки чекає. Приклад тексту: «Артикул 2108 у кількості 3.000 чекає надходження на склад.» |
Кожне попередження має й поле message з текстом мовою відповіді. У
відповіді на повтор warnings завжди порожній список.
У якому порядку перевіряється запит
Якщо в запиті кілька проблем, відповідь називає першу за порядком:
- Загальні перевірки ключа й магазину, як в усіх адрес (див. «Помилки та їхні коди»).
- У рядку адреси немає параметрів, крім
locale(422validation_failed). - Заголовок
Idempotency-Keyє і він правильний. Якщо його немає або в ньому самі пробіли, відповідь 428idempotency_key_required. Якщо він неправильного вигляду, відповідь 400bad_idempotency_key. - Тіло — об’єкт JSON (400
bad_json). - Ключ повтору. Якщо перший запит із цим ключем ще оформлюється, відповідь
409
idempotency_in_progress, хоч би яке було тіло. Інакше магазин порівнює тіло з першим запитом: інше тіло отримає 422idempotency_key_reused. Якщо тіло те саме й замовлення вже створено, магазин одразу віддає це замовлення, більше нічого не перевіряючи. Якщо замовлення ключу більше не видно — 409idempotency_order_hidden. - Поля тіла (422
validation_failed). - Номер
external_idне зайнятий (409external_id_taken,external_id_in_progress). - Замовлення можна зібрати точно так, як надіслано (422
cannot_place). - Підсумок збігається з
expected_total(409total_mismatch). - Оформлення. Тут магазин ще раз рахує замовлення, звіряє підсумок і
резервує товар (422
cannot_place, 409total_mismatch, 409order_busy). Зрідка тут же приходить 409idempotency_in_progressабоexternal_id_in_progressіз заголовкомRetry-After: 2: поки замовлення оформлювалося, ключ повтору чи номерexternal_idзабрав інший запит, бо цей тривав довше за 10 хвилин.
GET /api/v1/orders
Замовлення контакту, якому видано ключ, з усіх каналів. Право: orders:read.
Порядок: за номером замовлення, за зростанням. Можна гортати за offset або
за after_id, як описано на сторінці
«Запити та відповіді».
| Параметр | Тип | Типово | Що робить |
|---|---|---|---|
status |
рядок | немає | замовлення з цим статусом. Коди статусів віддає /order_statuses |
storefront_id |
ціле | немає | лише замовлення цієї вітрини. На відміну від каталогу, параметр не змінює валюту: суми приходять у валюті замовлення |
external_id |
рядок | немає | замовлення з цим вашим номером, прийняте цим ключем. Точний збіг |
created_since |
дата й час | немає | замовлення, створені починаючи з цього моменту |
updated_since |
дата й час | немає | замовлення, змінені починаючи з цього моменту |
limit |
ціле | 50 | записів на сторінці, від 1 до 200 |
offset |
ціле | 0 | скільки записів пропустити. Разом з after_id не передається |
after_id |
ціле | немає | замовлення з номером, більшим за вказаний |
locale |
рядок | немає | мова текстів помилок |
Дата й час передаються у форматі ISO 8601 із часовим поясом:
2026-10-19T08:00:00Z або 2026-10-19T11:00:00+03:00. Знак + в адресі
потрібно записувати як %2B, але магазин зрозуміє й неекранований. Межа
включається: замовлення, змінене саме у вказану секунду, потрапить у
відповідь.
Час зміни замовлення зсувається під час зміни статусу, оплати й правки
замовлення в панелі: складу, сум, адреси, доставки. Тому сюди потрапляє й
замовлення, якому менеджер призначив доставку, оплату чи отримувача. Щоб
забирати лише зміни, запам’ятовуйте час початку попереднього запиту й
передавайте його в updated_since.
curl "https://shop.example.ua/api/v1/orders?updated_since=2026-10-19T08:00:00Z&after_id=0&limit=100" \
-H "Authorization: Bearer <ключ>"
{
"data": [
{ "id": 5120, "number": "#1005120", "external_id": "A-1024", "status": "shipped", "...": "..." }
],
"meta": { "total": 1, "limit": 100, "after_id": 0 },
"links": { "next": null, "prev": null }
}
| Помилка 422 | Поле в errors |
Повідомлення |
|---|---|---|
| невідомий параметр | назва параметра | «Такого параметра в цієї адреси немає. Допустимі параметри: …» |
| статусу з таким кодом немає | status |
«Такого статусу замовлення немає. Коди статусів віддає адреса /order_statuses.» |
storefront_id не є цілим додатним числом |
storefront_id |
«Потрібен номер запису — ціле додатне число.» |
external_id чи status передано списком |
назва параметра | «Значення має бути одним рядком.» |
| неправильна дата | created_since або updated_since |
«Потрібні дата й час у форматі ISO 8601, наприклад 2026-10-17T09:00:00Z.» |
неправильний limit, offset, after_id або offset разом з after_id |
назва параметра | як на сторінці «Запити та відповіді» |
Номер вітрини, якої немає, помилкою не вважається: прийде порожній список.
GET /api/v1/orders/{id}
Одне замовлення за його номером у магазині (поле id). Право: orders:read.
curl https://shop.example.ua/api/v1/orders/5120 \
-H "Authorization: Bearer <ключ>"
Відповідь — {"data": {…}} із замовленням, поля описано нижче. Якщо
замовлення немає або воно належить іншому контакту, відповідь 404 з кодом
not_found. Номер, довший за 18 цифр, теж отримує 404.
Адреса приймає лише параметр locale. Будь-який інший параметр, зокрема
storefront_id, limit і offset, отримує 422 з повідомленням «Такого
параметра в цієї адреси немає. Допустимі параметри: locale.»
Поля замовлення
Замовлення має однаковий вигляд у відповіді на створення, у списку й у картці. Суми приходять у валюті замовлення й за його курсом. Ціни, курс і склад замовлення записуються в момент оформлення й потім самі не перераховуються.
Доставка, оплата й отримувач у замовленні лише для читання: їх призначає
менеджер у панелі. У щойно створеному замовленні shipping і recipient
дорівнюють null, у payment є лише стан оплати, а доставка в підсумку
дорівнює нулю. Приклад нижче показує замовлення після того, як менеджер
призначив доставку Новою Поштою, оплату під час отримання й отримувача.
{
"id": 5120,
"number": "#1005120",
"external_id": "A-1024",
"status": "new",
"payment_status": "pending",
"storefront_id": 1,
"locale": "uk",
"currency": "UAH",
"rate": "1.000000",
"base_currency": "UAH",
"channel": { "type": "api", "api_client_id": 3, "name": "API: Сайт партнера" },
"customer": {
"contact_id": 418,
"name": "Коваленко Олег",
"phone": "+380501112233",
"email": "kovalenko@example.ua",
"company": null
},
"recipient": {
"phone": "+380671234567",
"last_name": "Коваль",
"first_name": "Ірина",
"is_company": false
},
"items": [
{
"id": 9311,
"product_id": 1045,
"sku_id": 2108,
"sku": "730601",
"name": "Крем для рук 50 мл",
"qty": "2.000",
"unit": "pcs",
"price": "208.32",
"compare_price": "320.00",
"discount": "0.00",
"services_total": "0.00",
"total": "416.64",
"is_gift": false,
"backorder_qty": "0.000"
}
],
"totals": {
"items_total": "416.64",
"services_total": "0.00",
"discount_total": "0.00",
"shipping_total": "85.00",
"bonus_total": "0.00",
"tax_total": "0.00",
"total": "501.64",
"paid_total": "0.00",
"due": "501.64"
},
"shipping": {
"method_id": 3,
"option_id": "3:nova_poshta",
"name": "Нова Пошта",
"price": "85.00",
"type": "warehouse",
"city": "Київ",
"point": {
"ref": "1ec09d88-e1c2-11e3-8c4a-0050568002cf",
"number": "1",
"name": "Відділення №1: вул. Пирогівський шлях, 135",
"address": "вул. Пирогівський шлях, 135"
},
"address": {
"country": null,
"region": null,
"city": "Київ",
"street": null,
"building": null,
"apartment": null,
"zip": null
},
"waybill_number": null
},
"payment": {
"method_id": 1,
"name": "Оплата під час отримання",
"status": "pending"
},
"comment": "Запакуйте як подарунок",
"placed_at": "2026-10-19T08:12:40Z",
"created_at": "2026-10-19T08:12:40Z",
"updated_at": "2026-10-19T09:30:02Z"
}
Те саме замовлення одразу після створення:
{
"id": 5120,
"...": "...",
"recipient": null,
"totals": { "items_total": "416.64", "shipping_total": "0.00", "total": "416.64", "due": "416.64", "...": "..." },
"shipping": null,
"payment": { "method_id": null, "name": null, "status": "pending" }
}
| Поле | Тип | Що означає |
|---|---|---|
id |
ціле | номер замовлення в магазині. За ним замовлення відкривається в /orders/{id} |
number |
рядок | номер замовлення так, як його бачать у магазині й називають покупцеві, наприклад "#1005120". Вигляд номера задає власник |
external_id |
рядок або null |
ваш номер замовлення, якщо замовлення надійшло через API з external_id. У замовлень з інших каналів null |
status |
рядок | код статусу замовлення. Назви й переходи віддає /order_statuses |
payment_status |
рядок | стан оплати: pending — не оплачено, partial — оплачено частково, paid — оплачено, authorized — гроші заблоковано на картці й буде списано пізніше, failed — оплата не пройшла, refunded — гроші повернули |
storefront_id |
ціле або null |
вітрина замовлення |
locale |
рядок або null |
мова замовлення |
currency |
рядок | валюта замовлення, код ISO 4217 |
rate |
рядок | курс у момент оформлення: скільки одиниць основної валюти коштує одна одиниця валюти замовлення, шість знаків після крапки |
base_currency |
рядок | основна валюта магазину зараз |
channel |
об’єкт | звідки надійшло замовлення, описано нижче |
customer |
об’єкт | замовник, описано нижче |
recipient |
об’єкт або null |
отримувач, якого призначив менеджер. Набір полів залежить від форми отримувача в магазині: код поля й значення рядком, а також ознака компанії is_company. null, поки отримувача немає |
items |
список | позиції замовлення, описано нижче |
totals |
об’єкт | суми замовлення, описано нижче |
shipping |
об’єкт або null |
доставка, яку призначив менеджер, описана нижче. null, поки доставки немає |
payment |
об’єкт | оплата, описана нижче |
comment |
рядок або null |
коментар до замовлення |
placed_at |
дата або null |
коли замовлення оформлено |
created_at |
дата | коли замовлення з’явилося в магазині |
updated_at |
дата | коли замовлення востаннє змінювалося |
Канал channel.
| Поле | Тип | Що означає |
|---|---|---|
type |
рядок | api — надійшло через API, marketplace — з майданчика, наприклад Rozetka чи Prom, admin — оформив менеджер у панелі, storefront — оформлено на вітрині |
api_client_id |
ціле або null |
номер ключа API, який надіслав замовлення. Є лише в type: api |
name |
рядок або null |
підпис каналу. У замовлень через API — «API: назва ключа», з майданчика — його назва, з панелі й вітрини — назва вітрини |
Замовник customer. Дані з картки контакту на момент оформлення.
| Поле | Тип | Що означає |
|---|---|---|
contact_id |
ціле або null |
номер контакту замовника. У замовлень за ключем це контакт ключа |
name |
рядок або null |
ім’я замовника |
phone |
рядок або null |
телефон замовника |
email |
рядок або null |
пошта замовника |
company |
рядок або null |
компанія замовника. У замовлень за ключем приходить, лише якщо картка контакту — компанія |
Позиція в items.
| Поле | Тип | Що означає |
|---|---|---|
id |
ціле | номер позиції в замовленні |
product_id |
ціле або null |
номер товару. null, якщо товар видалили з каталогу |
sku_id |
ціле або null |
номер артикула. null, якщо артикул видалили |
sku |
рядок або null |
код артикула в момент оформлення |
name |
рядок | назва позиції в замовленні, мовою замовлення |
qty |
рядок | кількість в одиницях unit, три знаки після крапки |
unit |
рядок або null |
одиниця продажу товару, як у каталозі: pcs, m, kg та інші. Якщо в товару одиницю не задано, pcs. null, якщо товар видалили |
price |
рядок | ціна однієї одиниці |
compare_price |
рядок або null |
стара, закреслена ціна одиниці |
discount |
рядок | частка знижок замовлення, що припала на цю позицію. Якщо магазин зберігає знижку замовлення однією сумою, а не розкладає по позиціях, тут "0.00", і знижку видно лише в totals.discount_total |
services_total |
рядок | сума послуг позиції |
total |
рядок | ціна, помножена на кількість, плюс послуги, до знижок замовлення |
is_gift |
логічне | позицію поклав магазин, це подарунок за акцією |
backorder_qty |
рядок | скільки з кількості чекає надходження на склад. "0.000", якщо весь товар є |
Суми totals. Усі у валюті замовлення, два знаки після крапки.
| Поле | Що означає |
|---|---|
items_total |
сума позицій до знижок |
services_total |
сума послуг |
discount_total |
знижки замовлення |
shipping_total |
вартість доставки. "0.00", поки менеджер не призначив доставку |
bonus_total |
оплачено бонусами |
tax_total |
податок понад ціни. Зазвичай "0.00": податок уже входить у ціни товарів |
total |
підсумок замовлення |
paid_total |
скільки вже оплачено |
due |
скільки лишилося оплатити: підсумок мінус оплачене, не менше нуля |
Доставка shipping. null, поки менеджер не призначив доставку.
| Поле | Тип | Що означає |
|---|---|---|
method_id |
ціле або null |
номер способу доставки з /shipping_methods |
option_id |
рядок або null |
варіант доставки у вигляді <номер способу>:<код варіанта> |
name |
рядок або null |
назва доставки в замовленні |
price |
рядок | вартість доставки, та сама, що totals.shipping_total |
type |
рядок або null |
вид відправлення в перевізника: warehouse — відділення, postomat — поштомат, courier — за адресою. null, якщо спосіб виду не називає |
city |
рядок або null |
місто доставки. Якщо менеджер виправив адресу, тут нове місто |
point |
об’єкт або null |
відділення чи поштомат: ref — код точки в перевізника, number — номер, name — назва, address — адреса. null у разі доставки за адресою |
address |
об’єкт або null |
адреса доставки: country, region, city, street, building, apartment, zip. У разі доставки в точку вулиця, будинок і квартира — null |
waybill_number |
рядок або null |
номер накладної перевізника, коли магазин її створив |
Оплата payment.
| Поле | Тип | Що означає |
|---|---|---|
method_id |
ціле або null |
номер способу оплати з /payment_methods. null, поки менеджер не призначив спосіб |
name |
рядок або null |
назва способу в замовленні. null, поки способу немає |
status |
рядок | те саме, що payment_status |
API не віддає службових даних замовлення: посилання на сторінку оплати, IP-адреси й браузера покупця, відповідального співробітника, історії замовлення, номера платежу в банку й закупівельних цін.
Причини відмови
Причини приходять списком problems у відповіді /orders/check і у
відповіді 422 cannot_place на POST /orders. Кожна причина має поля:
| Поле | Що означає |
|---|---|
field |
якого поля запиту стосується причина: items.0.qty, items.1.product_id, items. У problems позиції відповіді перевірки цього поля немає |
code |
код причини. Ваша програма перевіряє саме його, текст message може змінюватися |
message |
пояснення мовою відповіді |
| інші поля | подробиці причини, перелічено в таблиці |
{
"type": "https://cartixx.com/docs/api/errors#cannot-place",
"title": "Дані не пройшли перевірку",
"status": 422,
"detail": "Замовлення не створено. Причини перелічено в полі problems.",
"code": "cannot_place",
"request_id": "P8W3NB2Z",
"problems": [
{
"field": "items.0.sku_id",
"code": "sku_not_in_product",
"product_id": 1045,
"sku_id": 2240,
"message": "Артикул 2240 не належить товару 1045. Візьміть product_id і sku_id з одного товару в /products."
},
{
"field": "items.1.qty",
"code": "qty_not_allowed",
"product_id": 1050,
"sku_id": 2251,
"min": "2.000",
"step": "2.000",
"suggested": "4.000",
"message": "Така кількість не продається: мінімум 2.000, крок 2.000. Найближча допустима кількість — 4.000."
}
]
}
Кожна позиція має не більше однієї причини. Магазин перевіряє позицію в такому порядку: товар, артикул, належність артикула товару, продаж, кількість, залишок. На першій же причині перевірка позиції зупиняється.
Причини позицій завжди мають product_id і sku_id із запиту.
code |
field |
Подробиці | Текст | Що робити |
|---|---|---|---|---|
product_not_found |
items.N.product_id |
product_id, sku_id |
«Товару 1045 немає в каталозі або його не опубліковано.» Товар — чернетка, прихований, в архіві або такого номера немає | приберіть позицію, звірте каталог через /products/ids |
sku_not_found |
items.N.sku_id |
product_id, sku_id |
«Артикула 2108 немає в каталозі.» | візьміть номер артикула з /products |
sku_not_in_product |
items.N.sku_id |
product_id, sku_id |
«Артикул 2240 не належить товару 1045. Візьміть product_id і sku_id з одного товару в /products.» | передайте номери товару й артикула з одного запису /products |
sku_not_for_sale |
items.N.sku_id |
product_id, sku_id |
«Артикул 2108 знято з продажу.» | приберіть позицію |
qty_not_allowed |
items.N.qty |
product_id, sku_id, min, step, suggested |
«Така кількість не продається: мінімум 2.000, крок 2.000. Найближча допустима кількість — 4.000.» Кількість менша за мінімум або не кратна кроку, а в товару «лише упаковками» не кратна упаковці. suggested — найближча відповідна кількість, не менша за запитану |
замовте suggested або іншу відповідну кількість |
out_of_stock |
items.N.qty |
product_id, sku_id, available |
«На складі менше, ніж у замовленні: доступно 2.000.» На складах, за якими магазин рахує наявність для ключа (вибраних у ключі, а якщо їх не вибрано — на складах вітрини), менше, ніж у замовленні, а передзамовлення в магазині заборонено. available — скільки можна замовити |
зменште кількість до available |
external_id_taken |
external_id |
external_id, order_id |
«Замовлення з external_id A-1024 уже прийнято, у магазині воно має номер 5120.» Лише в перевірці | не надсилайте замовлення повторно |
total_mismatch |
expected_total |
expected_total, actual_total |
«Підсумок замовлення 416.64 відрізняється від очікуваного 400.00.» Лише в перевірці | звірте ціни й знижки |
stock_reserve_failed |
items |
products |
«Поки замовлення оформлювалося, частина товару закінчилася на складі. Яких артикулів забракло, вказано в полі products. Перевірте наявність і надішліть замовлення ще раз.» Лише під час створення: товар забрало інше замовлення. У products для кожного артикула: sku_id, name і short_qty — скільки забракло |
перевірте наявність і надішліть замовлення ще раз |
order_rejected |
поле, якого стосується відмова | немає | «Магазин не прийняв замовлення. Повідомте магазину код із поля request_id, за ним знайдуть ваш запит.» Лише під час створення: замовлення відхилило доповнення магазину або правило, яке API не вміє назвати | повідомте магазину код із request_id, справжню причину записано в журнал магазину під цим кодом |
Коди помилок замовлень
Загальний вигляд відповіді про помилку й загальні коди описано на сторінці «Помилки та їхні коди». Тут зібрано коди, які бувають лише в замовлень.
| HTTP | code |
Адреса | Коли | Що робити |
|---|---|---|---|---|
| 400 | bad_json |
обидва POST |
тіло не є об’єктом JSON | надішліть об’єкт JSON |
| 400 | bad_idempotency_key |
POST /orders |
ключ повтору довший за 255 знаків, із кирилицею чи перенесенням рядка | використовуйте латиницю, цифри й розділові знаки, найзручніше UUID |
| 428 | idempotency_key_required |
POST /orders |
немає заголовка Idempotency-Key |
додайте заголовок |
| 422 | validation_failed |
усі | неправильне поле тіла чи параметр, подробиці в errors |
виправте поля з errors |
| 422 | cannot_place |
POST /orders |
замовлення не можна зібрати точно так, як надіслано, причини в problems |
виправте замовлення за причинами |
| 422 | idempotency_key_reused |
POST /orders |
з цим ключем повтору вже надійшло замовлення з іншим тілом | дайте новому замовленню новий ключ |
| 409 | idempotency_in_progress |
POST /orders |
замовлення з цим ключем ще оформлюється. Є Retry-After: 2 |
повторіть той самий запит через 2 секунди |
| 409 | idempotency_order_hidden |
POST /orders |
замовлення за цим ключем повтору створено, але ключ API відтоді прив’язали до іншого контакту | не надсилайте замовлення заново, зв’яжіться з магазином |
| 409 | external_id_taken |
POST /orders |
замовлення з цим external_id уже прийнято. Номер замовлення в order_id, ваш номер в external_id |
не надсилайте замовлення заново. Переглянути його можна в /orders/{order_id}. Якщо ключ відтоді прив’язали до іншого контакту, замовлення лишилося в попереднього, і адреса відповість 404 |
| 409 | external_id_in_progress |
POST /orders |
замовлення з цим external_id ще оформлює інший запит. Є Retry-After: 2 |
повторіть через 2 секунди |
| 409 | total_mismatch |
POST /orders |
підсумок не збігся з expected_total. Ваш підсумок в expected_total, підсумок магазину в actual_total |
перевірте замовлення через /orders/check і надішліть із новим підсумком |
| 409 | order_busy |
POST /orders |
магазин саме зараз оформлює інші замовлення з тими самими товарами. Є Retry-After: 2 |
повторіть той самий запит із тим самим ключем через 2 секунди |
| 404 | not_found |
GET /orders/{id} |
замовлення немає або воно чуже | перевірте номер |
{
"type": "https://cartixx.com/docs/api/errors#total-mismatch",
"title": "Конфлікт",
"status": 409,
"detail": "Підсумок замовлення не збігся з expected_total, тому замовлення не створено. Підсумок за розрахунком магазину — у полі actual_total.",
"code": "total_mismatch",
"request_id": "B6R1TZ9Q",
"expected_total": "400.00",
"actual_total": "416.64"
}
{
"type": "https://cartixx.com/docs/api/errors#external-id-taken",
"title": "Конфлікт",
"status": 409,
"detail": "Замовлення з цим external_id уже прийнято. Його номер у магазині — у полі order_id.",
"code": "external_id_taken",
"request_id": "H4N8CW2L",
"external_id": "A-1024",
"order_id": 5120
}
Жодна відмова з цієї таблиці не створює замовлення. Після відмови ключ
повтору вільний, і виправлений запит можна надіслати з тим самим
Idempotency-Key. Винятки — idempotency_key_reused,
idempotency_order_hidden і idempotency_in_progress: ключ зайнятий іншим
запитом або замовленням, яке за ним уже створено.