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

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

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

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

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

1. 1
   Створення заявки на виклик кур'єра
   
   Клієнт викликає метод POST /pickups для створення нової заявки. На цьому етапі заявка отримує статус Draft. У цьому статусі клієнт може:

   • 1.1
     Додавати або видаляти посилки.
   • 1.2
     Змінювати адресу або часові інтервали.
2. 2
   Додавання посилок у заявку на виклик кур'єра
   
   Посилки додаються через метод POST /pickups/{id}/shipments. Для цього клієнт передає масив ID посилок, які необхідно додати.
   
   Обмеження:

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

   1. 3.1
      За допомогою POST /time-intervals/find отримує доступні часові інтервали та вибирає зручний.
   2. 3.2
      Вибраний інтервал передається у параметри pickedTimeFrom і pickedTimeTo.
4. 4
   Зміна статусу заявки
   
   Коли всі посилки додані, клієнт переводить заявку у статус Created за допомогою PUT /pickups/{id}/status. У цьому статусі заявка готова до виконання.
   
   Обмеження:

   • 4.1
     Шипменти мають бути у статусі Paid або ContractAfterPayment.
   • 4.2
     Змінювати заявку більше не можна, окрім зміни часового інтервалу.

1. 5
   Перегляд заявок
   
   Клієнт може отримати список своїх заявок за допомогою методу GET /pickups. У відповіді клієнт побачить поточний статус кожної заявки.
   
   Статуси заявок:
   

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

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

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

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

1. 6
   Скасування та видалення

   • 6.1
     Для скасування заявки у статусі Created клієнт змінює її статус на ClientCanceled через PUT /pickups/{id}/status.
   • 6.2
     Для видалення заявки у статусі Draft використовується DEL /pickups/{id}

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

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

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