Перейти до основного вмісту
Виклик кур’єра

Методи

Оформлення відправки посилок з вашої адреси відправника

Виклик кур'єра забезпечує можливість відправляти посилки з адреси. Через API клієнти можуть створювати запити на виклик кур'єра, керувати часовими інтервалами візиту, скасовувати та редагувати заявки.

У цій статті описані основні аспекти роботи з викликом кур'єра через API.

Логіка роботи виклику кур’єра через API

  1. Створення заявки на виклик кур'єра

    Клієнт викликає метод POST /pickups для створення нової заявки. На цьому етапі заявка отримує статус Draft. У цьому статусі клієнт може:
    • Додавати або видаляти відправлення.
    • Змінювати адресу або часові інтервали.
  2. Додавання відправлення у заявку на виклик кур'єра

    Відправлення додаються через метод POST /pickups/{id}/shipments. Для цього клієнт передає масив ID електроних накладних, які необхідно додати.

    Обмеження:
    • Відправлення мають бути у статусі ReadyToShip.
    • Відправлення з іншою адресою відправника не можуть бути додані.
  3. Вказання дати/часу прибуття кур’єра

    Після додавання відправлень треба вказати дату та час візиту кур'єра:
    1. За допомогою POST /time-intervals/find отримує доступні часові інтервали та вибирає зручний.
    2. Вибраний інтервал передається у параметри pickedTimeFrom і pickedTimeTo.
  4. Зміна статусу заявки

    Коли всі відправлення додані, клієнт переводить заявку у статус Created за допомогою PUT /pickups/{id}/status. У цьому статусі заявка готова до виконання.

    Обмеження:
    • Відправлення мають бути у статусі Paid або ContractAfterPayment.
    • Змінювати заявку більше не можна, окрім зміни часового інтервалу.
  1. Перегляд заявок

    Клієнт може отримати список своїх заявок за допомогою методу GET /pickups. У відповіді клієнт побачить поточний статус кожної заявки.
  2. Скасування та видалення
    • Для скасування заявки у статусі Created клієнт змінює її статус на ClientCanceled через PUT /pickups/{id}/status.
    • Для видалення заявки у статусі Draft використовується DEL /pickups/{id}

Методи виклику кур'єра в API

POST /pickups:

створення заявки на виклик кур'єра

Відповідь: ID створеної заявки зі статусом Draft. Поки заявка знаходиться у статусі Draft її можна видалити, якщо передумали викликати кур’єра.

Параметри:

  • address: адреса виклику кур'єра (адреса відправника)
  • pickedTimeFrom і pickedTimeTo: інтервал часу, коли прибуде кур'єр
  • contactPhone і contactName: контактні дані відправника

POST /pickups/{id}/shipments:

додавання у заявку відправлень, що будуть відправлені кур'єром в межах одного виклику

Параметри:

  • Масив ID електроних накладних: shipmentId[]

Умови:

  • Відправлення мають бути у статусі ReadyToShip.
  • Всі відправлення в межах однієї заявки мають мати однакову адресу відправки.
  • Одне відправлення може бути додана лише до однієї заявки на виклик кур'єра.

PUT /pickups/{id}/status:

зміна статусу заявки

Відповідь: підтвердження зміни статусу

  • Переводить заявку у статус Created, підтверджуючи готовність до виконання.

    Можливо, якщо у заявці є хоча б одне відправлення, та всі відправлення в заявці повинні бути у статусі Paid або ContractAfterPayment.
  • Переводить заявку зі статусу Created у статус ClientCanceled, у випадку якщо необхідно скасувати виклик у статусі Created.

POST /time-intervals/find:

отримання доступних для вибору часових інтервалів для візиту кур'єра

Відповідь: масив доступних інтервалів.

Параметри:

  • address: адреса виклику кур'єра (адреса відправника)
  • country: країна відправки
  • type: виклик кур’єра день в день PickupDayToDay або наступного дня PickupNextDay.

    Обмеження: Виклик кур'єра день в день PickupDayToDay вже працює у Лондоні, Варшаві, Празі та Берліні . Нові міста та країни додаються.

    В інших містах та країнах працює виклик кур'єра наступного дня PickupNextDay.

GET /pickups/{id}/shipments:

отримання переліку відправлень, що додані в заявку на виклик кур'єра

Відповідь: перелік усіх відправлень, доданих до конкретної заявки на виклик кур'єра.

DEL /pickups/{id}/shipments:

видалення відправлень із заявки

Параметри:

  • Масив ID електроних накладних

Умови:

  • Заявка має бути у статусі Draft

DEL /pickups/{id}:

видалення заявки на виклик кур'єра

Умови:

  • Видаляє заявку повністю, якщо вона у статусі Draft.
  • Заявки в статусі Created видалити не можливо, вони мають бути скасовані шляхом зміни статусу у ClientCanceled.

GET /pickups:

відстеження стану поточних заявок на виклик кур'єра

Відповідь: перелік заявок із вказанням їх статусів: Draft, Created, ClientCanceled тощо.

Статуси заявок:

  • Draft: Початковий статус заявки. В цьому статусі клієнт може додавати або видаляти відправлення.
  • Created: Після переведення в цей статус заявка вважається готовою для обробки кур'єром.
  • AppointedCourier: На заявку призначений кур'єр.
  • InProgress: Кур'єр виконує візит на адресу відправника.
  • ReceivedByCourier: Кур'єр прийняв відпрвлення у відправника та доставляє їх на підрозділ.
  • Done: Кур'єр виконав заявку і відправлення доставлені на підрозділ.
  • ClientCanceled: Заявка скасована клієнтом.
  • NotCompleted: Кур'єр скасував заявку через неможливість прийняти відправлення (наприклад, посилки не готові).
  • Deleted: Заявка видалена з системи.

Статуси посилок

Кожне відправлення в заявці на виклик кур'єра має окремий статус, що відображає його поточний стан у процесі приймання кур’єром (pickup_shipments[...]).

  • Added: відправлення додане у заявку. Доступно лише у статусі заявки Draft. Статус є початковим для кожного відправлення, доданої до заявки.
  • Accepted: відправлення успішно прийнято кур’єром. Застосовується лише для заявок на виклик кур'єра у статусах AppointedCourier або InProgress.
  • NotReady: відправлення вилучено із заявки через те, що посилка не була готова для відправки. Статус може бути встановлений лише кур’єром. Доступно лише для заявок на виклик кур'єра у статусах AppointedCourier або InProgress.
  • NotPacked: відправлення не було запаковане належним чином для передачі кур’єру. Статус може бути встановлений лише кур’єром. Доступно у заявках зі статусом AppointedCourier або InProgress.
  • ClientCanceled: Відправлення вилучено із заявки за ініціативою клієнта. Доступно в заявках на виклик кур'єра з будь-яким статусом, за винятком Draft і Deleted.
  • Deleted: Відправлення видалено із заявки на виклик кур'єра. Доступно лише у заявках на виклик зі статусом Draft. Видалені відправлення можуть бути відновлені до статусу Added.

Обмеження та важливі моменти

  • Додавання та видалення відправлень можливо лише у заявки у статусі Draft.
  • Заявки у статусі Created або вище не можна змінювати, лише скасувати, окрім зміни часового інтервалу.
  • Адреси відправки всіх відправлень у заявці на виклик кур’єра повинні бути однаковими, окрім поля Note.
  • Часові інтервали мають бути вибрані за допомогою доступних слотів. Часові інтервали “День в день” PickupDayToDay працюють не для всіх міст. Нові міста додаються поступово.
  • При внесенні змін у заявку на виклик кур’єра необхідно обов’язково збільшувати на одиницю значення поля lockVersion.

Детальну документацію щодо API-методів можна знайти у API-документації Nova Post.