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 Tracking — официална точка за проследяване на превозвача и указания за клиентите.
  • UPS Tracking — официална точка за проследяване на превозвача.