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

Такий підхід корисний, коли клієнт відкриває сторінку замовлення, спеціаліст служби підтримки потребує оновлення або вашій системі потрібно відновитися після пропущеного сповіщення. Надійна реалізація поєднує запити на вимогу, чіткі індикатори актуальності та захист від дубльованих або отриманих не в тому порядку оновлень.
Визначте, що означає «найновіший статус відправлення»
Перш ніж обирати кінцеву точку, розрізніть три операції, які можуть звучати подібно, але дають різні результати.
| Операція | Що вона робить | Чого вона не встановлює |
|---|---|---|
| Прочитати власну базу даних | Повертає інформацію про відстеження, яку ваш застосунок уже зберігає. | Чи отримав провайдер новіше оновлення. |
| Надіслати запит до API відстеження | Отримує інформацію, доступну через операцію запиту провайдера. | Чи відбулася нова перевірка у перевізника під час цього запиту. |
| Запросити оновлення відстеження | Запитує ще одну перевірку на стороні джерела, якщо провайдер підтримує таку операцію. | Що перевізник має нове сканування або що оновлення завершиться синхронно. |
Використовуйте запит, коли вам потрібна відповідь зараз. Розглядайте операцію оновлення лише тоді, коли потрібно, щоб провайдер спробував виконати ще одну перевірку на стороні джерела. Не припускайте, що додавання параметра для обходу кешу, повторення запиту або надсилання HTTP-заголовка cache-control змусить перевізника надати нову інформацію.
Видимість відправлення має кілька етапів: перевізник фіксує подію, провайдер відстеження отримує її, а ваш застосунок отримує або запитує її. Прямий API-запит може усунути очікування доставки сповіщення, але не може усунути затримки на попередніх етапах цього ланцюжка.
Перевірте контракт запиту перед написанням коду
Розробник, який інтегрує сервіс відстеження, відповідає за цей процес. Починайте з актуальної документації провайдера, а не з кінцевої точки, скопійованої зі старого прикладу інтеграції. Перевірте такі деталі:
- Ідентифікація відправлення: Чи приймає запит номер відстеження, внутрішній ідентифікатор відправлення або номер відстеження разом з ідентифікатором перевізника?
- Вимоги до реєстрації: Чи потрібно зареєструвати відправлення перед виконанням запиту?
- Автентифікація: Який заголовок або механізм автентифікації потрібен?
- Значення відповіді: Чи повертає операція збережену інформацію, ініціює збір даних або повертає завдання для подальшої перевірки?
- Обробка результату: Чи може успішна HTTP-відповідь містити помилку на рівні відправлення або результат, що очікує обробки?
- Обмеження використання: Які обмеження частоти запитів, пакетів і обмеження для облікового запису застосовуються?
- Поля актуальності: Які часові позначки відповідають подіям перевізника, оновленням провайдера та формуванню відповіді?
Для інтеграції з 17TRACK відповідним продуктом є Tracking API, а не сторінка відстеження для споживачів або інтерфейс відстеження в інтернет-магазині. Використовуйте офіційну документацію API, щоб підтвердити операцію запиту інформації про відстеження, автентифікацію, поля запиту та структуру відповіді для вашої інтеграції. Розглядайте запити та обробку вебхуків як окремі шляхи застосунку, які оновлюють один і той самий запис відправлення.
Уникайте жорстко заданих припущень щодо поведінки оновлення або частоти запитів. Ці деталі мають відповідати операції та умовам сервісу, якими ви фактично користуєтеся.
Створіть отримання даних на вимогу через свій бекенд
Практичний підхід полягає у створенні автентифікованої кінцевої точки у вашому застосунку. Браузер запитує оновлення відправлення через цю кінцеву точку; ваш сервер перевіряє авторизацію, визначає, чи потрібен запит до провайдера, і повертає нормалізований результат.
Наведений нижче маршрут є прикладом кінцевої точки, яку ви створили б у своєму застосунку. Це не кінцева точка 17TRACK і не специфікація запиту провайдера.
GET /api/orders/{order_id}/shipment-statusВикористовуйте ідентифікатор замовлення, щоб знайти відправлення на сервері. Не дозволяйте користувачу отримувати історію відстеження іншого клієнта лише шляхом заміни номера відстеження в запиті. Зберігайте облікові дані API провайдера на бекенді, а не в JavaScript браузера чи пакеті мобільного застосунку.
Процес запиту, який можна реалізувати
- Авторизуйте доступ. Переконайтеся, що клієнт або працівник має право переглядати замовлення.
- Визначте відправлення. Зчитайте збережений ідентифікатор відстеження та інформацію про перевізника, якщо це необхідно.
- Перевірте локальну актуальність. Якщо нещодавно вже було успішно виконано запит, повторно використайте його відповідно до політики актуальності вашого застосунку.
- За потреби надішліть запит провайдеру. Використовуйте задокументовану операцію та обмежений час очікування запиту.
- Перевірте результат. Перевірте як результат HTTP-запиту, так і результат на рівні відправлення.
- Об’єднайте інформацію. Застосуйте ті самі правила нормалізації та узгодження, що й для подій вебхуків.
- Поверніть статус і актуальність. Додайте час останньої події та час останньої успішної перевірки провайдера, якщо вони доступні.
Політика локальної актуальності є інженерним рішенням, а не твердженням про частоту оновлень перевізника. Визначайте її з урахуванням вимог інтерфейсу, обмежень провайдера, обсягу відправлень і фактичної користі запитів. Багаторазове натискання клієнтом кнопки оновлення не повинно створювати необмежений потік запитів до джерела.
Нормалізуйте відповідь, не вигадуючи актуальність
Ваш застосунок може повертати стабільний внутрішній формат навіть тоді, коли структури відповідей провайдерів відрізняються. Цей ілюстративний об’єкт є вашим власним контрактом застосунку, а не фактичним payload провайдера:
{
"shipment_id": "internal-shipment-id",
"status": "in_transit",
"latest_event_at": null,
"provider_updated_at": null,
"last_successful_query_at": null,
"retrieval_state": "success",
"source": "provider_query"
}Заповнюйте кожну часову позначку лише тоді, коли відоме її значення. Час отримання відповіді вашим сервером належить до метаданих запиту; його не можна подавати як час переміщення посилки. Якщо провайдер не надає часової позначки оновлення провайдера, залиште це поле відсутнім або зі значенням null, а не підставляйте іншу часову позначку.
В інтерфейсі клієнта розділяйте повідомлення: «Остання подія перевізника» описує активність відправлення, а «Відстеження перевірено» описує активність вашого застосунку з отримання даних. Це розмежування не дозволяє незмінному скануванню виглядати як щойно зафіксованому.
Не дозволяйте API-запитам і вебхукам перезаписувати одне одного
Коли обидва механізми активні, одна й та сама подія може надійти через запит і вебхук. Вони також можуть завершитися в іншому порядку, ніж були запущені. Запит, запущений першим, може завершитися після того, як вебхук уже надав новішу інформацію.
Не використовуйте логіку «перемагає остання відповідь». Payload, отриманий останнім, не обов’язково є найновішим станом відправлення.
- Використовуйте один конвеєр оновлень. Передавайте результати запитів і payload вебхуків через однакові функції перевірки, нормалізації та збереження.
- Усувайте дублікати подій. Перевагу слід надавати задокументованому ідентифікатору події. Якщо його немає, створіть ретельно визначений відбиток на основі доступних полів, таких як час події, статус, місцезнаходження та опис.
- Використовуйте поля порядку з відомою семантикою. Задокументована ревізія або послідовність корисніші, ніж припущення, що час отримання визначає порядок подій.
- Зберігайте історію. Нещодавно отримана подія може заповнити історичну прогалину, не змінюючи поточний підсумок відправлення.
- Дозволяйте виправлення. Статуси не є універсальною лінійною послідовністю. Дотримуйтеся задокументованої поведінки виправлень, а не назавжди відхиляйте кожен видимий перехід назад.
Коли порядок подій невідомий, зберігайте початковий payload і його походження для розслідування. Не усувайте неоднозначність шляхом вигадування часової позначки події або припущення, що всі часові позначки перевізника використовують один часовий пояс.
Обробляйте відсутні дані та невдалі запити по-різному
Порожній результат, незмінений результат і невдалий запит не повинні формувати однакове повідомлення для клієнта.
Запит успішний, але статус не змінився
Збережіть наявний статус відправлення та оновіть час останнього успішного запиту. Не створюйте нову подію відправлення лише тому, що завершилося ще одне отримання даних. Якщо клієнту потрібні додаткові відомості, покажіть наявну історію подій і поясніть, що новішої події відстеження не повернуто.
Відправлення ще не має інформації про відстеження
Перевірте, чи потрібна реєстрація, чи правильні ідентифікатор і перевізник, а також як провайдер позначає очікування збору даних. Відсутність подій сама по собі не доводить, що номер відстеження недійсний або посилка загублена. Зберігайте розмежування провайдера між невідомим ідентифікатором, зареєстрованим відправленням, що очікує інформації, і запитом, який не вдалося обробити.
Запит до провайдера завершився тайм-аутом або помилкою
Якщо у вас є попередній дійсний статус, поверніть його з чітким зазначенням, що остання перевірка була невдалою. Не змінюйте час попереднього успішного запиту. Мережева помилка не є винятком доставки й не повинна змінювати бізнес-статус посилки.
Для відповідних тимчасових помилок використовуйте обмежені повторні спроби з експоненційною затримкою та випадковим розподілом. Не повторюйте запити з недійсними обліковими даними або неправильним форматом. Якщо відповідь містить Retry-After, інтерпретуйте його відповідно до контракту провайдера та семантики HTTP. Специфікація HTTP дозволяє вказувати це значення як затримку в секундах або дату HTTP.
Надходить кілька запитів для одного відправлення
Об’єднуйте одночасні отримання даних, щоб вони могли спільно використовувати один запит до джерела. Застосовуйте обмеження для облікового запису та відправлення й не допускайте множення автоматичної повторної спроби на кількох рівнях застосунку. Якщо підтримуються пакетні запити, перевіряйте результат кожного відправлення, а не вважайте весь пакет успішним лише тому, що HTTP-запит завершився.
Використовуйте опитування як контрольований резервний варіант
Без вебхуків заплановане опитування може підтримувати актуальність бази даних, але для цього потрібна чітка операційна політика. Визначте, які відправлення залишаються доступними для перевірки, як помилки впливають на розклад і коли регулярне опитування припиняється.
Для більшості інтеграцій гібридна конструкція є розумною відправною точкою: вебхуки обробляють фонові зміни, запити на вимогу обслуговують інтерактивні звернення, а завдання узгодження перевіряють записи, що потребують уваги. Це архітектурна рекомендація, а не гарантія мінімальних витрат для кожного облікового запису.
- Надавайте пріоритет активним відправленням і записам із невирішеними помилками отримання.
- Не запитуйте кожне історичне відправлення під час кожного запланованого запуску.
- Визначте, як обробляються завершені відправлення, зокрема будь-який період виправлень, потрібний вашому бізнесу.
- Відстежуйте, як часто запити знаходять справді нову інформацію.
- Розслідуйте проблеми доставки вебхуків, а не приховуйте їх дедалі частішим опитуванням.
Відстежуйте затримку запитів до провайдера, невдалі запити, відповіді про перевищення ліміту та відмінності між даними запитів і записами, отриманими через вебхуки. Окремо контролюйте вік останньої події перевізника. Успішні відповіді API можуть співіснувати з інформацією про відстеження, яка не змінилася.
Протестуйте процес перед випуском
Успішний запит — лише перша перевірка. Переконайтеся, що система коректно обробляє ситуації, які інакше можуть створювати оманливі оновлення статусу:
- Вебхук надходить, коли запит на вимогу ще виконується.
- Двоє клієнтів або працівників одночасно запитують те саме відправлення.
- Провайдер повертає HTTP-успіх, але повідомляє про помилку на рівні відправлення.
- Запит завершується помилкою після того, як застосунок уже має дійсну інформацію про відстеження.
- Подія не містить часового поясу або містить незнайомий код статусу.
- Виправлення перевізника змінює раніше показаний результат.
- Користувач намагається отримати доступ до відправлення, що належить іншому обліковому запису.
Критерієм випуску має бути те, що застосунок повертає найкращу відому інформацію про відправлення, точно пояснює її актуальність і не пошкоджує цю інформацію, коли запити завершуються помилкою або надходять не в тому порядку.
FAQ
Чи змушує запит до API перевізника сканувати або оновлювати посилку?
Ні. Отримання інформації про відстеження не може спричинити фізичне сканування. Чи запускає запит перевірку на стороні джерела, залежить від задокументованої операції. Навіть підтримуване оновлення може повернути незмінену інформацію, якщо у перевізника немає новішої події.
Чи можна використовувати API-запити без налаштування вебхуків?
Якщо провайдер підтримує необхідний процес запитів, ви можете побудувати інтеграцію на запитах на вимогу або опитуванні. Спочатку підтвердьте вимоги до реєстрації та запитів. Після цього ваш застосунок відповідатиме за визначення часу перевірки, контроль обсягу запитів і виявлення змін.
Як часто потрібно опитувати статус відправлення?
Універсального інтервалу не існує. Обирайте розклад, який відповідає обмеженням провайдера, обсягу відправлень і цінності швидшого отримання оновлень для бізнесу. Вимірюйте, як часто опитування повертає нові події, і коригуйте розклад, а не припускайте, що часті запити забезпечують актуальніші дані перевізника.
Чому API повертає інформацію, яку я вже отримав через вебхук?
Обидва шляхи можуть надавати доступ до одного базового запису відправлення. Вебхук доставляє сповіщення, а запит отримує інформацію на вимогу. Отримання тієї самої події через обидва шляхи не обов’язково є помилкою; ваш застосунок має усувати дублікати.
Чи має кнопка оновлення називатися «Оновити відстеження»?
Лише якщо це формулювання точно описує операцію. Якщо кнопка отримує збережені дані провайдера, зрозумілішим буде напис «Перевірити наявність оновлень». Показуйте час останньої події перевізника окремо від часу останньої успішної перевірки застосунком.
Джерела
- 17TRACK Tracking API — офіційний опис продукту для інтеграції API відстеження, розглянутої в цьому посібнику.
- Документація 17TRACK API — довідкова інформація про специфічні для провайдера операції, автентифікацію, поля запитів та обробку відповідей.
- RFC 9110, розділ 10.2.3: Retry-After — визначає форми HTTP-заголовка delay-seconds і HTTP-date.


