Як надіслати кілька номерів відстеження в одному API-запиті (обмеження пакетної обробки та часткові збої)
Щоб надіслати кілька номерів відстеження в одному API-запиті, використовуйте кінцеву точку Tracking API, яка явно підтримує пакетну обробку, відформатуйте кожне відправлення відповідно до схеми її запиту та розділіть великі списки на пакети в межах задокументованих обмежень. Потім перевірте як HTTP-відповідь, так і результат для кожного відправлення: успішний HTTP-запит не обов’язково означає, що всі номери відстеження було прийнято. Повторно надсилайте лише придатні для повторної спроби невдалі записи та перевіряйте невизначені результати перед повторним надсиланням усього пакета.

Цей посібник призначений для розробників, які підключають відстеження відправлень до системи керування замовленнями, складської платформи, ecommerce-застосунку або внутрішньої інформаційної панелі. Мета полягає не лише в тому, щоб надсилати менше запитів. Потрібно враховувати кожне відправлення, не створюючи дубльовану роботу та не втрачаючи записи про невдалі операції.
Спочатку визначте, що саме робить кінцева точка пакетної обробки
Інтеграція відстеження може охоплювати кілька різних операцій. Реєстрація відправлень, отримання їхньої актуальної інформації про відстеження та отримання подальших оновлень — це не взаємозамінні операції.
- Реєстрація: Надсилання відправлень, щоб сервіс міг розпочати або продовжити їх відстеження.
- Пошук: Запит інформації про відстеження відправлень відповідно до правил отримання даних для цієї кінцевої точки.
- Оновлення доставки: Отримання подальших змін через підтримуваний механізм, наприклад вебхуки, або отримання їх за допомогою запланованих запитів.
Перевірте документацію, щоб визначити потрібну операцію. Те, що кінцева точка реєстрації приймає кілька записів, не означає, що кінцева точка пошуку приймає таку саму кількість, використовує ту саму схему або має той самий ліміт швидкості.
Для інтеграції з 17TRACK почніть зі сторінки продукту Tracking API та скористайтеся офіційною документацією API, щоб підтвердити операцію, метод автентифікації, формат запиту та поля відповіді. Розглядайте наведені нижче приклади як шаблони реалізації, а не як заміну контракту цього API.
Обмеження пакетів — це не лише максимальна кількість відправлень
Для Tracking API не існує універсального обмеження розміру пакета. Обмеження можуть відрізнятися залежно від постачальника, кінцевої точки, версії API та конфігурації облікового запису. Перед реалізацією пакетної обробки зафіксуйте ці обмеження окремо.
| Обмеження | Що потрібно підтвердити | Наслідок для реалізації |
|---|---|---|
| Кількість елементів у запиті | Максимальна кількість записів для конкретної операції | Розділити вхідний список перед надсиланням |
| Розмір тіла запиту | Будь-яке задокументоване обмеження в байтах | Враховувати необов’язкові поля та розмір серіалізованих даних |
| Швидкість запитів | Допустима кількість запитів за визначений інтервал | Регулювати запити через спільний обмежувач |
| Паралельність | Будь-яке обмеження на одночасні запити | Обмежити кількість активних працівників |
| Облік використання | Чи обчислюється використання за запитом, відправленням або іншою одиницею | Оцінювати споживання окремо від кількості запитів |
Наприклад, якщо гіпотетична кінцева точка дозволяє 25 записів у запиті, для 63 записів знадобляться три запити, що міститимуть 25, 25 і 13 записів. Ці числа лише ілюструють розподіл на частини; вони не є лімітами 17TRACK.
Не припускайте, що пакетна обробка зменшує оплачуване використання. Вона може зменшити накладні витрати HTTP-запитів, але вплив на вартість залежить від фактичних правил обліку постачальника. Так само допустимий розмір пакета не дає дозволу на необмежену кількість паралельних запитів.
Підготуйте записи перед формуванням запиту
Більшість помилок пакетної обробки, яких можна уникнути, починаються з підготовки вхідних даних. Перевіряйте кожне відправлення перед додаванням до пакета, але уникайте правил, які випадково відхиляють дійсні номери відстеження різних перевізників.
- Зберігайте номери відстеження як рядки. Перетворення на числа може видалити початкові нулі або змінити довгі ідентифікатори.
- Видаляйте випадкові пробіли на початку та в кінці. Не видаляйте внутрішні символи та не змінюйте регістр, якщо відповідна специфікація не дозволяє таку нормалізацію.
- Перевіряйте обов’язкові поля. Деякі робочі процеси можуть вимагати ідентифікатор перевізника або додаткову інформацію про відправлення. Використовуйте лише задокументовані назви полів і значення.
- Визначте явну область дедуплікації. Повторюваний номер відстеження не автоматично є дублікатом для кожного перевізника, продавця або історичного відправлення.
- Зберігайте локальний ідентифікатор відправлення. Зберігайте зв’язок між вихідним елементом і записом замовлення або відправлення, навіть якщо API не приймає власні поля посилань.
Для Carrier Tracking у різних мережах не визначайте перевізника лише за довжиною або префіксом номера відстеження, якщо такий висновок не є надійним у вашому конкретному робочому процесі. Якщо API підтримує ідентифікацію перевізника, дотримуйтеся задокументованої поведінки обробки неоднозначності.
Приклад структури запиту
Наведений нижче JSON демонструє концепцію корисного навантаження пакетного запиту. Обгортка, назви властивостей та ідентифікатори є ілюстративними, а не схемою запиту 17TRACK. Деякі API очікують масив верхнього рівня замість об’єкта, що містить масив.
{
"shipments": [
{
"tracking_number": "EXAMPLE000001",
"carrier_id": "DOCUMENTED_CARRIER_ID"
},
{
"tracking_number": "EXAMPLE000002",
"carrier_id": "DOCUMENTED_CARRIER_ID"
}
]
}Формуйте корисне навантаження за допомогою серіалізатора JSON, а не конкатенації рядків. Надсилайте облікові дані автентифікації через задокументований механізм і не зберігайте їх у системі контролю версій, коді, що доставляється браузеру, або звичайних журналах.
Обробляйте відповідь на двох рівнях
Пакетний запит має результат транспортного рівня та результат рівня застосунку. Інтеграція повинна оцінювати обидва.
Рівень 1: Чи отримав запит придатну для використання відповідь?
Почніть із HTTP-статусу, заголовків відповіді та тіла відповіді. Помилки автентифікації, неправильні запити, обмеження швидкості та помилки сервера можуть перешкодити нормальній обробці елементів. Мережевий тайм-аут відрізняється: клієнт може не знати, чи отримав сервер запит або обробив його.
Семантика HTTP визначена в RFC 9110. Однак документація постачальника визначає, як поля результату рівня застосунку відповідають фактичним результатам для відправлень.
Рівень 2: Що сталося з кожним відправленням?
Якщо відповідь підтримує результати на рівні елементів, класифікуйте кожен надісланий запис. Не припускайте, що HTTP 200 означає успіх кожного запису або що список результатів зберігає порядок запиту, якщо контракт явно цього не гарантує.
- Прийнято: Операція успішна відповідно до задокументованого визначення кінцевої точки.
- Постійна помилка вхідних даних: Виправте запис або дослідіть його перед новою спробою.
- Помилка, придатна для повторної спроби: Заплануйте нову спробу відповідно до рекомендацій постачальника.
- Невідомий результат: Відповідь відсутня, неповна або її неможливо безпечно зіставити з надісланим записом.
Зберігайте відповіді на кшталт «вже зареєстровано» або інші відповіді, пов’язані з дублікатами, окремо, доки не зрозумієте їхнє задокументоване значення. Вони можуть означати, що бажаний стан уже існує, але їх не слід автоматично трактувати як підтвердження успішного володіння, налаштування або підписки.
Після обробки відповіді кожен вхідний запис повинен мати рівно один локальний результат. Корисна перевірка узгодження: надіслані записи дорівнюють прийнятим записам плюс постійні помилки плюс помилки, придатні для повторної спроби, плюс невідомі результати. Це правило локального обліку, а не обов’язковий формат відповіді API.
Обробляйте часткові помилки, не повторюючи успішні записи
Припустімо, що ілюстративний пакет містить десять відправлень: сім прийнято, два мають недійсні обов’язкові поля, а для одного виникла задокументована тимчасова помилка. Збережіть сім успішних результатів, передайте два недійсні записи на виправлення та повторно надішліть лише запис із тимчасовою помилкою.
Повторне надсилання всіх десяти записів створює зайвий трафік і може ускладнити обробку дублікатів. Воно також ускладнює розрізнення початкового відхилення та подальшої відповіді, пов’язаної з дублікатом.
| Результат | Рекомендована дія |
|---|---|
| Недійсне поле або непідтримуване значення | Виправити вхідні дані; не повторювати без змін |
| Помилка автентифікації або дозволів | Призупинити відповідну роботу та виправити облікові дані або доступ |
| Відповідь про обмеження швидкості | Зробити паузу відповідно до задокументованих рекомендацій і відповідних заголовків |
| Тимчасова помилка на рівні елемента | Повторити для цього елемента з обмеженою кількістю спроб і затримкою |
| Тайм-аут після надсилання | Позначити як невизначений; узгодити результат або використати задокументовані гарантії безпеки повторної спроби |
| Нерозпізнаний або неповний результат | Зберегти докази та провести розслідування, а не припускати успіх |
HTTP 429 означає надмірну кількість запитів, і відповідь може містити заголовок Retry-After, як описано в RFC 6585. Не припускайте, що цей заголовок присутній завжди. Якщо явну затримку повторної спроби не вказано, використовуйте обмежену політику відкладеного повтору, узгоджену з документацією API.
Додавайте випадкову затримку, щоб розподілити повторні спроби між кількома працівниками, установіть максимальну кількість спроб або максимальний вік повтору та надсилайте записи, для яких вичерпано спроби, до черги перевірки. Нескінченні повторні спроби можуть приховати постійну проблему конфігурації.
Чому тайм-аути потребують особливого підходу
Тайм-аут не доводить відхилення. Сервер міг прийняти пакет до розриву з’єднання. Тому автоматичне повторне надсилання запиту, що змінює стан, може призвести до повторного виконання роботи.
Якщо кінцева точка підтримує задокументовані ключі ідемпотентності, дотримуйтеся її правил, зокрема області дії та терміну зберігання ключа. Не вигадуйте заголовок ідемпотентності й не припускайте, що сервер його враховує. В іншому разі використовуйте підтримуваний робочий процес пошуку або узгодження, щоб визначити, чи існує бажаний стан, перш ніж надсилати запит повторно. Локальна дедуплікація допомагає координувати власних працівників, але не гарантує ідемпотентність на стороні сервера.
Практичний робочий процес пакетної обробки
Зберігайте деталі, специфічні для постачальника, в адаптері, щоб черга, планувальник повторних спроб і логіка моніторингу не залежали від необроблених назв полів відповіді.
перевірити записи та зберегти локальні ідентифікатори відправлень
визначити дублікати в межах потрібної бізнес-області
розділити записи відповідно до задокументованих обмежень елементів і корисного навантаження
для кожного пакета через обмежений пул працівників:
зберегти запис про спробу перед надсиланням
дочекатися спільного обмежувача швидкості
надіслати через адаптер, специфічний для постачальника
якщо результат невизначений:
поставити узгодження в чергу
продовжити
класифікувати результати на рівні запиту та елемента
зберегти один результат для кожного надісланого запису
запланувати повторну спробу лише для придатних помилок
передати недійсні записи або записи з вичерпаними спробами на перевірку
Зробіть збереження результатів і планування повторних спроб відновлюваними. Наприклад, довговічний запис завдання або транзакційний шаблон постановки в чергу може запобігти втраті рішення про повторну спробу через збій процесу. Після перезапуску працівники повинні розрізняти ненадіслану роботу та роботу, віддалений результат якої досі невизначений.
Використовуйте розмір пакета як параметр конфігурації, пов’язаний із відповідною кінцевою точкою, а не як константу, розкидану по всій кодовій базі. Менший пакет може бути корисним під час усунення несправностей або ізоляції проблемних записів; найбільший дозволений пакет не обов’язково є найкращим робочим розміром.
Відстежуйте результати відправлень, а не лише доступність HTTP
Моніторинг API має показувати, чи досягають відправлення потрібного стану. Панель, яка відображає лише показники успішності HTTP, може пропустити часткові помилки всередині відповідей, що загалом є успішними.
- Рівень прийняття елементів: Прийняті записи, поділені на надіслані записи, із чітко визначеним обліком повторних спроб.
- Розподіл помилок: Кількість за кінцевою точкою, задокументованим кодом помилки та відповідним контекстом перевізника.
- Невідомі результати: Неузгоджені записи та тривалість їхнього перебування без вирішення.
- Черга повторних спроб: Очікувані повтори, вік найстарішої повторної спроби та вичерпані спроби.
- Стан запитів: Затримка, тайм-аути, обмеження швидкості та помилки сервера.
- Актуальність відстеження: Чи отримують прийняті відправлення надалі придатну для використання інформацію про відстеження.
Прийняття реєстрації не є доказом нового сканування перевізником. Відокремлюйте статус обробки API від переміщення відправлення та актуальності даних, щоб інцидент інтеграції не плутали із затримкою доставки.
Записуйте локальні ідентифікатори пакетів, посилання на відправлення, кількість спроб, задокументовані коди помилок та ідентифікатори запитів постачальника, якщо вони доступні. Маскуйте облікові дані та непотрібну персональну інформацію. Використовуйте ідентифікатори відстеження лише там, де це операційно необхідно, і не розміщуйте необроблені ідентифікатори відправлень у мітках метрик із високою кардинальністю.
Перевірте ці випадки до запуску в продуктивному середовищі
За можливості використовуйте задокументоване пісочне середовище або контрольоване тестове середовище. Не припускайте, що вигадані номери відстеження спричинятимуть передбачувані відповіді у продуктивному середовищі.
- Надішліть дійсний пакет із задокументованою максимальною кількістю елементів, а потім перевірте, як клієнт запобігає надмірному розміру пакета.
- Переконайтеся, що номери відстеження з початковими нулями зберігаються під час серіалізації та зберігання.
- Перевірте змішані прийняті та відхилені елементи, не повторюючи успішні записи.
- Імітуйте обмеження швидкості та підтвердьте, що кілька працівників дотримуються одного ліміту.
- Імітуйте тайм-аут після надсилання та перевірте шлях узгодження.
- Перезапустіть працівника між отриманням відповіді та локальним збереженням.
- Перевірте відсутні, незнайомі або такі, що не піддаються зіставленню, результати елементів.
- Переконайтеся, що недійсні записи потрапляють до видимої черги виправлення, а не повторюються нескінченно.
Інтеграція, готова до продуктивної експлуатації, може пояснити стан кожного надісланого відправлення, зокрема тих, результат яких тимчасово невідомий. Зменшення кількості запитів корисне, але збереження цієї підзвітності є важливішою метою проєктування.
Поширені запитання
Скільки номерів відстеження можна надіслати в одному запиті?
Використовуйте ліміт, задокументований для конкретної кінцевої точки та версії API. Також перевірте розмір запиту, обмеження швидкості та будь-які обмеження, пов’язані з обліковим записом. Не існує безпечного універсального числа, яке можна застосувати до всіх API відстеження або різних операцій в одному API.
Чи може один недійсний номер відстеження спричинити помилку всього пакета?
Так, залежно від правил перевірки кінцевої точки. Деякі API повертають окремі відхилення, тоді як інші можуть відхилити запит до обробки елементів. Перевіряйте як помилки на рівні запиту, так і результати на рівні елементів; не припускайте, що кожна кінцева точка пакетної обробки підтримує часткове прийняття.
Чи слід повторювати пакет, якщо HTTP-відповідь успішна?
Не автоматично. Спочатку проаналізуйте задокументований статус рівня застосунку та результати елементів. Збережіть успішні записи й повторіть лише придатні помилки. Якщо результат неможливо безпечно інтерпретувати, класифікуйте його як невизначений і дослідіть.
Чи можна змішувати перевізників в одному пакеті?
Лише якщо кінцева точка підтримує таку структуру запиту. Підтвердьте, чи надається інформація про перевізника для кожного відправлення, чи підтримується автоматична ідентифікація та що відбувається в разі неоднозначної ідентифікації. Сам факт підтримки кількох перевізників сервісом не визначає правила пакетної обробки кожної кінцевої точки.
Чи пришвидшує пакетна обробка надходження оновлень відстеження?
Пакетна обробка може зменшити кількість запитів, які надсилає ваш застосунок, але сама по собі не пришвидшує появу подій від перевізника. Реєстрація, отримання даних, доступність сканування перевізника та доставка оновлень є окремими частинами робочого процесу.
Джерела
- 17TRACK Tracking API — офіційна сторінка продукту для розробників, які оцінюють інтеграцію відстеження.
- Документація 17TRACK API — довідкова інформація щодо специфічного для постачальника контракту кінцевих точок, обмежень, автентифікації та обробки відповідей.
- RFC 9110: Семантика HTTP — семантика статусів HTTP, ідемпотентність, автоматичні повторні спроби та Retry-After.
- RFC 6585: Додаткові коди статусу HTTP — визначення HTTP 429 Too Many Requests і необов’язкового заголовка Retry-After.


