Документ замовлення
Цей документ повертають POST /v1/shop/orders/create і PUT /v1/shop/orders/{order}/items; позиції, контакти, доставка й підсумки у вебхуках мають ті самі форми. Замовлення — це знімок: поки воно у статусі draft, воно і є кошиком; після оплати нічого в ньому вже не змінюється.
Приклад
Section titled “Приклад”{ "id": "0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b", "number": "261004-48213", "shop_id": "7f3c2b1a-0d9e-4f8a-b7c6-d5e4f3a2b1c0", "status": "draft", "redirect_url": "https://shop.example.com/cart?nc=1", "locale": "uk", "items": [ { "external_id": "SKU-1", "title": "Brit Care Adult Large Breed", "variant": "12 кг", "image_url": "https://shop.example.com/i/brit.jpg", "product_url": "https://shop.example.com/p/brit", "price": 249000, "quantity": 1, "mode": "subscription", "interval_value": 4, "interval_unit": "week", "discounted_price": 231570, "subtotal": 249000, "total": 231570 }, { "external_id": "SKU-2", "title": "Керамічна миска Trixie", "variant": "400 мл", "image_url": "https://shop.example.com/i/bowl.jpg", "product_url": "https://shop.example.com/p/bowl", "price": 32000, "quantity": 2, "mode": "one_time", "interval_value": null, "interval_unit": null, "discounted_price": 32000, "subtotal": 64000, "total": 64000 } ], "discount_percent": 7, "contact": { "first_name": "Олена", "last_name": "Коваль", "phone": "+380671234567" }, "delivery": { "provider": "nova-poshta", "type": "branch", "data": { "city": { "id": "…", "external_id": "8d5a980d-391c-11dd-90d9-001a92567626", "name": "Київ" }, "branch": { "id": "…", "external_id": "1ec09d88-e1c2-11e3-8c4a-0050568002cf", "name": "Відділення №1: вул. Пирогівський шлях, 135" } }, "recipient": { "first_name": "Олена", "last_name": "Коваль", "phone": "+380671234567" } }, "totals": { "items_total": 313000, "discount_total": 17430, "total": 295570 }, "payment": { "id": "…", "status": "pending" }}Усі суми — цілі копійки: 249000 означає 2 490,00 ₴.
Поля верхнього рівня
Section titled “Поля верхнього рівня”| Поле | Тип | Опис |
|---|---|---|
id |
string, UUID | Ідентифікатор замовлення. Передається у NeocartsSubscription.open({ orderId }). |
number |
string | Людський номер у форматі YYMMDD-NNNNN: дата за UTC і 5 випадкових цифр. Безпечно показувати покупцю та в листах. |
shop_id |
string, UUID | Магазин, якому належить замовлення. |
status |
string | draft, pending_payment, paid, cancelled. Переходи — на сторінці Статуси. |
redirect_url |
string, може бути null | Куди віджет веде покупця кнопкою «Назад до магазину» після завершеного замовлення. Платіжному провайдеру не передається. |
locale |
string, може бути null | uk або en — мова листів цьому покупцю. |
items |
array | Позиції кошика, 1–50. Див. нижче. |
discount_percent |
integer, може бути null | Знижка на підписку, скопійована з налаштувань магазину в момент створення замовлення. null — знижки немає. |
contact |
object, може бути null | Контакти покупця. null, доки віджет не збереже крок «Контакти». |
delivery |
object, може бути null | Спосіб і адреса доставки. null, доки віджет не збереже крок «Доставка». |
totals |
object | Підсумки в копійках. Див. нижче. |
payment |
object, може бути null | Остання спроба оплати або null, якщо оформлення ще не починалося. |
Позиція (items[])
Section titled “Позиція (items[])”| Поле | Тип | Опис |
|---|---|---|
external_id |
string ≤255 | Ідентифікатор товару (варіанта, SKU) у магазині. Без символу /. |
title |
string ≤255 | Назва товару. |
variant |
string ≤255, може бути null | Варіант («12 кг», «400 мл»). |
image_url |
string, url ≤2048 | Зображення для віджета та листів. |
product_url |
string, url ≤2048 | Сторінка товару в магазині. |
price |
integer, копійки | Ціна за одиницю до знижки, яку назвав сервер магазину. 1–999999999. |
quantity |
integer | 1–9. |
mode |
string | one_time або subscription. |
interval_value |
integer, може бути null | 1–365. Для one_time завжди null. |
interval_unit |
string, може бути null | day або week. Для one_time завжди null. |
discounted_price |
integer, копійки | Ціна за одиницю після знижки. Для one_time дорівнює price. Формула — у Гроші та округлення. |
subtotal |
integer, копійки | price × quantity. |
total |
integer, копійки | discounted_price × quantity. |
Знижка застосовується лише до позицій subscription; одноразові товари йдуть за повною ціною.
Підсумки (totals)
Section titled “Підсумки (totals)”| Поле | Тип | Опис |
|---|---|---|
items_total |
integer, копійки | Сума subtotal усіх позицій. |
discount_total |
integer, копійки | items_total − total. |
total |
integer, копійки | Сума, яку покупець платить сьогодні. Вартість доставки сюди не входить — її покупець сплачує перевізнику. |
Контакти (contact)
Section titled “Контакти (contact)”| Поле | Тип | Опис |
|---|---|---|
first_name |
string | Імʼя. |
last_name |
string | Прізвище. |
email |
string | На цю адресу йдуть листи про замовлення й підписку. |
phone |
string | Міжнародний формат, +380…. |
Доставка (delivery)
Section titled “Доставка (delivery)”| Поле | Тип | Опис |
|---|---|---|
provider |
string | Перевізник, один із увімкнених у магазині. Сьогодні — nova-poshta. |
type |
string | branch, parcel-locker або address; має бути увімкнений для цього перевізника. |
data |
object | Адреса; поля залежать від способу, див. таблицю нижче. Місто, відділення, поштомат і вулиця — обʼєкти { id, external_id, name }: id — ідентифікатор Neocarts, external_id — ідентифікатор у перевізника (Ref Нової Пошти, з ним формують ТТН), name — назва. Якщо запис зник із довідника перевізника, external_id і name дорівнюють null. |
recipient |
object | first_name, last_name, phone отримувача. |
Форми delivery.data
Section titled “Форми delivery.data”| Спосіб | Поля data |
|---|---|
nova-poshta / branch |
city, branch |
nova-poshta / parcel-locker |
city, parcel_locker |
nova-poshta / address |
city, street, house_number; необовʼязкове apartment_number, floor_number |
ukr-poshta / branch |
zip_code (цифровий індекс) |
Укрпошта наразі вимкнена; форма наведена для повноти. Контакти й доставку заповнює покупець у віджеті — сервер магазину їх не передає.
Оплата (payment)
Section titled “Оплата (payment)”| Поле | Тип | Опис |
|---|---|---|
id |
string | Ідентифікатор спроби оплати. |
status |
string | pending, success, failed, expired, refunded. Одна спроба — один платіж; повтор оформлення створює нову спробу. |
Що і хто може змінити
Section titled “Що і хто може змінити”| Частина документа | Сервер магазину (Shop API) | Покупець у віджеті |
|---|---|---|
items, redirect_url, locale |
Задаються при створенні. items можна замінити цілком через PUT …/items, лише поки status = draft. |
Ніколи. |
contact, delivery |
Ніколи. | На кроках «Контакти» й «Доставка», поки замовлення draft або pending_payment. |
discount_percent |
Копіюється з налаштувань магазину при створенні; пізніші зміни налаштування відкриті замовлення не переоцінюють. | Ніколи. |
status, payment, totals |
Лише читання. | Лише читання; status і payment змінюються, коли покупець переходить до оплати й платить. |
Поле discount у позиції запиту ігнорується: знижка — налаштування магазину, а не властивість позиції.
Nullability коротко
Section titled “Nullability коротко”contact,delivery,payment—nullдо відповідного кроку.redirect_url,locale,discount_percent,variant—null, якщо не задані.interval_value,interval_unit—nullдляone_time, навіть якщо їх передали у запиті.totalsі всі грошові поля позицій присутні завжди й завжди цілі.