Як уніфікувати відстеження відправлень в Австралії та Новій Зеландії за допомогою одного API
Щоб уніфікувати відстеження відправлень в Австралії та Новій Зеландії за допомогою одного API, підключіть систему керування замовленнями або виконання замовлень до сервісу відстеження з підтримкою кількох перевізників, зареєструйте кожне відправлення з правильною ідентифікацією перевізника та перетворюйте вхідні оновлення відстеження на узгоджену внутрішню модель подій. Інтеграція має зберігати специфічні для перевізника деталі, водночас забезпечуючи вашій операційній команді та клієнтам єдиний досвід відстеження внутрішніх і транстасманських доставок.
Для розробників, операторів електронної торгівлі та логістичних команд основна проблема полягає не в тому, щоб виконати перший API-запит. Важливо забезпечити узгодженість ідентифікаторів відправлень, статусів доставки, передачі між перевізниками та сповіщень клієнтів, коли різні перевізники по-різному описують один і той самий маршрут. У цьому посібнику пояснюється, як спроєктувати таку інтеграцію, оцінити API відстеження та протестувати його перед використанням у робочому середовищі.
Визначте, що саме має уніфікувати єдиний API
Спільний API надає вашому застосунку єдину точку інтеграції. Він не змушує всіх перевізників публікувати однакову інформацію або сканувати посилки з однаковою частотою. Ваша архітектура має розрізняти узгоджений інтерфейс і повну видимість.
Почніть з переліку відправлень, сформованого на основі фактичної діяльності з виконання замовлень, а не загального списку перевізників, що працюють у будь-якій із цих країн. Додайте внутрішні австралійські відправлення, внутрішні новозеландські відправлення та транскордонні переміщення в обох напрямках. Додайте інші країни походження, якщо вони є частиною вашого бізнесу.
- Перевізник і послуга: зафіксуйте перевізника, використану послугу та будь-якого відомого партнера з доставки.
- Маршрут: відокремте походження й пункт призначення відправлення від місця останнього сканування.
- Ідентифікатори: зберігайте посилання на замовлення, посилання на виконання замовлення, номер відстеження та будь-який замінений або партнерський номер.
- Операційна мета: визначте, чи підтримують оновлення відстеження клієнтами, керування винятками, підтвердження доставки або всі три процеси.
- Необхідні деталі: вирішіть, чи достатньо загального статусу доставки, чи агентам також потрібні описи сканувань, місця та часові позначки.
Цей перелік стане вашим контрольним списком приймання. Загальне охоплення перевізників постачальником корисне для попереднього відбору, але рішення має ґрунтуватися на тому, чи повертають ваші фактичні комбінації перевізників і послуг придатну для використання інформацію про відстеження.
Оцініть API відстеження на відповідність вашому набору відправлень
17TRACK пропонує Tracking API, тому його варто розглянути для інтеграції з кількома перевізниками. Скористайтеся офіційною документацією API, щоб перевірити актуальні вимоги до інтеграції. Розглядайте підтримку перевізників, поля подій, поведінку оновлень, ліміти облікового запису та комерційні умови як параметри, які потрібно перевірити для вашої реалізації, а не як припущення, зроблені на основі категорії продукту.
Поставте будь-якому API, який розглядаєте, однакові практичні запитання:
- Чи може він визначати та відстежувати перевізників і послуги з вашого переліку відправлень?
- Якщо визначення перевізника неоднозначне, чи можете ви передати явний ідентифікатор перевізника?
- Як ваш застосунок отримує оновлення та який механізм відновлення доступний, якщо оновлення пропущено?
- Які вихідні дані перевізника залишаються доступними разом із нормалізованими статусами?
- Що відбувається, коли номер відстеження недійсний, ще не розпізнаний або пов’язаний із кількома можливими перевізниками?
- Як визначаються використання, виставлення рахунків, тривалість відстеження та ліміти доступу для вашого облікового запису?
Рекомендоване правило прийняття рішення: обирайте на основі успішного тестування ваших реальних моделей доставки, а не найбільшої заявленої кількості перевізників. Інтеграція є придатною, якщо вона надає достатньо інформації для підтримки ваших операційних рішень і достатньо чітко показує помилки, щоб їх можна було виправити.
Створіть внутрішню модель, стійку до відмінностей між перевізниками
Розділяйте замовлення, відправлення та етапи відстеження
Не використовуйте номер відстеження як первинний ключ замовлення. Одне замовлення може містити кілька посилок, а маршрут посилки може охоплювати більше одного ідентифікатора відстеження. Натомість створіть внутрішній ідентифікатор відправлення та прив’яжіть до нього записи відстеження.
Практична модель має три рівні: замовлення клієнта, його фізичні відправлення та етапи відстеження, пов’язані з кожним відправленням. Для внутрішньої посилки може бути потрібен лише один етап відстеження. Для транскордонної посилки можуть знадобитися пов’язані записи, коли стає актуальним інший перевізник або ідентифікатор.
Визначайте запис відстеження як за перевізником, так і за номером відстеження та зберігайте його зв’язок із внутрішнім ідентифікатором відправлення. Якщо з’являється новий номер партнера з доставки, додайте його як пов’язаний ідентифікатор, а не перезаписуйте початковий. Це зберігає історію, потрібну агентам підтримки під час розслідування передачі.
Зберігайте необроблену та нормалізовану події
Використовуйте невеликий внутрішній словник статусів, на основі якого ваш бізнес може діяти. Наприклад, можна визначити такі статуси: до транзиту, у дорозі, передано кур’єру для доставки, доступно для отримання, доставлено, виняток і невідомо. Це запропоновані внутрішні категорії, а не твердження про схему статусів конкретного постачальника.
Зберігайте оригінальний опис перевізника разом із відображеним статусом. Подія в пункті отримання та проблема з адресою можуть вимагати дій клієнта, але не повинні створювати однакове повідомлення. Так само створення етикетки не має автоматично свідчити про те, що перевізник фізично отримав посилку.
Документуйте рішення щодо відображення у версійованій конфігурації. Коли з’являється новий опис події, помістіть його в чергу на перевірку, якщо його значення незрозуміле. Явний невідомий стан безпечніший, ніж упевнене призначення неправильного результату доставки.
Розрізняйте час події та час отримання
Зберігайте час виникнення події окремо від часу її отримання вашою системою. Старіше сканування може надійти після новішого, особливо коли оновлення затримуються або історичні події надходять разом.
Для Австралії та Нової Зеландії не застосовуйте один фіксований часовий зсув до всіх відправлень. Зберігайте часові позначки та зсуви джерела, якщо вони надані. Для відображення використовуйте відповідний іменований часовий пояс, коли маєте надійний контекст місця, і враховуйте відмінності, пов’язані з переходом на літній час. Якщо часовий пояс джерела відсутній, зберігайте цю невизначеність, а не вигадуйте точне перетворення в UTC.
Реалізуйте надійний процес отримання даних
- Спочатку створіть внутрішнє відправлення. До реєстрації в сервісі відстеження зафіксуйте його зв’язок із замовленням, маршрут, вибраного перевізника та ідентифікатор відстеження.
- Надішліть реєстрацію відстеження. Використовуйте задокументований формат запиту постачальника. Зберігайте відповідь і розрізняйте успішну реєстрацію та подальшу доступність подій перевізника.
- Класифікуйте помилки. Відокремлюйте недійсні вхідні дані та проблеми автентифікації від тимчасових збоїв сервісу. Повторюйте запит лише там, де це обґрунтовано може допомогти.
- Отримуйте або завантажуйте оновлення. Реалізуйте механізм доставки, який підтримує вибраний API. Якщо використовуєте вебхуки, перевіряйте вхідні запити задокументованим постачальником методом і обробляйте прийняті події через надійну чергу.
- Усувайте дублікати до застосування змін. За можливості використовуйте ідентифікатор події постачальника або ретельно спроєктований складений ключ. Повторна доставка не повинна спричиняти повторні сповіщення клієнтів.
- Перераховуйте стан відправлення. Оцінюйте значення та хронологію подій, а не замінюйте поточний статус оновленням, яке надійшло останнім.
- Узгоджуйте неповні записи. Якщо API підтримує отримання даних, використовуйте його для перевірки пропущених оновлень або застарілих записів у межах застосовних лімітів використання.
Зберігайте автентифікацію, назви полів і обробку помилок, специфічні для постачальника, всередині адаптера. Ваша система керування замовленнями має використовувати внутрішню модель відправлення, а не безпосередньо залежати від кожної деталі відповіді постачальника. Таке розділення також спрощує тестування майбутніх змін API.
Обробляйте транстасманські маршрути без вигадування визначеності
Транскордонне відстеження потребує більше контексту, ніж послідовність статусів. Ваш застосунок має розрізняти подію експорту, митну подію, передачу перевізнику та подію фінальної доставки, коли вихідні дані дають змогу це зробити.
Не робіть висновок про митне оформлення із загального сканування «у дорозі». Так само відсутність недавнього сканування не означає, що митниця утримує посилку. Корисне повідомлення клієнту містить останню підтверджену подію та її час, а потім пояснює будь-яку наступну дію, яку ваша команда справді може підтримати.
Зберігайте походження та пункт призначення окремо від місця сканування. Відправлення з Австралії до Нової Зеландії не стає внутрішнім новозеландським відправленням лише тому, що отримало сканування прибуття. Це розрізнення важливе для звітності за маршрутами та відповідальності за винятки.
Перетворюйте події відстеження на корисні оновлення для клієнтів
Сторінка для клієнтів має відповідати на чотири запитання: який останній підтверджений статус, коли це сталося, де це було зафіксовано, якщо відомо, і чи потрібно клієнту діяти?
Тримайте правила сповіщень окремо від отримання подій. Не кожне сканування заслуговує на електронний лист або текстове повідомлення. Визначте важливі переходи, як-от перше підтверджене переміщення, спроба доставки, необхідність отримання або подія доставки, і пригнічуйте повторні сповіщення для того самого переходу.
- Застаріле відстеження: вказуйте час останнього оновлення, не трактуючи тишу як доказ втрати.
- Оцінки доставки: розрізняйте оцінку перевізника та обіцянку продавця. Не вигадуйте дату, якщо жодної з них немає.
- Винятки: якщо відомо, надавайте конкретний наступний крок, а не показуйте незрозумілу мітку помилки.
- Суперечки щодо доставки: зберігайте вихідну подію та передавайте справу до служби підтримки; сам статус «доставлено» не вирішує кожну суперечку клієнта.
Проведіть пілотне тестування за маршрутами до запуску
Протестуйте внутрішні австралійські, внутрішні новозеландські, австралійсько-новозеландські та новозеландсько-австралійські відправлення, якщо такі маршрути актуальні для вашого бізнесу. Додайте звичайні доставки та операційні крайні випадки: розділені замовлення, нерозпізнані номери, передачі, спроби доставки, події отримання, повернення та сканування, що надійшли із запізненням.
- Перевірка ідентичності: кожне оновлення надходить до правильного відправлення та замовлення.
- Перевірка хронології: події, що надійшли не по порядку, не змінюють помилково перебіг доставки назад.
- Перевірка відновлення: тимчасові помилки та дублікати оновлень не спричиняють втрати даних або повторних сповіщень.
- Перевірка підтримки: агенти можуть переглянути вихідну подію та зрозуміти статус, видимий клієнту.
- Комерційна перевірка: очікуване використання відповідає підтвердженій моделі виставлення рахунків і лімітам облікового запису.
Реалізація готова, коли ваша команда може пояснити неповне відстеження та відновити його, а не лише показати успішні доставки. Один API спрощує підключення; ваша модель відправлень, правила подій і операційні процедури роблять це підключення надійним.
FAQ
Чи замінює один API відстеження інтеграції з перевізниками?
Не обов’язково. Відстеження, створення етикеток, бронювання забору, розрахунок тарифів і митна документація — це окремі функції. Перевірте сферу застосування вибраного продукту та збережіть інші інтеграції, якщо вони потрібні вашому процесу виконання замовлень.
Чи можу я зареєструвати номер відстеження до першого сканування перевізником?
Перевірте правила реєстрації API. Спроєктуйте застосунок так, щоб він розрізняв прийняту реєстрацію відстеження та підтверджене фізичне переміщення. Запис без подій не повинен автоматично відображатися як такий, що перебуває в дорозі.
Чи надасть один API оновлення в реальному часі для кожного перевізника?
Не припускайте цього. Актуальність від початку до кінця залежить від того, коли перевізник публікує дані, коли сервіс відстеження їх отримує та коли ваш застосунок їх обробляє. Підтвердьте поведінку оновлень для комбінацій перевізників і послуг, які використовуєте.
Що має відбутися, коли номер відстеження змінюється?
Збережіть початковий ідентифікатор і додайте підтверджений замінений або партнерський ідентифікатор до того самого внутрішнього відправлення. Збережіть обидві історії та не допускайте, щоб дублікати записів створювали суперечливі сповіщення.
Чи актуальний 17TRACK для цієї інтеграції?
Так. Його Tracking API відповідає описаній тут інтеграції з кількома перевізниками. Оцініть його на зразках ваших австралійських і новозеландських відправлень та підтвердьте підтримку перевізників, технічну поведінку й умови облікового запису через офіційні ресурси API до розгортання.
Джерела
- 17TRACK Tracking API — офіційний ресурс продукту для API, розглянутого в цьому посібнику.
- Документація 17TRACK API — офіційний технічний довідник для перевірки форматів запитів, вимог до інтеграції та підтримуваної поведінки.
