Skip to main content
ГоловнаБлогПосібникиРобочий процес API відстеження відправлень: від реєстрації відправлення до отримання даних про відстеження

Робочий процес API відстеження відправлень: від реєстрації відправлення до отримання даних про відстеження

17TRACK

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

Робочий процес API відстеження від реєстрації відправлення до отримання даних

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

Зрозумійте, що робить реєстрація, а чого вона не робить

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

У застосунку розділяйте три результати:

  • Запит отримано: API повернув відповідь на ваш HTTP-запит.
  • Реєстрацію прийнято: Сервіс прийняв окремий запис відстеження для обробки.
  • Інформація про відстеження доступна: Сервіс має інформацію про відправлення, яку ваш застосунок може отримати або прийняти.

Ці результати не слід об’єднувати в один прапорець «успішно». Прийнятий номер відстеження може ще не мати подій перевізника. Так само успішна HTTP-відповідь на пакетний запит не означає, що кожен елемент пакета було прийнято; перевіряйте структуру результату на рівні застосунку, визначену постачальником.

1. Підготуйте ідентифікацію відправлення та конфігурацію API

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

Корисний внутрішній запис містить такі відомості. Це рекомендовані поля застосунку, а не схема запиту 17TRACK.

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

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

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

2. Зареєструйте відправлення та збережіть результат для окремого елемента

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

Наведений нижче псевдокод ілюструє послідовність дій у застосунку. Назви функцій є умовними; вони не є кінцевими точками API або методами SDK.

shipment = load_internal_shipment(shipment_id)
validate_tracking_input(shipment)

result = tracking_adapter.register(shipment)

if result.item_accepted:
    save_registration_result(shipment_id, result)
elif result.outcome_unknown:
    schedule_registration_reconciliation(shipment_id)
else:
    save_registration_error(shipment_id, result)
    route_for_retry_or_correction(result)

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

Обробляйте пакетні надсилання окремо

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

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

Розглядайте тайм-аути як невідомий результат

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

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

3. Дочекайтеся появи першої інформації про відстеження

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

Явно представляйте цей стан. «Зареєстровано; очікується інформація про відстеження» точніше, ніж «У дорозі» або «Реєстрація не вдалася». Не вигадуйте прогноз доставки чи подію переміщення, щоб заповнити порожній інтерфейс.

Якщо запис залишається порожнім, перевіряйте в такому практичному порядку:

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

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

4. Отримуйте деталі відстеження та правильно їх інтерпретуйте

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

Ваш застосунок має розрізняти три рівні інформації:

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

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

Зберігайте час події окремо від часу отримання

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

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

Зберігайте початковий зміст разом із нормалізованим статусом

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

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

5. Підтримуйте актуальність записів за допомогою опитування або вебхуків

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

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

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

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

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

6. Перетворюйте інформацію відстеження на безпечні бізнес-дії

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

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

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

Застосування робочого процесу до інтеграції з 17TRACK

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

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

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

Перевірки перед запуском, які допомагають уникнути дорогих помилок

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

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

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

Чи створює реєстрація номера відстеження відправлення?

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

Чому деталі відстеження порожні після успішної реєстрації?

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

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

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

Що використовувати — опитування чи вебхуки?

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

Чи можу я використовувати номер відстеження як єдиний ідентифікатор відправлення в базі даних?

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

Джерела

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