Як відстежувати відправлення з Китаю до Європи та США за допомогою одного API

Щоб відстежувати відправлення з Китаю до Європи та США за допомогою одного API, підключіть свою систему замовлень до сервісу відстеження з підтримкою кількох перевізників, зареєструйте кожну посилку за її трек-номером і всіма необхідними даними перевізника та додайте оновлення відстеження до спільного запису про відправлення. Інтеграція має враховувати міжнародні передачі, затримки сканування та окремі трек-номери для доставки на останній милі. Один API може об'єднати доступ до інформації про відстеження, але не може створювати події, про які перевізник не повідомляв.

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

Починайте з маршруту доставки, а не лише з країни призначення

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

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

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

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

Що має робити один API відстеження — і чого він не може робити

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

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

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

Побудуйте інтеграцію навколо запису на рівні посилки

1. Розділяйте замовлення, відправлення та ідентифікатори відстеження

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

Практична внутрішня модель має містити:

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

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

2. Реєструйте посилки на основі надійної бізнес-події

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

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

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

3. Спроєктуйте доставку оновлень до підключення сповіщень клієнтам

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

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

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

4. Нормалізуйте статуси, не втрачаючи змісту

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

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

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

Явно обробляйте міжнародні передачі

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

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

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

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

Роль 17TRACK у цьому робочому процесі

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

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

Основна причина вибрати об'єднаний API — зменшення складності інтеграції для маршрутів, якими ви фактично користуєтеся. Цю перевагу все одно потрібно перевірити на репрезентативних посилках. Жодного постачальника не слід обирати лише тому, що опис його загального покриття звучить широко.

Проведіть пілотне тестування на основі маршрутів до запуску

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

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

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

Відстежуйте свіжість даних окремо від доступності API

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

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

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

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

FAQ

Чи може один API відстежувати як китайського перевізника в пункті відправлення, так і перевізника доставки в пункті призначення?

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

Чому відстеження припиняє оновлюватися після того, як посилка залишає Китай?

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

Чи має застосунок використовувати вебхуки чи опитування?

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

Чи може API відстеження гарантувати дату доставки або митне оформлення?

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

Що слід перевірити перед вибором тарифного плану API?

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

Джерела

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