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

Замовлення

Кошик — це замовлення в статусі draft. Ваш сервер відкриває його з тим складом, який зібрав покупець, і замінює склад, якщо той змінився до оформлення. Віджет склад замовлення не змінює — він лише веде покупця через контакт, доставку й оплату.

Ціни ніколи не приходять із браузера. Їх задає ваш сервер, коли відкриває кошик. Ціна рядка — це сума, яку спише замовлення, а далі — підписка, створена з цього рядка. Гроші скрізь — цілі копійки: 249000 означає 2 490,00 ₴.

Замовлення мусить містити хоча б один рядок subscription: кошик лише з разових товарів — це власне оформлення магазину, Neocarts у ньому участі не бере. Знижка передплатника — налаштування магазину; надіслана в рядку знижка ігнорується.

Відкриває кошик і повертає документ замовлення з розрахованими цінами. Кожен рядок водночас записується в каталог так само, як це зробив би PUT /v1/shop/products/{external_id}, — окрім price, яка залишається на замовленні та на підписці, яку створить цей рядок.

POST/v1/shop/orders/createBearer: API-ключ магазину

Заголовки — як описано в Автентифікації: Authorization: Bearer nc_live_…, Accept-Language, Content-Type: application/json.

Поле Тип Правила
redirect_url string необовʼязкове, може бути null, url ≤ 2048 — адреса кнопки «Повернутися до магазину» на екрані успіху. Платіжній системі не передається
locale string обовʼязкове, uk | en — мова всіх листів цьому покупцеві. Що читає ваш покупець, знаєте лише ви, тому значення за замовчуванням немає. Зберігається в покупця з першим замовленням і далі не змінюється
items array обовʼязкове, від 1 до 50 рядків, хоча б один subscription
items.*.external_id string обовʼязкове, ≤ 255 — ідентифікатор товару в магазині (SKU)
items.*.title string обовʼязкове, ≤ 255
items.*.variant string необовʼязкове, може бути null, ≤ 255
items.*.image_url string обовʼязкове, url ≤ 2048
items.*.product_url string обовʼязкове, url ≤ 2048
items.*.price integer обовʼязкове, від 1 до 999999999 — копійки, до знижки
items.*.quantity integer обовʼязкове, від 1 до 9
items.*.mode string обовʼязкове, one_time | subscription
items.*.interval_value integer обовʼязкове для subscription, від 1 до 365; для one_time відкидається
items.*.interval_unit string обовʼязкове для subscription, day | week; для one_time відкидається

Інтервал у рядку one_time відкидається і повертається як null.

Terminal window
curl -X POST https://core.neocarts.com/v1/shop/orders/create \
-H "Authorization: Bearer nc_live_…" \
-H "Accept-Language: uk" \
-H "Content-Type: application/json" \
-d '{
"redirect_url": "https://shop.example.com/cart?neocarts=checkout",
"locale": "uk",
"items": [
{
"external_id": "SKU-1",
"title": "Brit Care Adult Large Breed",
"variant": "12 кг",
"image_url": "https://shop.example.com/images/brit-care.jpg",
"product_url": "https://shop.example.com/products/brit-care",
"price": 249000,
"quantity": 1,
"mode": "subscription",
"interval_value": 4,
"interval_unit": "week"
},
{
"external_id": "SKU-2",
"title": "Керамічна миска Trixie",
"variant": "400 мл",
"image_url": "https://shop.example.com/images/trixie-bowl.jpg",
"product_url": "https://shop.example.com/products/trixie-bowl",
"price": 32000,
"quantity": 2,
"mode": "one_time"
}
]
}'

Відповідь — документ замовлення, той самий, який читає віджет (скорочено; повний опис полів — у Документі замовлення):

{
"id": "0199a3c4-5d6e-7f80-9a1b-2c3d4e5f6a7b",
"number": "261004-48213",
"shop_id": "…",
"status": "draft",
"redirect_url": "https://shop.example.com/cart?neocarts=checkout",
"locale": "uk",
"items": [
{
"external_id": "SKU-1",
"title": "Brit Care Adult Large Breed",
"variant": "12 кг",
"image_url": "https://shop.example.com/images/brit-care.jpg",
"product_url": "https://shop.example.com/products/brit-care",
"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/images/trixie-bowl.jpg",
"product_url": "https://shop.example.com/products/trixie-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": null,
"delivery": null,
"totals": { "items_total": 313000, "discount_total": 17430, "total": 295570 },
"payment": null
}

Збережіть id для віджета; людям показуйте number. Знижка застосовується лише до рядків subscription і розраховується за правилами з Гроші та округлення.

Статус Коли
201 замовлення відкрито — у відповіді документ замовлення
401 ключа немає або він невідомий
422 валідація — errors з ключами за буквальним шляхом поля, наприклад items.0.price або locale

Що робити при помилці: 401 — зупиніться й перевірте ключ; 422 — виправте тіло за полем із errors; найчастіше це відсутній locale, ціна з дробовою частиною замість цілого числа копійок або кошик без жодного рядка subscription.

Замінити склад замовлення

Section titled “Замінити склад замовлення”

Замінює кошик цілком і переоцінює його з тією знижкою, з якою замовлення було відкрито. Викликайте, коли покупець змінив кошик уже після того, як ваш сервер відкрив замовлення, але до початку оформлення.

PUT/v1/shop/orders/{order}/itemsBearer: API-ключ магазину

Заголовки — ті самі, що й вище. {order} — id замовлення з відповіді на створення.

Поле Тип Правила
items array обовʼязкове, від 1 до 50 рядків, хоча б один subscription; правила рядка — ті самі, що й при створенні
Terminal window
curl -X PUT https://core.neocarts.com/v1/shop/orders/0199a3c4-5d6e-7f80-9a1b-2c3d4e5f6a7b/items \
-H "Authorization: Bearer nc_live_…" \
-H "Accept-Language: uk" \
-H "Content-Type: application/json" \
-d '{
"items": [
{
"external_id": "SKU-1",
"title": "Brit Care Adult Large Breed",
"variant": "12 кг",
"image_url": "https://shop.example.com/images/brit-care.jpg",
"product_url": "https://shop.example.com/products/brit-care",
"price": 249000,
"quantity": 2,
"mode": "subscription",
"interval_value": 4,
"interval_unit": "week"
}
]
}'

Відповідь — оновлений документ замовлення, такий самий за формою, як при створенні.

Статус Коли
200 склад замінено — у відповіді документ замовлення
401 ключа немає або він невідомий
404 невідоме замовлення або замовлення іншого магазину — {"message":"Not found."}
409 замовлення вже не draft: оформлення почалося — {"message":"Товари замовлення, яке вже в оформленні, змінити не можна."}; або його скасовано — {"message":"Це замовлення скасовано."}
422 валідація — errors з ключами за буквальним шляхом, наприклад items.0.price

Що робити при помилці: 404 і 409 — відкрийте нове замовлення й передайте віджету новий id; 422 — виправте рядок, на який вказує errors.

Чому склад заморожується

Section titled “Чому склад заморожується”

Щойно покупець натиснув «Перейти до оплати», замовлення стає pending_payment і його склад більше не змінюється — навіть якщо оплата не пройде. Так відкрита сторінка оплати зі старою сумою не купить інший кошик. Переходи — у Статусах.

Передати замовлення віджету

Section titled “Передати замовлення віджету”

Сторінці магазину потрібен від сервера лише id замовлення. Поверніть його на сторінку й викличте NeocartsSubscription.open({ orderId }) — далі віджет сам веде покупця через контакти, доставку й оплату. Про результат ваш сервер дізнається з вебхуків. Як це зробити на сторінці — у Оформленні замовлення.