Skip to main content
AcasăBlogGhiduriCum să validezi numerele de urmărire înainte de trimiterea către API: 7 reguli de urmat

Cum să validezi numerele de urmărire înainte de trimiterea către API: 7 reguli de urmat

17TRACK

Validați un număr de urmărire în mai multe etape înainte de a-l trimite către un API de urmărire: normalizați datele introduse, verificați structura de bază, confirmați contextul transportatorului, aplicați o sumă de control numai atunci când transportatorul o documentează și respingeți valorile care sunt în mod clar nesigure sau incomplete. Nu vă bazați pe o singură expresie regulată universală. Formatele numerelor de urmărire diferă în funcție de transportator, serviciu, țară și tipul expedierii, astfel încât un validator eficient ar trebui să prevină solicitările incorecte fără să blocheze numere legitime care folosesc un format necunoscut.

7 reguli pentru validarea numerelor de urmărire înainte de trimiterea către API

Acest ghid este destinat dezvoltatorilor și echipelor operaționale care integrează urmărirea expedierilor într-un sistem de gestionare a comenzilor, într-un flux de lucru al depozitului, într-un portal pentru clienți sau într-o aplicație de comerț electronic. Scopul nu este de a demonstra că un colet există înainte de trimitere. Validarea sintactică și validarea stării expedierii sunt pași separați.

Ce poate confirma și ce nu poate confirma validarea

Un validator înainte de trimitere poate identifica probleme frecvente ale datelor introduse, precum o valoare goală, spații adăugate accidental, caractere neacceptate, o lungime excesivă sau un număr de urmărire introdus în câmpul greșit. De asemenea, poate identifica un transportator probabil atunci când acesta este cunoscut și formatul este documentat.

În mod normal, nu poate confirma că un număr aparține unei expedieri reale, că pachetul a fost acceptat de un transportator sau că numărul poate fi urmărit în prezent. Pentru aceste întrebări este necesară o interogare către transportator sau platforma de urmărire. Un număr poate trece verificarea formatului și totuși să nu fie utilizat, să conțină o eroare subtilă de introducere, să fie expirat sau să fie asociat unui alt serviciu.

Cele șapte reguli

1. Normalizați valoarea fără a-i modifica sensul

Utilizatorii și sistemele din amonte adaugă adesea spații la început sau la sfârșit, întreruperi de linie, spații care nu permit întreruperea liniei sau caractere de formatare. Normalizați-le în siguranță înainte de validare. Un prim pas obișnuit este eliminarea spațiilor albe din jur și convertirea spațiilor care nu se afișează în spații obișnuite. Dacă formatul documentat al transportatorului permite spații interne sau cratime, decideți dacă le eliminați pentru solicitarea API sau păstrați valoarea originală pentru afișare și audit.

Păstrați două valori atunci când este practic: datele introduse inițial și o valoare canonică. Valoarea originală ajută echipele de asistență să investigheze problemele de calitate a datelor; valoarea canonică este utilizată pentru validare și trimitere. Evitați transformările care pot modifica identificatorii. Nu convertiți automat literele în cifre, nu înlocuiți caracterele ambigue și nu eliminați toate semnele de punctuație decât dacă documentația transportatorului sau a API-ului relevant acceptă explicit acest comportament.

Gestionarea Unicode necesită atenție. Un caracter vizual similar dintr-un alt alfabet poate să nu fie acceptat de un API, chiar dacă arată ca o literă sau o cifră ASCII. Restricționarea valorii canonice la setul de caractere permis de integrarea selectată poate preveni erori derutante în etapele ulterioare.

2. Respingeți valorile care nu trec verificările structurale de bază

Înainte de a aplica logica specifică transportatorului, verificați dacă valoarea există și este plauzibilă. Verificările utile includ lungimea minimă și maximă, clasele de caractere permise și dacă valoarea conține numai spații albe sau un substituent precum „N/A”, „TBD” ori „test”. Limitele exacte ar trebui să provină din contractul API sau din documentația transportatorului. Evitați să inventați o limită maximă universală doar pentru că majoritatea exemplelor sunt scurte.

O verificare structurală ar trebui să fie în mod deliberat conservatoare. De exemplu, o regulă care permite numai cifre va respinge identificatorii alfanumerici valizi. O regulă care impune o lungime fixă poate respinge variante de servicii sau formate internaționale. Folosiți verificări generice pentru a detecta erorile evidente, apoi aplicați verificări mai specifice numai atunci când transportatorul și serviciul sunt cunoscute.

Validați și tipul de date la limita aplicației. Un număr de urmărire ar trebui tratat de regulă ca șir de caractere, nu ca număr întreg. Conversia numerică poate elimina zerourile de la început și poate crea probleme de precizie în sistemele care folosesc tipuri numerice cu lățime fixă. Păstrați valoarea exact ca șir după normalizarea aprobată.

3. Folosiți contextul transportatorului în loc să ghiciți doar pe baza numărului

Un număr de urmărire fără transportator este o valoare ambiguă. Transportatori diferiți pot utiliza lungimi, prefixe sau seturi de caractere comune, iar un format care pare plauzibil pentru un transportator poate fi invalid pentru altul. Dacă comanda, eticheta, sistemul depozitului sau contul comerciantului identifică deja transportatorul, transmiteți acest context împreună cu numărul de urmărire ori de câte ori API-ul permite.

Contextul transportatorului îmbunătățește atât validarea, cât și rutarea. El permite aplicației să selecteze regulile de format relevante, reduce potrivirile false și face mesajele de eroare mai utile. De asemenea, împiedică tratarea rezultatului detectării automate ca fapt atunci când mai mulți transportatori ar putea accepta o valoare cu aspect similar.

Dacă transportatorul este necunoscut, utilizați o abordare în două etape. Mai întâi, efectuați verificări generice de siguranță. Apoi, trimiteți valoarea numai printr-un flux API care acceptă explicit detectarea transportatorului sau plasați-o într-o coadă de verificare atunci când procesul de afaceri necesită un transportator confirmat. Nu atribuiți în mod silențios un transportator doar pe baza unui prefix decât dacă maparea respectivă este întreținută și documentată.

4. Aplicați sume de control numai atunci când regula este documentată

Unele sisteme de identificatori folosesc cifre de control, însă numerele de urmărire nu sunt guvernate de un singur standard universal pentru sume de control. O sumă de control poate detecta anumite erori de transcriere, dar nu demonstrează că o expediere există. Mai important, aplicarea unui algoritm de sumă de control greșit poate respinge numere valide.

Implementați o sumă de control numai atunci când transportatorul, serviciul, specificația etichetei sau documentația API relevantă definește algoritmul și partea de intrare acoperită de acesta. Înregistrați versiunea regulii și testați-o pe baza exemplelor oficiale. Dacă nu există o regulă autorizată, omiteți suma de control în loc să ghiciți pe baza tiparelor observate într-un eșantion restrâns.

Tratați rezultatul sumei de control ca pe un singur indicator, nu ca pe o decizie completă de validare. O verificare eșuată poate justifica blocarea unei trimiteri atunci când regula este autorizată. O verificare trecută ar trebui să deplaseze valoarea la etapa următoare, nu să o marcheze ca expediere activă.

5. Separați validarea formatului de eligibilitatea pentru API

O valoare poate fi bine formatată și totuși nepotrivită pentru punctul final pe care îl apelați. Înainte de trimitere, verificați în documentația API câmpurile obligatorii, identificatorii de transportatori acceptați, cerințele de autentificare, limitele solicitărilor, comportamentul pentru duplicate și eventualele restricții privind tipurile de servicii sau destinațiile. Acestea sunt reguli de integrare, nu reguli pentru numerele de urmărire, dar determină dacă un identificator valid poate fi procesat cu succes.

Documentația API de urmărire 17TRACK este un exemplu al motivului pentru care această distincție contează: dezvoltatorii trebuie să urmeze modelul de solicitare al platformei și comportamentul de integrare acceptat, în loc să inventeze o solicitare pe baza aspectului unui număr de urmărire. Consultați documentația actuală pentru cerințele punctului final și gestionarea răspunsurilor la documentația API 17TRACK.

Păstrați erorile de validare separate de erorile de transport și autentificare. „Format invalid al numărului de urmărire”, „transportator necunoscut”, „limita de frecvență a fost atinsă” și „autorizare eșuată” necesită acțiuni diferite. Un singur mesaj generic de tipul „trimiterea a eșuat” face reîncercările și raportarea operațională mai puțin fiabile.

6. Protejați API-ul prin limite pentru datele introduse, eliminarea duplicatelor și reîncercări sigure

Validarea este și o măsură de protecție operațională. Impuneți o lungime limitată a datelor introduse înainte de analizare sau înregistrare. Respingeți caracterele de control și structurile de date neașteptate. Aplicați limite de frecvență la limita propriei aplicații, astfel încât un import defect să nu genereze o rafală necontrolată de solicitări.

Eliminați duplicatele înainte de trimitere atunci când procesul de afaceri nu necesită înregistrări repetate. O cheie utilă pentru eliminarea duplicatelor poate include numărul canonic de urmărire, transportatorul, contul și contextul expedierii. Cheia corectă depinde de fluxul de lucru; același identificator poate fi uneori reutilizat pentru servicii sau înregistrări de afaceri diferite, așadar nu presupuneți că numărul este întotdeauna unic la nivel global.

Folosiți reîncercări limitate cu backoff pentru erori temporare și evitați reîncercarea erorilor permanente de validare. Stocați o înregistrare de idempotență sau de trimitere atunci când API-ul și arhitectura dumneavoastră permit acest lucru. Înregistrați suficiente informații pentru depanarea solicitării, dar protejați datele de autentificare, datele clienților și orice detalii sensibile despre expediere. Un validator ar trebui să reducă eșecurile repetate, nu să creeze o a doua problemă de securitate prin înregistrarea excesivă a datelor.

7. Confirmați rezultatul după trimitere și monitorizați rezultatele fals pozitive

Regula finală este să tratați validarea înainte de trimitere ca pe o poartă de acces, nu ca pe un verdict. După acceptarea solicitării, analizați răspunsul API și păstrați starea acestuia, identificatorul solicitării, asocierea transportatorului și orice cod de eroare documentat. Dacă platforma acceptă solicitarea, dar nu poate returna încă evenimente de mișcare, acest lucru poate indica o întârziere de procesare, nu un număr invalid.

Definiți o politică de urmărire pentru numerele care rămân nerezolvate. Intervalul de timp ar trebui să reflecte transportatorul, serviciul, originea expedierii și politica de servicii pentru clienți; nu există o perioadă universală care să demonstreze că un număr este invalid. Escaladați înregistrările cu transportator lipsă, erori repetate ale furnizorului, rezultate contradictorii ale transportatorilor sau o stare care nu corespunde înregistrării comenzii.

Măsurați respingerile false și acceptările false. O expresie regulată strictă poate reduce trimiterile incorecte, blocând însă în mod eronat expedieri legitime. Un validator permisiv poate crește numărul solicitărilor acceptate, dar poate crea zgomot în etapele ulterioare. Analizați eșantioanele eșuate după transportator și serviciu, actualizați regulile documentate prin controlul versiunilor și testați modificările pe un set reprezentativ de date de test care protejează confidențialitatea.

O secvență practică de validare

O implementare ușor de întreținut poate utiliza următoarea secvență:

  1. Verificați dacă solicitarea conține o valoare de tip șir și o înregistrare de afaceri validă.
  2. Salvați datele introduse inițial, apoi creați o formă canonică documentată.
  3. Respingeți valorile goale, substituenții, caracterele nesigure și valorile din afara intervalului de lungime documentat.
  4. Identificați transportatorul din date de încredere ale comenzii sau utilizați un flux de detectare acceptat explicit.
  5. Aplicați regulile de sintaxă și de sumă de control specifice transportatorului numai atunci când documentația autorizată le susține.
  6. Verificați cerințele punctului final, starea duplicatului și eligibilitatea pentru reîncercare.
  7. Trimiteți solicitarea, clasificați răspunsul, stocați rezultatul și programați urmărirea înregistrărilor nerezolvate.

Această secvență facilitează testarea validatorului, deoarece fiecare decizie are un motiv diferit. De asemenea, oferă echipelor operaționale categorii de eșec utile, în locul unei singure erori opace.

Listă de verificare pentru implementare

  • Stocați numerele de urmărire ca șiruri de caractere, astfel încât zerourile de la început să fie păstrate.
  • Păstrați separat valorile originale și canonice atunci când trasabilitatea este importantă.
  • Mențineți regulile transportatorilor ca configurație cu versiuni, nu ca condiții codificate în mod hardcodat în locuri diferite.
  • Testați litere, cifre, cratime, spații albe, caractere Unicode asemănătoare vizual, substituenți și lungimi de limită.
  • Folosiți contextul de încredere al transportatorului ori de câte ori este disponibil.
  • Nu deduceți existența unei expedieri dintr-o potrivire reușită a unei expresii regulate.
  • Clasificați separat erorile permanente de validare și erorile temporare ale API-ului sau rețelei.
  • Consultați documentația furnizorului înainte de a modifica regulile de format sau logica solicitărilor.

Întrebări frecvente

Poate o expresie regulată să valideze un număr de urmărire?

Poate valida un tipar limitat atunci când formatul transportatorului și al serviciului este cunoscut. Nu poate demonstra că numărul există, că aparține unei anumite expedieri sau că este activ în prezent. O expresie universală va crea probabil respingeri false sau potriviri false.

Ar trebui trimis către API un număr care pare invalid?

Valorile clar goale, nesigure sau imposibile din punct de vedere structural ar trebui în mod normal oprite înainte de trimitere. Un format necunoscut, dar altfel sigur, nu ar trebui respins doar pentru că nu corespunde unei presupuneri interne. Verificați mai întâi documentația transportatorului sau utilizați un proces de detectare acceptat.

Este suficientă o sumă de control pentru a confirma o expediere?

Nu. O sumă de control, atunci când este aplicabilă, testează doar dacă valoarea respectă o regulă matematică. Nu confirmă că un transportator a emis numărul sau că pachetul a intrat în rețea.

Ce ar trebui să se întâmple atunci când transportatorul este necunoscut?

Rulați verificări generice de siguranță și utilizați un flux API care acceptă explicit detectarea transportatorului, dacă este disponibil. În caz contrar, păstrați înregistrarea pentru îmbogățire sau verificare manuală, în loc să ghiciți în mod silențios transportatorul.

Cum ar trebui gestionate erorile API?

Clasificați-le după cauză. Corectați datele introduse incorect și valorile de transportator neacceptate; reîncercați erorile temporare de rețea sau ale furnizorului cu limite și backoff; direcționați erorile de autentificare sau de cotă către responsabilul integrării. Păstrați detaliile răspunsului necesare pentru diagnosticare fără a expune secrete.

Surse

  • Documentația API 17TRACK — îndrumări privind solicitările și integrarea pentru dezvoltatorii de API-uri de urmărire.
  • API-ul de urmărire 17TRACK — informații oficiale despre produs și cazuri de utilizare ale API-ului.
  • Urmărirea USPS — punct oficial de acces la urmărirea transportatorului și îndrumări pentru clienți.
  • Urmărirea UPS — punct oficial de acces la urmărirea transportatorului.