Skip to main content
ДомаБлогВодичиКако да ги проверите броевите за следење пред поднесување преку API: 7 правила што треба да ги следите

Како да ги проверите броевите за следење пред поднесување преку API: 7 правила што треба да ги следите

17TRACK

Потврдете го бројот за следење во неколку слоеви пред да го испратите до API за следење: нормализирајте го внесот, проверете ја неговата основна структура, потврдете го контекстот на превозникот, применете контролна сума само кога превозникот има документирано таква, и отфрлете ги вредностите што се очигледно небезбедни или нецелосни. Не потпирајте се на еден универзален регуларен израз. Форматите на броевите за следење се разликуваат според превозникот, услугата, земјата и видот на пратката, па затоа ефективниот валидатор треба да спречи неисправни барања без да блокира легитимни броеви што користат непознат формат.

Како да ги потврдите броевите за следење пред испраќање преку API: 7 правила

Овој водич е наменет за програмери и оперативни тимови кои интегрираат следење на пратки во систем за управување со нарачки, магацински тек, кориснички портал или апликација за е-трговија. Целта не е да се докаже дека пратката постои пред испраќањето. Синтаксичката валидација и валидацијата на статусот на пратката се одделни чекори.

Што може, а што не може да потврди валидацијата

Валидаторот пред испраќање може да ги идентификува вообичаените проблеми со внесот, како празна вредност, случајни празни места, неподдржани знаци, прекумерна должина или број за следење внесен во погрешно поле. Исто така може да идентификува веројатен превозник кога превозникот е познат и форматот е документиран.

Обично не може да потврди дека бројот припаѓа на вистинска пратка, дека превозникот ја прифатил пратката или дека бројот моментално може да се следи. За овие прашања е потребно пребарување кај превозникот или платформата за следење. Бројот може да помине проверка на форматот, а сепак да биде неискористен, суптилно погрешно внесен, истечен или поврзан со друга услуга.

Седумте правила

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 — официјална страница за следење на превозникот.