Статус доставки Shipping API: коди статусів, вебхуки та сповіщення про виняткові ситуації

Статус доставки в API доставки описує перебіг переміщення посилки, а не те, чи був успішним запит API. Щоб створити надійне відстеження, розділяйте HTTP-коди відповіді та статуси відправлення, обробляйте вебхуки без припущення, що вони надходять один раз або в правильному порядку, а винятки, що потребують дій, перетворюйте на сповіщення з чітко визначеними відповідальними особами. Для інженерних команд і команд, що займаються операціями електронної комерції, мета полягає в тому, щоб запис про відправлення залишався надійним, навіть коли оновлення від перевізника затримуються, дублюються або виправляються.

У цьому посібнику пояснюється, як структурувати такий запис, обробляти вхідні події відстеження та відрізняти проблему з доставкою від проблеми інтеграції відстеження.

Розділяйте HTTP-коди, результати API та статуси відправлення

Вислів «код статусу» може стосуватися трьох різних рівнів. Їх змішування створює оманливі інформаційні панелі та непотрібні сповіщення для клієнтів.

Рівень	Що він повідомляє	Приклад тлумачення
HTTP-відповідь	Результат HTTP-запиту	Відповідь 200 означає успішність на рівні HTTP; це не означає, що посилку доставлено.
Бізнес-результат API	Чи була запитана операція успішною відповідно до прикладних правил постачальника	Тіло відповіді може повідомляти, що реєстрацію відстеження відхилено, зокрема в межах успішної HTTP-відповіді, якщо API використовує таку модель.
Статус відправлення	Повідомлений фізичний або операційний стан посилки	У дорозі, очікує отримання або доставлено.

Стандарт семантики HTTP визначає значення HTTP-відповідей. Наприклад, 202 Accepted означає, що запит прийнято до обробки, але обробка ще не обов’язково завершена. Це не є доказом того, що перевізник прийняв посилку.

Так само невдалий запит відстеження не доводить, що відправлення припинило рух. Ваш застосунок може тимчасово втратити видимість, хоча фізична доставка триває нормально. Відстежуйте ці рівні незалежно.

Створіть модель статусів, не втрачаючи дані перевізника

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

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

Ілюстративний внутрішній статус	Значення	Операційне застереження
Інформацію отримано	Електронна інформація про відправлення існує.	Не вважайте створення етикетки підтвердженням фізичної передачі посилки.
У дорозі	Запис відстеження вказує на переміщення через мережу доставки.	Ця широка категорія може охоплювати різні етапи транспортування.
Передано кур’єру для доставки	Повідомляється, що посилка перебуває на маршруті доставки.	Не перетворюйте цей статус на безумовну гарантію доставки.
Очікує отримання	Очікується, що одержувач забере посилку.	Додавайте інструкції або кінцеві строки отримання лише тоді, коли це підтверджено джерелом.
Доставлено	Джерело відстеження повідомляє про доставку.	Сам по собі скан доставки не вирішує заяву клієнта про неотримання.
Виняток	Подія може потребувати уваги або перервати нормальний перебіг.	Зберігайте причину, а не вважайте кожен виняток втратою.
Повернення триває або повернено	Посилка рухається назад або повідомлено про завершення повернення.	Відокремлюйте перебіг повернення від доставки початковому одержувачу.
Невідомо	Доступну інформацію неможливо впевнено зіставити.	Досліджуйте проблему мапінгу або нестачу даних замість вигадування статусу доставки.

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

Для реалізації з кількома перевізниками 17TRACK Tracking API є відповідним варіантом інтеграції. Використовуйте його офіційну документацію API, щоб визначити контракт реалізації, а не копіюйте ілюстративні позначення в поля, специфічні для постачальника. Перш ніж створювати адаптер, підтвердьте відповідні визначення статусів, конфігурацію вебхуків, вимоги до автентифікації та семантику відповідей.

Будуйте обробку вебхуків на основі надійного отримання

Вебхук — це HTTP-запит, надісланий до вашої кінцевої точки для повідомлення про подію. Він може зменшити потребу в постійному опитуванні, але його не слід розглядати як гарантію негайної, впорядкованої або одноразової доставки. Проєктуйте приймач так, щоб він витримував повторні спроби, переривання та неочікувані корисні навантаження, якщо постачальник прямо не гарантує інше.

1. Автентифікуйте запит. Застосовуйте задокументований метод перевірки постачальника. Якщо підтримуються підписи, перевіряйте їх за допомогою зазначеного алгоритму та необроблених байтів запиту. Не вигадуйте заголовок підпису і не припускайте, що кожен сервіс використовує HMAC.
2. Перевірте корисне навантаження. Перевіряйте обов’язкові поля, типи, розмір корисного навантаження та зв’язок із відправленням, яким керує ваш обліковий запис. Обробляйте невідомі необов’язкові поля, не порушуючи без потреби сумісність із майбутніми версіями.
3. Збережіть дані до підтвердження. Збережіть прийняту подію або помістіть її в надійну чергу до надсилання задокументованої успішної відповіді. Якщо збереження не вдалося, не підтверджуйте безпечне отримання події.
4. Обробляйте асинхронно. За можливості виконуйте мапінг статусів, оновлення замовлень і прийняття рішень щодо сповіщень поза обробником запиту.
5. Зробіть побічні ефекти ідемпотентними. Повторна подія не повинна створювати ще один запит до служби підтримки або надсилати копію того самого повідомлення клієнту.

Точний код підтвердження, час очікування, розклад повторних спроб і поведінка повторного відтворення залежать від постачальника. Явно перевіряйте ці деталі. Загальна інструкція «повертайте 200» не замінює контракт вебхука.

Використовуйте HTTPS і не зберігайте облікові дані в URL та звичайних журналах. Застосовуйте контроль доступу до збережених корисних навантажень, оскільки дані відстеження можуть містити персональну інформацію. Пам’ятка OWASP з безпеки REST містить відповідні рекомендації щодо захисту передавання, перевірки вхідних даних і безпеки кінцевих точок.

Усувайте дублікати подій, не приховуючи реальні оновлення

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

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

Відокремлюйте час події від часу отримання

Припустімо, що подія «у дорозі» потрапила до вашої системи після події «передано кур’єру для доставки», але мітка часу перевізника для неї раніша. Збережіть її в історії, не змінюючи автоматично поточний статус назад на «у дорозі».

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

Перетворюйте винятки на дії з відповідальними особами

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

Почніть із невеликої політики маршрутизації:

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

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

Розглядайте «відсутність оновлень» як окрему умову

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

Визначайте пороги бездіяльності за сервісом, маршрутом, етапом доставки та бізнес-зобов’язанням, а не застосовуйте один універсальний таймер. Відрізняйте посилку, яка ще не отримала сканування приймання, від посилки, оновлення якої припинилися після входження до мережі. Якщо історичних доказів недостатньо, використовуйте поріг для запуску розслідування, а не для оголошення втрати.

Пригнічуйте повторні сповіщення, доки незмінна справа залишається відкритою. Ескалюйте її, коли з’являються нові докази, пропущено погоджене подальше спостереження або зобов’язання щодо доставки клієнту потребує втручання.

Відстежуйте стан інтеграції окремо від ефективності доставки

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

• Стан запитів: Відстежуйте помилки автентифікації, тайм-аути, відповіді про обмеження частоти, помилки сервера та відхилення на рівні застосунку.
• Стан вебхуків: Відстежуйте помилки перевірки, затримку підтвердження, помилки збереження, дублікати доставок і помилки обробки.
• Стан обробки: Відстежуйте вік черги, необроблені події, помилки мапінгу та помилки сповіщень.
• Актуальність відстеження: Вимірюйте час від останньої події джерела окремо від часу від останнього успішного надходження у вашу систему.
• Операційні результати: Відстежуйте невирішені винятки, час до призначення відповідального та прострочені подальші дії.

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

Якщо це підтримується, використовуйте процес узгодження для отримання останнього запису відстеження після збоїв або підозрюваних пропущених подій. Встановлюйте його частоту в межах договірних обмежень і лімітів частоти. Вебхуки та узгодження мають різні цілі: перші доставляють зміни, а друге допомагає виявляти й виправляти прогалини.

Перевіряйте випадки збоїв до ввімкнення сповіщень для клієнтів

Почніть із внутрішньої обробки та перевірте репрезентативні відправлення, перш ніж дозволити надсилання клієнтам повідомлень про зміни статусу. Перевіряйте не лише звичайний перехід від «у дорозі» до «доставлено».

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

Критерієм випуску має бути операційна узгодженість: запис про відправлення, повідомлення клієнту та дія служби підтримки мають відповідати одним і тим самим базовим доказам. Одна лише успішна відповідь вебхука не доводить, що процес доставки працює.

Поширені запитання

Чи означає HTTP 200, що посилку доставлено?

Ні. Це означає успішність запиту на рівні HTTP. Окремо читайте бізнес-результат API та поля статусу відправлення. Для вебхука успішне підтвердження стосується отримання сповіщення, а не фізичної доставки посилки.

Що використовувати для оновлень відстеження: вебхуки чи опитування?

Використовуйте вебхуки для оновлень, керованих подіями, коли постачальник їх підтримує. Якщо це підтримується та є операційно виправданим, додайте обмежене опитування для узгодження й відновлення прогалин. Самого опитування може бути достатньо, коли вебхуки недоступні, але його частота має відповідати лімітам постачальника та вашим вимогам до актуальності.

Чому статус відстеження може змінитися після «доставлено»?

Джерело може виправити подію, або ваша інтеграція може отримати затриману чи суперечливу інформацію. Зберігайте історію та оцінюйте новіші докази, а не вважайте статус «доставлено» технічно незмінним. Повідомлена доставка та підтвердження отримання клієнтом також є різними фактами.

Як швидко слід надсилати сповіщення про виняток?

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

Чи мають клієнти бачити необроблений статус перевізника?

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

Джерела

• RFC 9110: Семантика HTTP — довідка щодо значень кодів статусу HTTP, зокрема 200 і 202.
• Пам’ятка OWASP з безпеки REST — рекомендації з безпеки, що стосуються кінцевих точок API та вебхуків.
• 17TRACK Tracking API — офіційний опис продукту для розглянутого варіанта інтеграції відстеження.
• 17TRACK API Documentation — офіційна довідка щодо специфічних для постачальника вимог інтеграції; ілюстративні схеми та рекомендації щодо робочого процесу в цьому посібнику не замінюють цей контракт.