Skip to main content
ГоловнаБлогПосібникиЯкі дані має повертати Tracking API? 12 полів, окрім поточного статусу?

Які дані має повертати Tracking API? 12 полів, окрім поточного статусу?

17TRACK

API відстеження має повертати більше, ніж просто мітку на кшталт «У дорозі». Окрім поточного статусу, шукайте ідентифікатори відправлення, дані перевізника, детальну інформацію про статус, оригінальні повідомлення перевізника, історію подій, часові мітки подій, місцезнаходження, орієнтовні строки доставки, винятки, передачу між перевізниками, деталі доставки та метадані актуальності даних. Разом ці 12 груп даних допомагають розробникам створювати надійні робочі процеси, а операційним командам — отримувати достатньо контексту для дій.

Які дані має повертати API відстеження: 12 полів понад поточний статус

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

Що робить дані відстеження корисними?

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

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

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

12 полів, які слід оцінити понад поточний статус

1. Ідентифікатори відправлення та відстеження

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

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

2. Ідентифікація перевізника

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

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

3. Нормалізована деталізація статусу

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

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

4. Оригінальні повідомлення та коди перевізника

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

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

5. Історія подій відстеження

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

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

6. Часові мітки подій та інформація про часовий пояс

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

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

7. Місцезнаходження подій і географія відправлення

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

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

8. Орієнтовна дата або період доставки

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

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

9. Причина винятку та необхідна дія

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

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

10. Передача між перевізниками та пов’язані номери відстеження

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

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

11. Результат доставки та посилання на підтвердження

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

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

12. Актуальність, стан отримання та метадані відповіді

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

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

Відсутні дані мають мати визначене значення

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

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

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

Як протестувати відповідь перед інтеграцією

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

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

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

Критерій приймання має бути практичним: чи може ваш застосунок пояснити стан відправлення без непідтверджених тверджень і чи може операційна команда визначити наступну обґрунтовану дію? Менше, але чітко визначене корисне навантаження може бути кориснішим за більшу відповідь, наповнену незрозумілими необов’язковими значеннями.

FAQ

Чи потрібно заповнювати всі 12 груп даних для кожного відправлення?

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

Чи слід зберігати необроблену відповідь або лише нормалізовані поля?

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

Яка часова мітка має визначати останню подію?

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

Чи може API відстеження підтвердити, що посилка втрачена?

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

Чи достатньо статусу «Доставлено», щоб закрити скаргу клієнта?

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

Джерела