Типи подій та коди статусів

У роботі з webhook використовуються два різні набори значень, і плутати їх не можна:

• Типи подій — це значення, які ви передаєте в параметрі eventTypes під час створення або оновлення підписки. Вони визначають, які зміни статусу породжуватимуть webhook-сповіщення.
• Коди статусів відстеження — це числові значення, які надходять у тілі webhook-запиту в параметрі history_tracking[].code. Саме на них будується бізнес-логіка на вашому боці. Допустимі значення — див. розділ Коди статусів відстеження.

Типи подій для параметра eventTypes

{
  "eventTypes": ["AwaitingOnDivision", "Received"]
}

• Порожній список або відсутній параметр означає, що надходитимуть усі підтримувані події.
• Значення чутливі до регістру. Назва з помилкою не спрацює як фільтр, і повідомлення про помилку при створенні підписки ви не отримаєте.

Тип події	Опис
ReadyToShip	Відправлення створено та готове до відправки.
Deleted	Відправлення видалено.
ParcelPlaceRemoved	Місце відправлення було видалено з відправлення.
Received	Відправлення отримано одержувачем.
MoneyTransfer	Створено грошовий переказ, пов’язаний із відправленням.
MoneyTransferReceived	Грошовий переказ, пов’язаний із відправленням, виплачено одержувачу.
Returned	Відправлення повертається або вже повернуто відправнику.
Refused	Одержувач відмовився прийняти відправлення.
Redirecting	Відправлення перенаправляється на іншу адресу або у відділення.
Utilization	Відправлення утилізовано.
Redelivery	Заплановано повторну спробу доставки відправлення.
UndeliveryReason	Зафіксовано причину недоставки.
ChangeTime	Дату або час доставки було змінено.
ArrivalSC	Відправлення прибуло до сортувального центру.
TransferToPartner	Відправлення передано партнеру для подальшої доставки.
LoadingCourier	Відправлення завантажено до транспортного засобу кур’єра.
ArrivalSenderWarehouse	Відправлення прибуло на склад відправника.
DepartureSenderWarehouse	Відправлення вибуло зі складу відправника.
InCityRecipient	Відправлення прибуло до міста отримувача.
AwaitingOnDivision	Відправлення очікує у відділенні або пункті видачі.

Коди статусів відстеження

Будуйте бізнес-логіку на параметрі code, а не на code_name. Числовий код є сталим, а назва статусу може змінюватися — вона потрібна лише для того, щоб людині було одразу зрозуміло, про що йдеться. Різні коди можуть мати однакову назву.

Нижче наведено коди статусів, за якими надсилаються webhook-сповіщення.

Код	Назва статусу відстеження
1	Ready to send
2	Deleted
4	Accepted for sending
5	Sent from the Sender's Division
6	Arrived in the city of the Recipient
7	Arrived (at the Division)
8	Arrived (at the Postomat)
9	Closed
10	The shipment is closed and the money transfer is sent to the Sender
11	The shipment is closed and the sender has received the money transfer
13	Arrival at the transit sorting center
16	Departure from the transit sorting center
17	ArrivalTransitWarehouse (currently not used)
19	DepartureFromTransitWarehouse (currently not used)
30	Arrived at customs terminal
31	Departed from customs terminal
70	Added to manifest
99	Delivery to Postomat is impossible (technical issues or oversized parcel)
101	Uploaded to the courier for delivery to the address
102	Returns (sender ordered a return)
103	Refusal of shipment
104	Redirecting
105	Utilization
106	Received and created return shipment of Documents/Document Subtypes
107	At pickup point
110	Shipment transferred to temporary storage
111	Failed delivery attempt (in case of targeted delivery)
112	Delivery date postponed (for targeted delivery)
113	Storage period expired (Postomat)
114	Awaiting customs clearance
115	Arrived at customs terminal
116	Broker refusal — under resolution
117	Cargo not found or lost (customs)
118	Forbidden content — delivery impossible (customs)
119	Customs clearance in progress
120	Customs clearance completed
121	Sent to destination city after customs
122	Preparing for transfer to customs
123	Awaiting information from the recipient
125	Preparing for transfer to customs
126	Preparing for transfer to customs
127	Customs declaration data verification in progress
128	Processing accompanying documents prior to customs
130	Import prohibited by customs
131	Return of uncleared cargo
132	Preparing for return
133	Client communication regarding a customs comment
134	The international shipment has been handed over to the customs broker for processing
135	The international shipment has been placed in Storage Area
138	Shipment delay due to incorrect recipient information
141	Storage period expired
144	Storage period expired
149	In storage
155	Shipment transferred for disposal
197	Processing customs documents
198	Cargo inspection by customs
199	Shipment requires customs clearance
999	Undetermined

Мінімальний алгоритм обробника

1. Перевірити секретний заголовок.
2. Розібрати тіло запиту.
3. Взяти UUID повідомлення із заголовка x-np-attempt — частину до крапки.
4. Якщо цей UUID уже оброблено — повернути 2xx і завершити обробку.
5. Зберегти дані та UUID однією транзакцією.
6. Повернути 2xx.
7. Виконати бізнес-обробку окремо, поза межами цього запиту.

Особливості, які варто врахувати

Situation	Що робити
Бізнес-логіка на назві статусу ненадійна.	Використовуйте code. Він сталий, тоді як code_name може змінитися, а різні коди можуть мати однакову назву.
Оновлення підписки скидає параметри, які не були передані в запиті.	Під час виклику PUT завжди передавайте повний набір параметрів, навіть якщо змінюєте один. Перед оновленням отримайте поточні налаштування методом Отримати всі підписки.
Тип підписки змінити не можна.	Щоб перейти на інший тип, створіть нову підписку й видаліть стару.
Видалення номерів повертає код 200 навіть тоді, коли не видалено жодного номера.	Перевіряйте параметр status у тілі відповіді, а не HTTP-код.
Додавання номерів може спрацювати частково.	Завжди звіряйте missedNumbers. Номери, яких ще немає в системі, потрібно додати повторно пізніше.
Кожне webhook-сповіщення містить усю історію, а не лише нову подію.	Зберігайте у себе останній оброблений стан і порівнюйте з ним.
Одне сповіщення може надійти кілька разів.	Обробник має бути стійким до повторів — використовуйте UUID із заголовка x-np-attempt.
Події за час вимкненої підписки не зберігаються.	Після повторного ввімкнення підписки пропущені події не надійдуть. Якщо потрібна повна історія за цей період, отримайте її через методи трекінгу.
Кілька підписок на ті самі відправлення не дають більше сповіщень.	Webhook-сповіщення надсилається один раз незалежно від кількості підписок, під які підпадає відправлення. Дублювати підписки не потрібно.
Номери не відв’язуються від підписки автоматично.	Навіть після доставки відправлення його номер залишається в підписці. Видаляйте номери самостійно, коли вони більше не потрібні.
text/plain як значення contentType буде виведено з підтримки.	Переходьте на application/json. Тіло запиту при цьому не зміниться.
У Sandbox webhook-сповіщення за реальними змінами статусів не надсилаються.	Перевіряйте інтеграцію методом Перевірка тестового webhook. Відсутність webhook-сповіщень у Sandbox не означає помилки в налаштуванні.