← Назад
ordersСередній⏱️ 9 хв читання

Повний процес відвантаження товару

Наскрізний сценарій від створення отримувача та кошика до пречека і відвантаження: усі кроки та ендпоінти по порядку.

#orders#delivery#shopping-cart#processing

Цей інструкція показує повний шлях від створення апі ключа до відвантаження товару.

Усі ендпоінти цього сценарію зібрані в окремий 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. Пов’язує отримувача, місто, перевізника та склад перевізника (відділення) в один профіль доставки.

Параметри тіла запиту

NameTypeDescription
receiverstring (uuid)отримувач з кроку 1.1
citystring (uuid)місто доставки — GET /delivery/regions → GET /delivery/region/{region_uuid}/cities
carrierstring (uuid)перевізник — GET /delivery/carriers
carrier_warehousestring (uuid)відділення перевізника — GET /delivery/carriers/warehouses
is_defaultbooleanзробити профілем за замовчуванням

Тіло запиту:

{
  "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
}

Пошук

Пошук ендпоінтів, гайдів, туторіалів, реліз-ноутів по всьому порталу