Цей інструкція показує повний шлях від створення апі ключа до відвантаження товару.
Усі ендпоінти цього сценарію зібрані в окремий OpenAPI-файл — зручно імпортувати в Postman/Insomnia чи інший клієнт, не тягнучи всю специфікацію API: завантажити openapi-shipment-process.json.
Крок 0. Отримання API-ключа
Створіть апі ключ або використайте інстуючий(«Як отримати API-ключ»)
Крок 1. Попередня підготовка
1.1 Створення отримувача
Метод: POST /delivery/receivers. Контактна особа, якій буде
видано товар.
Тіло запиту:
{
"surname": "Четвоертинський",
"name": "Іван",
"middle_name": "Андрійович",
"phone": "+380965432101"
}
Відповідь (201 Created):
{
"receiver": {
"full_name": "Четвоертинський Іван Андрійович",
"phone": "388095432101",
"uuid": "8203005056BA39E811F19551E0F4F5DA"
},
"success": true
}
receiver.uuid знадобиться на наступному кроці.
1.2 Створення налаштування доставки
Метод: POST /delivery/configs. Пов’язує отримувача, місто,
перевізника та склад перевізника (відділення) в один профіль доставки.
Параметри тіла запиту
| Name | Type | Description |
|---|---|---|
receiver | string (uuid) | отримувач з кроку 1.1 |
city | string (uuid) | місто доставки — GET /delivery/regions → GET /delivery/region/{region_uuid}/cities |
carrier | string (uuid) | перевізник — GET /delivery/carriers |
carrier_warehouse | string (uuid) | відділення перевізника — GET /delivery/carriers/warehouses |
is_default | boolean | зробити профілем за замовчуванням |
Тіло запиту:
{
"receiver": "<receiver_uuid>",
"city": "<city_uuid>",
"carrier": "<carrier_uuid>",
"carrier_warehouse": "<carrier_warehouse_uuid>",
"is_default": true
}
Відповідь (201 Created):
{
"success": true,
"message": null,
"config": {
"uuid": "<delivery_config_uuid>",
"name": "Нова пошта, Луцьк, Луцьк (1), Четвоертинський Іван Андрійович, Мінімальне страхування",
"carrier": { "uuid": "<carrier_uuid>", "name": "Нова пошта" },
"carrier_warehouse": {
"name": "Луцьк (1)",
"address": "Відділення №1: вул. Корсака Івана, 1 (поруч з Адреналін-Сіті)",
"max_weight": 0
},
"city": { "name": "Луцьк", "region": { "name": "Волинська область" } },
"receiver": { "full_name": "Четвоертинський Іван Андрійович" },
"address": "",
"house": "",
"flat": "",
"note": "",
"full_insurance": false,
"return_money": false,
"address_delivery": false
}
}
💡 На відміну від інших методів створення, тут повне тіло
configповертається одразу — окремо запитуватиGET /delivery/configsне потрібно, якщо ви вже збереглиconfig.uuidз цієї відповіді.
Якщо перевізник вимагає підтвердження (наприклад, кодом з СМС), викличте
POST /delivery/config/confirm з параметром ?code=<код_з_смс> —
успішне підтвердження також повертає 201 Created.
1.3 Створення кошика
Метод: POST /shopping/carts.
Тіло запиту:
{
"name": "Замовлення для СТО №1"
}
Відповідь (201 Created):
{
"carts": {
"warehouse": {
"uuid": "ACF9000C2947F7AE11E28A2B02C4AD32",
"name": "Луцьк РЦ"
},
"weight": 0.000,
"currency_name": "ГРН",
"total": 0.00,
"products": [],
"products_count": 0,
"comment": "",
"owner": {
"uuid": "81EE005056AC66D611EA4E45FCEC98E5",
"name": "Четвертинський Іван Петрович",
"f": 1
},
"uuid": "ca97cacb8c824d999bddfaa5a7660491",
"name": "string"
}
}
carts.uuid — з ним працюємо далі. Кошик одразу прив’язаний до конкретного
складу (carts.warehouse) та власника-контрагента (carts.owner).
1.4 Пошук товару
Метод: GET /search/products. Параметри передаються в
query-рядку, тіла запиту немає:
GET /search/products?q=турбіна&per_page=3
Відповідь (200 OK) — товари приходять
об’єктом, де ключ — це uuid товару (скорочено, показано один результат):
{
"products": {
"90DFDE6FDE75833F4ECFF1B18F3EDD86": {
"article": "765155-9007W",
"brand": "GARRETT",
"name": "Турбіна MB Sprinter 218/318/418/518 3.0CDI OM642 (заводська реставрація)",
"price": "28767.54",
"currency_name": "ГРН",
"available": true,
"in_stocks": [
{
"uuid": "ACF9000C2947F7AE11E28A2B02C4AD32",
"name": "Луцьк РЦ",
"quantity": "6",
"is_main": true
}
]
}
}
}
Ключ товару в об’єкті products (тут 90DFDE6FDE75833F4ECFF1B18F3EDD86) і є
product_uuid, потрібний для додавання в кошик. За in_stocks[].uuid
зручно перевірити, що товар є на тому самому складі, що й кошик
(carts.warehouse.uuid з кроку 1.3) — інакше додавання поверне помилку
нестачі залишку.
1.5 Додавання товару в кошик
Метод: POST /shopping/cart/{cart_uuid}/product/{product_uuid}/{quantity}.
Ідентифікатори кошика, товару та кількість передаються прямо в шляху, тіла
запиту немає. Наприклад, додати 1 одиницю товару в кошик:
POST /shopping/cart/c1c0ba18.../product/90DFDE6F.../1
Відповідь (201 Created):
{
"success": true,
"previous_quantity": 0,
"position_quantity": 1,
"position_total": 28767.54,
"cart": {
"uuid": "<cart_uuid>",
"products_count": 1,
"total": 28767.54,
"weight": 8.400,
"warehouse": { "uuid": "ACF9000C2947F7AE11E28A2B02C4AD32", "name": "Луцьк РЦ" },
"currency_name": "ГРН"
}
}
Щоб додати одразу список товарів, є
POST /shopping/cart/{cart_uuid}/products.
Крок 2. Пречек
Метод: GET /processing/cart/{cart_uuid}/pre_check. Перед
відвантаженням обов’язково перевірте, чи весь склад кошика доступний для
відвантаження — ціни, залишки та інші умови могли змінитися, поки формувався
кошик. Тіла запиту немає, cart_uuid передається в шляху.
Відповідь (200 OK — завжди, і для
дозволеного, і для забороненого відвантаження; результат перевіряйте за
полем allowed, а не за HTTP-статусом), якщо все гаразд:
{
"allowed": true,
"error": false,
"message": null
}
Якщо allowed: false — message міститиме причину рядком. Наприклад, якщо
на контрагенті є непідписані електронні документи (реальна відповідь):
{
"allowed": false,
"error": true,
"message": "Відвантаження заборонено. Наявні непідписані електронні документи."
}
Причиною так само можуть бути нестача залишку чи зміна ціни, поки формувався
кошик. У будь-якому разі скоригуйте те, на що вказує message (склад кошика —
DELETE /shopping/cart/{cart_uuid}/product/{product_uuid}, чи
непідписані документи — в особистому кабінеті) і повторіть пречек.
⚠️ Пречек — не одноразова перевірка “на вході”. Стан кошика й контрагента може змінитися між кроками 2 і 3.3, тож повторюйте пречек прямо перед викликом
POST /processing/sync, а не лише один раз на початку сценарію.
Аналогічні перевірки існують для одного товару
(GET /processing/{product_uuid}/{quantity}/pre_check) і для
резервів (GET /processing/reserves/pre_check).
Крок 3. Відвантаження
3.1 Отримання налаштувань доставки
Метод: GET /delivery/configs. Тіла запиту немає.
Відповідь (200 OK) — скорочено, один запис
зі списку:
{
"configs": [
{
"uuid": "<delivery_config_uuid>",
"name": "Самовивіз, Луцьк РЦ, Четвертинський Іван Петрович",
"carrier": { "uuid": "927D8673D92E46174374F9AB37AF08FB", "name": "Самовивіз" },
"carrier_warehouse": { "name": "Луцьк РЦ", "address": "вул. Корсака Івана 1", "max_weight": 0 },
"city": { "name": "Луцьк РЦ", "region": { "name": "Волинська область" } },
"receiver": { "full_name": "Четвертинський Іван Петрович" },
"is_default": false
}
]
}
Знайдіть тут uuid потрібного профілю доставки — саме він піде в параметр
delivery_config кроків 3.2 і 3.3.
💡 Новостворений на кроці 1.2 профіль може з’явитись у цьому списку не миттєво — якщо він потрібен відразу, надійніше взяти
config.uuidпрямо з відповіді кроку 1.2, а не з цього списку.
3.2 Отримання доступних рейсів
Метод: GET /processing/departures.
GET /processing/departures?delivery_config=<delivery_config_uuid>&warehouse=<warehouse_uuid>
⚠️ У специфікації і
delivery_config, іwarehouseпозначені опційними, але на практиці метод повертає422 Unprocessable Entity, якщо передати лишеdelivery_configбезwarehouse. Передавайте обидва параметри.
Відповідь (200 OK, реальний приклад, дати
відносні до моменту запиту):
{
"departures": [
{
"name": "Експрес-самовивіз (отримання через 15 хв)",
"route_at": "2026-08-11T00:00:00Z",
"route_code": "000000264",
"uuid": "c9acc64dc12fb07d04197cb92861688b 2026-08-11T00:00:00Z",
"departure_at": "2026-08-11T00:00:00Z",
"key": "c9acc64dc12fb07d04197cb92861688b",
"expired_at": "2026-08-11T20:45:00Z",
"is_working_time": true,
"message": null
},
{
"name": "завтра",
"route_at": "2026-08-12T00:00:00Z",
"route_code": "000000264",
"uuid": "498b15b20b9f39aa7acc03f328d3f8bd 2026-08-12T00:00:00Z",
"departure_at": "2026-08-12T00:00:00Z",
"key": "498b15b20b9f39aa7acc03f328d3f8bd",
"expired_at": "2026-08-12T20:45:00Z",
"is_working_time": true,
"message": null
}
]
}
key, route_code, route_at, departure_at та expired_at цього рейсу
передаються далі у виклик відвантаження.
3.3 Відвантаження кошика
Метод: POST /processing/sync.
Тіло запиту:
{
"cart": "<cart_uuid>",
"delivery_config": "<delivery_config_uuid>",
"warehouse": "<warehouse_uuid>",
"key": "c9acc64dc12fb07d04197cb92861688b",
"route_code": "000000264",
"route_at": "2026-08-11T00:00:00Z",
"departure_at": "2026-08-11T00:00:00Z",
"expired_at": "2026-08-11T20:45:00Z"
}
Відповідь (200 OK — так само і для
result: true, і для result: false; успішність перевіряйте за полем
result, а не за HTTP-статусом) — повний набір полів:
{
"result": true,
"document": "<order_uuid>",
"processing_report": null,
"changed_prices": null,
"saved_unshipped": null,
"download_unshipped": null,
"delivery_config": null
}
⚠️ Метод синхронний — таймаут може становити до 30 секунд, бо реалізація формується одразу і одразу впливає на ваш борг і кредитну лінію.
Для спрощеного відвантаження (без прив’язки до конкретного рейсу) достатньо
опустити key, departure_at, expired_at та route_at і залишити лише
cart, delivery_config і warehouse.
result: false означає, що документ не сформовано — сама причина в error.
Реальний приклад — непідписані електронні документи на контрагенті (блокує
будь-яке відвантаження, доки їх не підписано в кабінеті):
{
"result": false,
"error": "Наявні непідписані електронні документи",
"document": null,
"processing_report": null,
"changed_prices": null,
"saved_unshipped": null,
"download_unshipped": null,
"delivery_config": null
}