Як зареєструвати номер відстеження через API: поля запиту, коди перевізників і відповіді
Щоб зареєструвати номер відстеження через API, надішліть автентифікований запит на реєстрацію, що містить номер відстеження відправлення та, якщо потрібно, ідентифікатор перевізника. Потім перевірте відповідь для кожного надісланого відправлення, а не лише статус HTTP, і збережіть інформацію про те, чи реєстрація успішна, невдала або залишається невизначеною. Реєстрація запускає процес відстеження, але не доводить, що перевізник відсканував посилку або що події відстеження вже доступні.
Цей посібник призначений для розробників, які підключають систему керування замовленнями, складський застосунок або платформу електронної комерції до API відстеження. У ньому 17TRACK використовується як конкретний приклад інтеграції та пояснюється, які деталі необхідно перевірити в документації для вибраної версії API.
Що робить реєстрація — і чого вона не робить
Запит на реєстрацію повідомляє сервісу відстеження, яке відправлення ви хочете відстежувати. Це відрізняється від придбання транспортної етикетки, замовлення забору або запиту до перевізника на створення відправлення. У типовій інтеграції процес доставки спочатку створює номер відстеження, а ваш застосунок реєструє цей номер після цього.
Розділяйте ці три події у своєму застосунку:
- Відправлення створено: ваша система доставки призначила номер відстеження.
- Реєстрацію прийнято: сервіс відстеження прийняв відправлення для відстеження.
- Інформацію про відстеження отримано: події перевізника стали доступними через сервіс відстеження.
Не змінюйте статус замовлення на «у дорозі» лише тому, що реєстрацію успішно виконано. Щойно створена етикетка може ще не мати фізичного сканування під час приймання. Статус відправлення, який бачить клієнт, має визначатися подіями відстеження, інтерпретованими за вашими правилами зіставлення статусів, а не відповіддю на реєстрацію.
Для інтеграцій із 17TRACK почніть з огляду Tracking API і використовуйте офіційну документацію API як джерело інформації щодо кінцевих точок, визначень полів, автентифікації та кодів відповіді. Наведені нижче приклади зосереджені на реєстрації, а не на окремих завданнях отримання результатів або приймання оновлень.
Підготуйте поля запиту перед написанням виклику API
Найкорисніша підготовка — це невеликий контракт полів між вашою системою доставки та інтеграцією відстеження. Визначте, звідки походить кожне значення, чи може воно бути відсутнім і як його перевірятимуть.
| Поле або значення | Призначення | Правило реалізації |
|---|---|---|
| Номер відстеження | Ідентифікує відправлення для відстеження. | Зберігайте та передавайте його як рядок; зберігайте початкові нулі. |
| Ідентифікатор перевізника | Ідентифікує перевізника в системі постачальника відстеження. | Використовуйте ідентифікатор, задокументований постачальником, а не внутрішній код складу. |
| Внутрішнє посилання | Пов’язує реєстрацію із записом вашого відправлення. | Використовуйте підтримуване поле посилання, якщо воно доступне; у будь-якому разі зберігайте власне зіставлення в базі даних. |
| Додаткові ідентифікаційні дані | Можуть допомогти ідентифікувати відправлення, якщо перевізнику потрібно більше, ніж номер відстеження. | Передавайте лише поля, задокументовані для цієї інтеграції та перевізника. |
| Облікові дані API | Автентифікують обліковий запис, що здійснює виклик. | Зберігайте їх на сервері та виключайте з журналів застосунку. |
Розглядайте номер відстеження як ідентифікатор
Ніколи не перетворюйте номер відстеження на ціле число. Числове перетворення може видалити початкові нулі, а великі значення в деяких програмних середовищах можуть втратити точність. Видаляйте випадкові пробіли на початку та в кінці, але не видаляйте розділові знаки й не змінюйте регістр літер, якщо відповідна документація або формат перевізника не підтримує таку нормалізацію.
Перевіряйте очевидні помилки введення до виклику API: порожні рядки, неочікувані переноси рядків і номер замовлення, скопійований у поле номера відстеження. Не встановлюйте єдине універсальне правило довжини або символів для всіх перевізників. Правило перевірки, що підходить одному перевізнику, може відхилити коректні номери іншого.
Зберігайте посилання на замовлення окремо від ідентифікаторів відправлень
Замовлення може містити кілька посилок, а повторне відправлення може мати інший номер відстеження. Моделюйте реєстрацію на рівні відправлення або посилки, а не припускайте наявність одного номера відстеження на замовлення.
Якщо ви використовуєте тег або поле посилання, підтримуване постачальником, надавайте перевагу непрозорому посиланню на відправлення, а не електронній або поштовій адресі клієнта. Ваша власна база даних має залишатися авторитетним зв’язком між замовленнями, відправленнями, номерами відстеження та зіставленнями перевізників.
Виберіть правильний код перевізника
Код перевізника не обов’язково є універсальним галузевим ідентифікатором. Значення, яке розпізнає платформа відстеження, може відрізнятися від назви перевізника, що зберігається у вашому програмному забезпеченні доставки. Навіть дві системи, які використовують числові коди, можуть призначати різні номери одному й тому самому перевізнику.
Підтримуйте явне зіставлення між вашою службою доставки та ідентифікатором перевізника постачальника відстеження. За потреби розрізняйте регіональну операцію або послугу перевізника та його ширший бренд. Зіставлення, засноване лише на назві, що відображається, може стати неоднозначним, якщо системи доставки використовують псевдоніми.
- Коли перевізник відомий: використовуйте задокументований ідентифікатор перевізника, якщо він підтримується, особливо коли формати номерів відстеження перетинаються.
- Коли перевізник невідомий: використовуйте автоматичне визначення лише через задокументований механізм. Не припускайте, що відсутність значення, порожній рядок, нуль і null означають одне й те саме.
- Коли результат виглядає неправильним: перевірте оригінальну етикетку, службу доставки та зіставлення, перш ніж повторно реєструвати той самий номер.
Автоматичне визначення корисне, але не є доказом того, що певний перевізник фізично має відправлення. Так само коректний код перевізника не гарантує, що наданий номер відстеження належить цьому перевізнику.
Зберігайте зіставлення перевізників у конфігурації, а не розподіляйте їх по коду застосунку. Фіксуйте дату останньої перевірки зіставлення та додавайте відоме відправлення до регресійних тестів щоразу, коли змінюєте його.
Приклад: надішліть запит на реєстрацію 17TRACK
Наведений нижче приклад ілюструє кінцеву точку реєстрації 17TRACK v2.2, заголовок автентифікації 17token і масив, що містить один об’єкт номера відстеження. Перед розгортанням переконайтеся, що ця версія та її вимоги до запиту відповідають вашому обліковому запису й офіційній документації. Номер відстеження є заповнювачем і має бути замінений реальним ідентифікатором відправлення.
curl --request POST \
--url 'https://api.17track.net/track/v2.2/register' \
--header "17token: ${TRACKING_API_TOKEN}" \
--header 'Content-Type: application/json' \
--data '[
{
"number": "YOUR_TRACKING_NUMBER"
}
]'
Цей мінімальний приклад не демонструє вибір перевізника або додаткові поля, специфічні для перевізника. Перегляньте документацію щодо реєстрації, щоб визначити, як працює визначення перевізника, якщо поле перевізника не вказано, і чи потребує ваше відправлення додаткової інформації. Якщо ви вказуєте перевізника, використовуйте задокументоване поле carrier та ідентифікатор, очікуваний цією версією API.
Виконуйте цей запит із серверного середовища. Не вбудовуйте токен у загальнодоступну вітрину, браузерний скрипт або мобільний застосунок, що розповсюджується серед клієнтів. Змінна середовища зручна для локального прикладу; у виробничих розгортаннях слід використовувати засоби керування секретами вашої організації.
Перш ніж збільшувати обсяг, протестуйте одне відоме відправлення та перевірте повну відповідь. Потім протестуйте некоректне введення й пакет, що містить одночасно коректні та некоректні елементи. Ці перевірки покажуть, чи справді ваша інтеграція обробляє результати на рівні елементів, а не лише розпізнає успішну відповідь HTTP.
Читайте відповідь на трьох рівнях
Надійний обробник відповіді має відповісти на три окремі запитання: чи досяг запит сервісу, чи прийняв сервіс операцію та що сталося з кожним відправленням?
1. Результат HTTP і транспорту
Тайм-аут з’єднання, помилка TLS або перервана відповідь не обов’язково повідомляють, чи обробив сервер запит. Позначте такий результат як невизначений, доки не зможете його узгодити. Успішний статус HTTP підтверджує успішний обмін HTTP, але вам усе одно потрібно перевірити відповідь застосунку.
2. Результат на рівні запиту
Перевірте задокументований результат верхнього рівня API та поля помилок. Помилки автентифікації, некоректний JSON і обмеження облікового запису потребують різних дій. Зберігайте оригінальний код і повідомлення про помилку постачальника, а не зводьте кожну помилку до «відстеження недоступне».
Не припускайте, що числовий код застосунку має те саме значення, що й код статусу HTTP. Їхні значення походять із різних рівнів і мають інтерпретуватися окремо.
3. Результат на рівні відправлення
Під час пакетної реєстрації враховуйте кожен надісланий елемент. Відповідь може розрізняти прийняті та відхилені відправлення; ваш аналізатор має дотримуватися точної схеми, задокументованої для вибраної версії. Не позначайте весь пакет як зареєстрований лише тому, що один елемент виконано успішно.
Нормалізуйте відповіді постачальника до власних стабільних станів застосунку. Наприклад, ваша база даних може використовувати accepted, rejected і uncertain. Це запропоновані внутрішні стани, а не буквальні значення відповідей 17TRACK. Зберігайте оригінальну відповідь постачальника відповідно до належної політики зберігання та доступу, щоб розробники могли досліджувати розбіжності.
Корисний запис реєстрації містить внутрішній ідентифікатор відправлення, надісланий номер, вибраного перевізника, час спроби, версію API, результат і відомості про помилку постачальника. Зберігайте статус реєстрації окремо від статусу доставки.
Обробляйте повторні спроби, не створюючи нескінченний цикл
Політика повторних спроб має залежати від помилки, а не просто від того, чи виник виняток.
- Некоректне введення: виправте поле перед повторною спробою. Повторне надсилання незмінного некоректного запиту навряд чи допоможе.
- Помилка автентифікації: перевірте облікові дані та конфігурацію облікового запису. Не надсилайте повторно той самий пакет, що завершується помилкою.
- Обмеження частоти: дотримуйтеся задокументованих лімітів і відповідних інструкцій щодо повторних спроб. Використовуйте обмежену затримку зі збільшенням інтервалу, а не негайні паралельні повтори.
- Тимчасовий збій сервісу: повторюйте спробу в межах визначених бюджету кількості спроб і часу.
- Тайм-аут після надсилання: узгодьте стан реєстрації відправлення відповідно до задокументованої поведінки API, перш ніж вважати першу спробу невдалою.
- Відповідь, пов’язана з дублюванням: перевірте, чи не зареєстровано відправлення вже та чи правильно його пов’язано із записом вашого застосунку.
Не припускайте, що реєстрація є ідемпотентною, якщо документація прямо не визначає таку поведінку. Дедуплікація на рівні застосунку зменшує кількість випадкових повторних надсилань, але не встановлює політику постачальника щодо обробки дублікатів.
Використовуйте внутрішнє правило унікальності, що відповідає вашій моделі відправлень. Самого номера відстеження може бути недостатньо як постійного ключа для різних перевізників і тривалих періодів зберігання. Зберігайте контекст перевізника та власний ідентифікатор відправлення й документуйте обробку замін і виправлених номерів.
Відстежуйте реєстрацію окремо від оновлень відстеження
Моніторинг API має розрізняти збій інтеграції та відправлення, для якого просто немає нової події перевізника. Ці умови потребують різних відповідальних осіб і різних виправлень.
Для реєстрації відстежуйте кількість прийнятих і відхилених запитів, категорії помилок, невизначені результати, чергу повторних спроб і затримку відповіді. Для подальшого відстеження окремо відстежуйте отримання оновлень або помилки їх отримання. Не встановлюйте числові пороги сповіщень, доки не зрозумієте нормальний трафік і задокументовані робочі ліміти постачальника.
Практична виробнича перевірка має відповісти на такі запитання:
- Чи має кожне відправлення, що очікує на відстеження, запис реєстрації?
- Чи можна кожну прийняту реєстрацію простежити до правильної посилки?
- Чи спрямовуються відхилені елементи до особи, яка може виправити базові дані?
- Чи узгоджуються невизначені запити, а не залишаються без уваги або повторюються нескінченно?
- Чи формуються статуси, що бачить клієнт, на основі подій відправлення, а не прийняття реєстрації?
- Чи виключені з журналів облікові дані та непотрібна особиста інформація?
Для операцій електронної комерції операційна передача важлива не менше, ніж сам виклик API. Розробники мають відповідати за транспортні помилки та помилки аналізу; команди доставки або виконання замовлень повинні мати змогу досліджувати неправильні етикетки, зіставлення перевізників і відсутню інформацію про відправлення.
FAQ
Чи можна зареєструвати номер відстеження до першого сканування перевізником?
Реєстрація та сканування перевізником — це окремі події. Сервіс може прийняти номер до того, як події відстеження стануть доступними, відповідно до його правил перевірки. Не трактуйте прийняття як доказ того, що перевізник отримав посилку.
Чи завжди потрібно надавати код перевізника?
Це залежить від задокументованої поведінки API щодо визначення та конкретного відправлення. Якщо перевізник відомий, явний правильно зіставлений ідентифікатор може зменшити неоднозначність. Якщо він невідомий, використовуйте задокументований метод автоматичного визначення, а не вигадуйте значення перевізника.
Чому API повернув успішний HTTP-результат, хоча відправлення не пройшло?
HTTP-запит може завершитися успішно, тоді як застосунок відхилить окремий елемент. Читайте результат застосунку верхнього рівня та результати на рівні відправлення. Це розрізнення особливо важливе для пакетних запитів.
Що робити, якщо час очікування запиту на реєстрацію минув?
Вважайте результат невизначеним. Сервер міг обробити запит до того, як з’єднання було перервано. Перевірте задокументовану поведінку постачальника щодо дублікатів і доступні методи пошуку реєстрації або відстеження, а потім узгодьте результат або повторіть спробу в межах обмеженої політики.
Чи налаштовує реєстрація сповіщення про відстеження автоматично?
Не припускайте, що це так. Реєстрація, отримання даних відстеження та налаштування вебхуків — це окремі питання інтеграції. Перевірте відповідну документацію та протестуйте повний шлях оновлення, перш ніж покладатися на нього для сповіщень клієнтів.
Джерела
- Документація API 17TRACK — джерело інформації щодо кінцевих точок реєстрації, автентифікації, полів запиту, ідентифікаторів перевізників, схем відповідей та обробки помилок. Узгоджуйте деталі реалізації з версією API, яку розгортаєте.
- Огляд Tracking API 17TRACK — офіційна відправна точка для продукту tracking API та ресурсів інтеграції для розробників.


