6 verificări pentru a confirma că cele mai recente evenimente de urmărire ale transportatorului au fost sincronizate prin API-ul dvs.
Pentru a verifica dacă API-ul dvs. a sincronizat cele mai recente evenimente de urmărire ale transportatorului, verificați identitatea expedierii, marcajele temporale ale evenimentelor, detaliile evenimentelor, traseul livrării, ordinea evenimentelor și actualitatea acestora în raport cu o vizualizare independentă a urmăririi. Un răspuns API reușit sau o confirmare webhook confirmă doar o parte a acestui lanț; de unul singur, nu dovedește că aplicația dvs. conține cel mai nou eveniment al transportatorului.

Acest ghid este destinat dezvoltatorilor și echipelor operaționale responsabile de introducerea datelor de urmărire într-un sistem de gestionare a comenzilor, într-o pagină destinată clienților, într-un instrument de asistență sau într-un flux de alertare. Scopul este să identificați locul în care un eveniment a lipsit sau s-a modificat, apoi să decideți dacă trebuie să reîncercați procesarea, să corectați o mapare sau să așteptați informații noi de la transportator.
Înainte de a începe: definiți ce înseamnă „cel mai recent”
Păstrați separate trei momente: când transportatorul afirmă că a avut loc un eveniment, când furnizorul dvs. de urmărire l-a primit sau l-a făcut disponibil și când aplicația dvs. l-a stocat. Aceste momente pot fi diferite. Un transportator poate publica o scanare după evenimentul fizic, iar integrarea dvs. o poate procesa și mai târziu. Prin urmare, cel mai nou eveniment după momentul producerii nu este neapărat înregistrarea primită cel mai recent.
Alegeți un punct de comparație înainte de investigație. Ideal, utilizați pagina de urmărire a transportatorului sau o altă înregistrare autorizată furnizată de transportator pentru aceeași expediere. Dacă aceasta nu este disponibilă, comparați aplicația cu răspunsul API actual al furnizorului de urmărire. Această comparație mai restrânsă poate stabili dacă aplicația dvs. corespunde furnizorului; nu poate stabili dacă furnizorul deține deja fiecare scanare a transportatorului. Notați momentul în care ați făcut comparația, astfel încât o actualizare ulterioară să nu facă un rezultat anterior să pară inconsistent.
1. Confirmați că ambele sisteme se referă la aceeași expediere
Începeți cu numărul de urmărire, transportatorul și orice identificator de cont sau de expediere utilizat de integrarea dvs. Numerele de urmărire pot fi insuficiente pentru depanare: un număr poate fi introdus cu o greșeală, asociat transportatorului greșit sau reutilizat într-o înregistrare internă după editarea unei comenzi. Numărul comenzii și numărul de urmărire au, de asemenea, scopuri diferite. O comandă poate avea mai multe colete, astfel încât verificarea celui mai recent status al comenzii poate ascunde un colet învechit.
- Găsiți numărul exact de urmărire și transportatorul transmise către API-ul de urmărire.
- Confirmați ce înregistrare internă a expedierii sau a coletului a primit răspunsul.
- Verificați dacă expedierea a fost înlocuită, împărțită, anulată sau reasociată după înregistrare.
- Comparați transportatorul și numărul afișate în înregistrarea sursă cu cele afișate în aplicația dvs.
Dacă identificatorii nu corespund, nu mai tratați diferența ca pe o întârziere de sincronizare. Corectați mai întâi asocierea, apoi repetați comparația evenimentelor. Stocați suficiente identificatoare în jurnalele de diagnostic pentru a urmări o expediere fără a introduce în aceste jurnale date sensibile de autentificare ale contului.
2. Comparați momentele evenimentelor fără a le pierde semnificația
Pentru fiecare candidat la cel mai recent eveniment, capturați momentul producerii raportat de transportator, fusul orar sau decalajul indicat, dacă este furnizat, precum și momentele primirii și stocării în aplicația dvs. Convertiți marcajele temporale la o bază temporală comună pentru comparație, dar păstrați valoarea originală. RFC 3339 definește un format de marcaj temporal pentru internet, cu informații explicite despre decalaj; este o referință utilă atunci când vă proiectați propriile câmpuri de timp. Totuși, nu garantează că un transportator sau un furnizor oferă un fus orar pentru fiecare eveniment.
O afișare care conține doar ora, un fus local presupus sau un analizator care elimină în tăcere decalajul poate muta un eveniment într-o altă zi calendaristică sau îl poate plasa într-o ordine greșită. Când sursa oferă o oră locală ambiguă, marcați comparația ca incertă în loc să inventați un moment UTC precis. De asemenea, distingeți momentul producerii evenimentului de momentul răspunsului API: un răspuns preluat acum poate conține în mod legitim un eveniment care s-a produs mai devreme.
Notați ora la care ați verificat vizualizarea transportatorului sau a furnizorului. Dacă sursa a publicat o scanare nouă după solicitarea API, o diferență între cele două vizualizări nu demonstrează că solicitarea anterioară a eșuat.
3. Verificați conținutul evenimentului, nu doar statusul principal
Comparați descrierea celui mai recent eveniment, locația, statusul sau codul transportatorului și orice câmp relevant de livrare cu înregistrarea din amonte. Un status normalizat precum „în tranzit” poate rezuma mai multe scanări distincte. Dacă aplicația dvs. stochează doar rezumatul, acesta poate părea neschimbat chiar dacă a sosit un eveniment nou.
Inspectați răspunsul API brut sau corpul webhook păstrat, acolo unde regulile dvs. de gestionare a datelor permit acest lucru. Apoi urmăriți evenimentul prin analizare, maparea câmpurilor, persistență și prezentare. Căutați câmpuri null suprascrise cu valori implicite, coduri de status neașteptate încadrate într-o categorie generică, texte trunchiate sau o interfață de utilizator care afișează doar anumite tipuri de evenimente. O discrepanță a etichetei de status diferă de un eveniment lipsă: aceasta indică logica de transformare sau de afișare, nu livrarea.
Nu deduceți livrarea doar pentru că o locație sau un status pare final. Confirmați evenimentul specific și câmpurile pe care se bazează fluxul dvs. Invers, un status general neschimbat nu dovedește că sincronizarea s-a oprit; o scanare nou primită poate fi mapată la aceeași categorie. Înregistrarea dvs. de diagnostic trebuie să păstreze atât evenimentul din amonte, cât și valoarea afișată utilizatorilor.
4. Urmăriți modul în care evenimentul a ajuns în aplicația dvs.
Dacă utilizați webhook-uri, verificați jurnalul de primire pentru expedierea și evenimentul relevante. Verificați dacă endpointul dvs. a acceptat solicitarea, dacă mesajul a trecut validarea și dacă procesarea ulterioară s-a finalizat. Un răspuns HTTP de succes de la endpointul dvs. nu dovedește că un worker ulterior al cozii a salvat evenimentul. Dacă procesarea este asincronă, examinați atât solicitarea de intrare, cât și rezultatul jobului.
Dacă interogați un API, verificați ultima solicitare finalizată, identificatorul expedierii din acea solicitare, răspunsul acesteia și orice logică de paginare sau de preluare utilizată de integrarea dvs. O solicitare reușită poate fi urmată de o scriere eșuată în baza de date sau de citirea unei memorii cache învechite. Utilizați documentația aplicabilă a furnizorului pentru a verifica efectiv câmpurile răspunsului, cerințele de autentificare și comportamentul de livrare pentru integrarea dvs., în loc să presupuneți că toate API-urile de urmărire respectă același contract. Pentru o integrare 17TRACK, punctele de pornire relevante sunt pagina Tracking API și documentația API; confirmați comportamentul documentat pentru endpointul și metoda pe care le utilizați.
Faceți procesarea evenimentelor sigură pentru repetare. O reîncercare nu ar trebui să creeze scanări duplicate, să trimită în mod repetat aceeași notificare clientului sau să înlocuiască o stare stocată mai nouă cu un payload mai vechi. Cheia duplicatelor potrivită depinde de câmpurile furnizate efectiv de furnizor. Testați cheia aleasă cu evenimente distincte care se întâmplă să aibă același status sau marcaj temporal; aceste evenimente nu ar trebui comasate doar pentru că par similare.
5. Verificați regulile de ordonare și de tranziție a stărilor
Sortați evenimentele înregistrate după o regulă clar definită, apoi inspectați rezultatul. Multe aplicații trebuie să distingă între „cel mai recent eveniment produs” și „cel mai recent eveniment primit de noi”. O scanare anterioară întârziată poate sosi după o scanare mai nouă. Dacă baza de date face pur și simplu din mesajul procesat cel mai recent starea curentă a expedierii, scanarea întârziată poate readuce statusul afișat la o stare anterioară.
Comparați istoricul stocat cu istoricul din amonte, nu doar un singur câmp de status. Întrebați dacă o înregistrare nou primită a fost adăugată, eliminată ca duplicat sau autorizată să actualizeze starea curentă. Verificați orice regulă care acordă prioritate anumitor evenimente față de altele. O astfel de regulă poate fi intenționată, dar nu ar trebui să ascundă evenimentul de bază sau să sugereze că transportatorul a inversat un jalon atunci când aplicația a primit pur și simplu târziu o scanare mai veche.
Pentru un test practic, luați o expediere cu mai mult de un eveniment și redați mesajele într-o ordine diferită de sosire într-un mediu care nu este de producție. Confirmați că istoricul evenimentelor rămâne intact și că statusul destinat clienților urmează regula documentată. Acest lucru evidențiază defectele de ordonare pe care un test normal, cu succesiune corectă, nu le poate dezvălui.
6. Măsurați actualitatea și reconciliați excepțiile
În cele din urmă, comparați ce știa fiecare nivel în același moment de observare: vizualizarea transportatorului, răspunsul furnizorului de urmărire, webhook-ul de intrare sau rezultatul interogării, înregistrarea din baza de date și rezultatul afișat clientului. Marcați primul nivel la care evenimentul așteptat dispare. Această limită este mai utilă decât un raport general conform căruia „urmărirea este întârziată”.
Măsurați atât vechimea celui mai recent eveniment raportat de transportator, cât și timpul scurs de când integrarea dvs. a verificat sau a primit ultima dată date cu succes. Acestea răspund unor întrebări diferite. Un colet poate să nu aibă nicio scanare nouă a transportatorului chiar dacă integrarea dvs. funcționează corect; alternativ, transportatorul poate afișa o scanare nouă în timp ce ultima dvs. solicitare reușită este veche. Utilizați praguri de alertare care reflectă propriile cerințe operaționale și comportamentul observat. Nu promiteți clienților un interval fix de actualizare dacă acordurile dvs. cu transportatorul și furnizorul nu îl susțin.
Creați o coadă mică de reconciliere pentru expedierile ale căror înregistrări diferă de sursa de comparație aleasă. Includeți identificatorii, evenimentul lipsă sau nepotrivit, marcajele temporale relevante, primul nivel care a eșuat și următoarea acțiune. De exemplu, un eveniment prezent în răspunsul furnizorului, dar absent din baza dvs. de date, necesită o investigație a integrării. Un eveniment prezent în baza dvs. de date, dar absent de pe pagina de urmărire, necesită verificarea afișării sau a cache-ului. Dacă transportatorul însuși nu afișează nicio scanare nouă, o altă solicitare API nu poate crea una.
Testul operațional este simplu: puteți identifica aceeași expediere, localiza cel mai recent eveniment cunoscut din amonte și urmări acel eveniment până la vizualizarea destinată utilizatorului fără a-i schimba semnificația? Dacă nu, cele șase verificări restrâng problema la o limită specifică și oferă echipei dvs. următorul pas justificat.
Întrebări frecvente
Un răspuns webhook reușit înseamnă că cel mai recent eveniment este sincronizat?
Nu. Acesta arată că endpointul dvs. a returnat un răspuns reușit la o solicitare. Confirmați că validarea, procesarea cozii, stocarea în baza de date și afișarea au reușit, de asemenea. Verificați payload-ul pentru a stabili ce eveniment conținea solicitarea.
De ce pagina transportatorului afișează o scanare mai nouă decât răspunsul meu API?
Mai întâi confirmați că vizualizați același colet și că ambele observații au fost făcute la momente comparabile. Publicarea de către transportator și primirea sau expunerea unui eveniment de către furnizorul de urmărire pot avea loc la momente diferite. Dacă diferența persistă, utilizați documentația și procesul de asistență al furnizorului pentru a investiga expedierea specifică, în loc să presupuneți existența unei garanții de actualizare.
Ar trebui să folosesc marcajul temporal al evenimentului sau momentul la care sistemul meu l-a primit pentru a alege cel mai recent status?
Utilizați o regulă documentată, potrivită fluxului dvs., și păstrați ambele valori. Marcajul temporal al evenimentului descrie momentul în care a avut loc activitatea raportată; momentul primirii descrie când sistemul dvs. a aflat despre aceasta. Niciunul dintre câmpuri nu rezolvă singur toate cazurile, în special atunci când momentele sursă sunt ambigue sau scanările anterioare sosesc cu întârziere.
Ce se întâmplă dacă statusul API nu s-a schimbat, dar lista evenimentelor are o intrare nouă?
Acest lucru poate fi normal dacă mai multe evenimente ale transportatorului sunt mapate la un singur status normalizat. Comparați detaliile evenimentelor și verificați dacă aplicația dvs. a stocat și afișează noua intrare acolo unde este cazul. Tratați un eveniment lipsă și o etichetă de rezumat neschimbată ca probleme diferite.
Surse
- 17TRACK Tracking API — referință de produs pentru integrările cu API-ul de urmărire.
- Documentația API 17TRACK — punct de referință pentru verificarea contractului de integrare aplicabil.
- RFC 3339: Data și ora pe internet: marcaje temporale — referință pentru formatul marcajelor temporale și al decalajului UTC.


