Перейти до вмісту

Документ замовлення

Цей документ повертають POST /v1/shop/orders/create і PUT /v1/shop/orders/{order}/items; позиції, контакти, доставка й підсумки у вебхуках мають ті самі форми. Замовлення — це знімок: поки воно у статусі draft, воно і є кошиком; після оплати нічого в ньому вже не змінюється.

{
"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": "Коваль",
"email": "[email protected]",
"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 ₴.

Поле Тип Опис
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, якщо оформлення ще не починалося.
Поле Тип Опис
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; одноразові товари йдуть за повною ціною.

Поле Тип Опис
items_total integer, копійки Сума subtotal усіх позицій.
discount_total integer, копійки items_total − total.
total integer, копійки Сума, яку покупець платить сьогодні. Вартість доставки сюди не входить — її покупець сплачує перевізнику.
Поле Тип Опис
first_name string Імʼя.
last_name string Прізвище.
email string На цю адресу йдуть листи про замовлення й підписку.
phone string Міжнародний формат, +380….
Поле Тип Опис
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 отримувача.
Спосіб Поля 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 (цифровий індекс)

Укрпошта наразі вимкнена; форма наведена для повноти. Контакти й доставку заповнює покупець у віджеті — сервер магазину їх не передає.

Поле Тип Опис
id string Ідентифікатор спроби оплати.
status string pending, success, failed, expired, refunded. Одна спроба — один платіж; повтор оформлення створює нову спробу.
Частина документа Сервер магазину (Shop API) Покупець у віджеті
items, redirect_url, locale Задаються при створенні. items можна замінити цілком через PUT …/items, лише поки status = draft. Ніколи.
contact, delivery Ніколи. На кроках «Контакти» й «Доставка», поки замовлення draft або pending_payment.
discount_percent Копіюється з налаштувань магазину при створенні; пізніші зміни налаштування відкриті замовлення не переоцінюють. Ніколи.
status, payment, totals Лише читання. Лише читання; status і payment змінюються, коли покупець переходить до оплати й платить.

Поле discount у позиції запиту ігнорується: знижка — налаштування магазину, а не властивість позиції.

  • contact, delivery, payment — null до відповідного кроку.
  • redirect_url, locale, discount_percent, variant — null, якщо не задані.
  • interval_value, interval_unit — null для one_time, навіть якщо їх передали у запиті.
  • totals і всі грошові поля позицій присутні завжди й завжди цілі.