Skip to main content
ГоловнаБлогПосібникиЯк перевірити номери відстеження перед надсиланням через API: 7 правил, яких слід дотримуватися

Як перевірити номери відстеження перед надсиланням через API: 7 правил, яких слід дотримуватися

17TRACK

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

7 правил перевірки номерів відстеження перед надсиланням до API

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

Що може і чого не може підтвердити перевірка

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

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

Сім правил

1. Нормалізуйте значення, не змінюючи його зміст

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

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

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

2. Відхиляйте значення, які не проходять базові структурні перевірки

Перш ніж застосовувати логіку конкретного перевізника, перевірте, чи є значення наявним і правдоподібним. Корисні перевірки включають мінімальну та максимальну довжину, дозволені класи символів, а також перевірку, чи містить значення лише пробіли або заповнювач на кшталт «N/A», «TBD» чи «test». Точні обмеження мають випливати з контракту API або документації перевізника. Не вигадуйте універсальну максимальну довжину лише тому, що більшість прикладів короткі.

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

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

3. Використовуйте контекст перевізника замість припущень лише за номером

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

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

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

4. Застосовуйте контрольні суми лише тоді, коли правило задокументоване

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

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

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

5. Відокремлюйте перевірку формату від придатності для API

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

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

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

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

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

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

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

7. Підтверджуйте результат після надсилання та відстежуйте хибні спрацьовування

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

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

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

Практична послідовність перевірки

Підтримувана реалізація може використовувати таку послідовність:

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

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

Контрольний список реалізації

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

Часті запитання

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

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

Чи слід надсилати до API номер, який виглядає недійсним?

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

Чи достатньо контрольної суми для підтвердження відправлення?

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

Що робити, якщо перевізник невідомий?

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

Як обробляти помилки API?

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

Джерела

  • Документація 17TRACK API — рекомендації щодо запитів та інтеграції для розробників API відстеження.
  • 17TRACK Tracking API — офіційна інформація про продукт і варіанти використання API.
  • Відстеження USPS — офіційна сторінка відстеження перевізника та рекомендації для клієнтів.
  • Відстеження UPS — офіційна сторінка відстеження перевізника.