Skip to main content
AcasăBlogGhiduriCe date ar trebui să returneze un API de urmărire? 12 câmpuri pe lângă starea actuală?

Ce date ar trebui să returneze un API de urmărire? 12 câmpuri pe lângă starea actuală?

17TRACK

Așa cum o API de urmărire ar trebui să returneze mai mult decât o etichetă precum „În tranzit”. Pe lângă starea actuală, căutați identificatori ai expedierii, identitatea transportatorului, informații detaliate despre stare, mesajele originale ale transportatorului, istoricul evenimentelor, marcajele temporale ale evenimentelor, locațiile, estimările de livrare, excepțiile, transferurile între transportatori, detaliile livrării și metadatele privind actualitatea datelor. Împreună, aceste 12 grupuri de date îi ajută pe dezvoltatori să creeze fluxuri de lucru fiabile și oferă echipelor operaționale suficient context pentru a acționa.

Ce date ar trebui să returneze o API de urmărire: 12 câmpuri suplimentare

Acesta este un contract de răspuns recomandat pentru dezvoltatori, cumpărători tehnici și echipele de operațiuni ecommerce — nu o afirmație că fiecare transportator sau API furnizează fiecare câmp. Unele valori vor fi în mod legitim indisponibile. Un design mai bun face aceste lipsuri explicite, în loc să le completeze cu presupuneri.

Ce face utile datele de urmărire?

O stare actuală răspunde unei singure întrebări: care este starea rezumată a expedierii? Aceasta nu explică neapărat ce s-a întâmplat, când s-a întâmplat, dacă informația este recentă sau ce ar trebui să facă cineva în continuare.

De exemplu, două expedieri pot afișa ambele „În tranzit”, deși necesită răspunsuri diferite. Una poate avea o scanare recentă într-un centru și nicio problemă raportată. Cealaltă poate avea o problemă de adresă nerezolvată înregistrată în istoricul evenimentelor. O aplicație care citește doar starea principală poate rata această diferență.

Evaluați răspunsul în raport cu trei sarcini practice: asocierea expedierii cu comanda corectă, explicarea exactă a progresului acesteia și stabilirea dacă este justificată o acțiune. Următoarele câmpuri sprijină aceste sarcini. Denumirile câmpurilor sunt ilustrative; nu reprezintă un standard universal sau schema unui anumit furnizor.

12 câmpuri de evaluat dincolo de starea actuală

1. Identificatorii expedierii și ai urmăririi

Răspunsul ar trebui să identifice expedierea descrisă. Valorile utile includ numărul de urmărire trimis, identificatorul înregistrării de urmărire al API-ului și o referință a clientului pe care sistemul dumneavoastră o poate asocia unei înregistrări de onorare sau de colet.

Nu presupuneți că o comandă este egală cu o expediere. O comandă poate fi împărțită în mai multe colete, iar o înlocuire poate crea o altă expediere. Stocați înregistrările de urmărire la nivel de colet sau de onorare, apoi asociați-le comenzii. Păstrați numerele de urmărire ca șiruri de caractere, astfel încât formatarea și zerourile de la început să nu se piardă.

2. Identitatea transportatorului

Căutați un identificator stabil al transportatorului împreună cu un nume lizibil al acestuia. Atunci când este disponibil, răspunsul ar trebui să distingă un transportator furnizat explicit de aplicația dumneavoastră de unul selectat prin detectare automată.

Contextul transportatorului contează la interpretarea unui număr de urmărire și a evenimentelor sale. Dacă detectarea este ambiguă, integrarea dumneavoastră ar trebui să permită clarificarea acesteia, în loc să prezinte în tăcere o potrivire incertă drept confirmată. Păstrați separat informațiile despre nivelul serviciului: numele transportatorului nu stabilește singur dacă expedierea utilizează un serviciu expres, poștal sau alt tip de serviciu.

3. Detalii normalizate despre stare

Pe lângă starea principală, solicitați un cod de detaliu sau o substare documentată. O categorie generală poate descrie o expediere ca fiind o excepție, în timp ce detaliul identifică o încercare de livrare, o problemă de adresă sau o reținere legată de vamă.

Utilizați coduri stabile pentru logica de business și etichete lizibile pentru prezentare. Confirmați modul în care furnizorul mapează evenimentele transportatorului la aceste coduri, inclusiv modul în care gestionează evenimentele necunoscute sau nemapate. O etichetă normalizată facilitează utilizarea fluxurilor de date de la transportatori diferiți, dar nu ar trebui să elimine distincțiile de care are nevoie echipa de asistență.

4. Mesajele și codurile originale ale transportatorului

Păstrați descrierea originală a evenimentului și codul evenimentului transportatorului atunci când sunt furnizate. Aceste valori oferă agenților de asistență un context care poate lipsi dintr-o stare normalizată, mai ales atunci când un transportator folosește o formulare operațională specifică.

Păstrați textul original separat de descrierile traduse sau rescrise. În caz contrar, o explicație destinată clientului poate fi confundată cu formularea exactă a transportatorului. Tratați textul transportatorului ca date neverificate atunci când îl afișați: faceți escaping în mod corespunzător și nu îl redați ca HTML executabil.

5. Istoricul evenimentelor de urmărire

Un răspuns util ar trebui să expună cronologia expedierii, nu doar cel mai recent eveniment. Fiecare eveniment ar trebui, în mod ideal, să includă un identificator, o stare sau un cod, o descriere, un marcaj temporal și informațiile disponibile despre locație.

Verificați dacă API-ul returnează istoricul complet, o fereastră limitată sau rezultate paginate. Stabiliți, de asemenea, modul în care sunt reprezentate corecțiile și observațiile duplicate. Aplicația dumneavoastră nu ar trebui să presupună că primul element este întotdeauna cel mai nou, cu excepția cazului în care contractul de răspuns garantează explicit această ordonare.

6. Marcajele temporale ale evenimentelor și informațiile despre fusul orar

Momentul producerii unui eveniment este diferit de momentul în care API-ul l-a primit sau l-a returnat. Păstrați-le pe ambele atunci când sunt disponibile. Această distincție ajută la explicarea motivului pentru care o actualizare primită recent poate descrie ceva ce s-a întâmplat mai devreme.

Solicitați marcaje temporale cu decalaje UTC explicite sau cu notație UTC. RFC 3339 definește un format de marcaj temporal potrivit pentru protocoalele Internet, inclusiv decalaje numerice de timp. Dacă o sursă furnizează doar ora locală fără un decalaj cunoscut, păstrați această incertitudine în loc să o tratați în tăcere ca UTC. Nu sugerați niciodată o precizie la nivel de secundă atunci când sursa de bază furnizează doar o dată.

7. Locațiile evenimentelor și geografia expedierii

Căutați componente structurate ale locației, precum orașul, regiunea, țara și codul poștal, atunci când sunt furnizate. Păstrați și un șir de caractere cu locația brută dacă transformarea acesteia în câmpuri structurate ar putea pierde semnificație.

Locația unei scanări nu este neapărat poziția în timp real a coletului. În mod similar, ultimul centru raportat nu dovedește că pachetul se află încă acolo. Paginile destinate clienților ar trebui să o descrie ca fiind cea mai recentă locație raportată. Evitați deducerea coordonatelor sau a unei adrese exacte de livrare dintr-un text incomplet al scanării.

8. Data sau intervalul estimat de livrare

Un câmp pentru livrarea estimată ar trebui să indice dacă acesta conține o singură dată sau un interval, cine l-a produs și când a fost actualizat ultima dată. O estimare furnizată de transportator și o predicție calculată separat ar trebui să rămână distincte.

Nu transformați o estimare care conține doar o dată într-o oră precisă de sosire. Integrarea dumneavoastră ar trebui, de asemenea, să gestioneze estimările revizuite sau retrase fără a păstra o promisiune depășită pe pagina de urmărire. Dacă nu există nicio estimare, afișați faptul că aceasta nu este disponibilă, în loc să calculați una pe baza unei presupuneri nefundamentate.

9. Motivul excepției și acțiunea necesară

Informațiile despre excepție ar trebui să explice problema și, atunci când sursa permite, să identifice o acțiune, partea responsabilă sau un termen-limită. O notificare generală privind o întârziere este diferită din punct de vedere operațional de o solicitare de informații despre destinatar.

Păstrați faptele raportate separat de propriile decizii ale fluxului de lucru. De exemplu, compania dumneavoastră poate deschide o sarcină de asistență după o perioadă configurată fără actualizări. Aceasta este o regulă internă de escaladare, nu o dovadă că transportatorul a declarat coletul pierdut. Nu generați instrucțiuni de plată sau solicitări de informații sensibile dintr-un text ambiguu de urmărire.

10. Transferurile între transportatori și numerele de urmărire asociate

Atunci când o expediere trece între operatori, datele utile includ următorul transportator, un număr de urmărire asociat și relația dintre înregistrarea originală și cele ulterioare. Acest lucru poate ajuta la păstrarea continuității atunci când etapa de livrare utilizează un identificator diferit.

Tratați un transfer raportat ca pe o relație, în loc să suprascrieți transportatorul original. Nu combinați înregistrările doar pentru că destinațiile sau numerele de urmărire par similare. Dacă relația nu este furnizată sau confirmată în alt mod, păstrați-o nerezolvată în loc să inventați o călătorie continuă.

11. Rezultatul livrării și referințele dovezii

Atunci când livrarea este raportată, răspunsul ar trebui să ofere ora înregistrată a livrării și orice detaliu disponibil despre aceasta, precum descrierea unui loc sigur sau categoria destinatarului. O referință a dovezii de livrare poate fi, de asemenea, utilă atunci când transportatorul și serviciul o fac disponibilă.

O stare „Livrat” nu ar trebui tratată ca dovadă că destinatarul vizat a acceptat personal coletul. Semnăturile, fotografiile, numele și locațiile precise pot conține informații personale. Limitați accesul, evitați expunerea acestor detalii pe paginile publice de urmărire și confirmați orice cerințe privind autorizarea sau expirarea linkurilor către dovezi.

12. Actualitatea datelor, starea preluării și metadatele răspunsului

Solicitați suficiente metadate pentru a distinge cel mai recent eveniment al expedierii de cea mai recentă preluare reușită a datelor. Valorile utile includ ultima verificare reușită, ultima încercare eșuată, momentul generării răspunsului și dacă datele returnate sunt stocate în cache sau parțiale.

O solicitare API reușită nu stabilește prin ea însăși că transportatorul a publicat o scanare nouă. Semantica răspunsului HTTP descrie rezultatul solicitării; progresul expedierii aparține datelor aplicației. Păstrați separat erorile de preluare de excepțiile expedierii, astfel încât o problemă temporară de conexiune să nu devină o alertă falsă de livrare.

Datele lipsă au nevoie de o semnificație definită

Prezența unui câmp este doar o parte a contractului. Echipa dumneavoastră trebuie, de asemenea, să înțeleagă ce înseamnă o valoare absentă. O estimare de livrare poate fi indisponibilă la sursă, poate să nu fi fost încă preluată sau poate să nu fie aplicabilă după livrare. Aceste situații nu ar trebui să genereze automat același mesaj pentru client.

  • Valoarea nu a fost stabilită.
  • Furnizare absentă: Sursa nu a furnizat valoarea în datele preluate.
  • Neaplicabil: Câmpul nu se aplică acestei înregistrări sau stări.
  • Preluare eșuată: Sistemul nu a putut finaliza căutarea relevantă.

Acestea sunt distincții recomandate, nu valori literale obligatorii. Indiferent de reprezentarea aleasă, documentați-o. Evitați datele-placeholder, obiectele goale care seamănă cu înregistrări valide și coordonatele implicite care ar putea fi confundate cu locații reale.

Cum să testați răspunsul înainte de integrare

Evaluați payload-urile reale de la transportatorii, serviciile și rutele de expediere utilizate de compania dumneavoastră. O schemă poate enumera un câmp opțional fără a garanta că fiecare sursă de bază îl completează. Pentru o integrare 17TRACK, utilizați documentația oficială Tracking API pentru a verifica contractul de răspuns, în loc să tratați denumirile conceptuale ale câmpurilor din acest ghid ca parametri gata de copiat.

  1. Construiți un eșantion reprezentativ. Includeți expedieri înregistrate recent, expedieri active, încercări de livrare, livrări finalizate și cazuri de transfer disponibile.
  2. Urmăriți câmpurile până la evenimente. Confirmați că starea afișată, cel mai recent eveniment și detaliile livrării descriu o înregistrare coerentă. Investigați discrepanțele în loc să le ascundeți.
  3. Testați actualizările întârziate și repetate. Reprocesați același payload și primiți un eveniment mai vechi după unul mai nou. Confirmați că niciunul dintre cazuri nu creează notificări duplicate sau nu inversează incorect starea afișată.
  4. Testați valorile lipsă și incorecte. Includeți estimări absente, locații necunoscute, coduri de stare neobișnuite și marcaje temporale incomplete. Aplicația ar trebui să rămână utilizabilă fără să inventeze înlocuitori.
  5. Separați erorile de transport de rezultatele urmăririi. O eroare de autentificare, un timeout sau un răspuns incorect ar trebui să urmeze calea erorilor de integrare, nu fluxul de lucru pentru excepțiile expedierii.
  6. Validați vizualizarea pentru client. Verificați ca referințele interne, detaliile brute de diagnostic și informațiile personale să nu ajungă pe paginile publice sau în notificări.

Pentru actualizările bazate pe webhook, verificați și identificatorii livrării, autentificarea, comportamentul la reîncercare și gestionarea redării din documentația furnizorului. Acestea sunt cerințe de integrare, nu fapte despre expediere. Receptorul dumneavoastră ar trebui să proceseze în siguranță livrările repetate și să nu presupună că ordinea sosirii este egală cu ordinea evenimentelor.

Criteriul de acceptare ar trebui să fie practic: poate aplicația dumneavoastră să explice expedierea fără a face afirmații nefundamentate și poate echipa operațională să identifice următoarea acțiune justificată? Un payload mai mic și bine definit poate fi mai util decât un răspuns mai amplu, plin de valori opționale neexplicate.

Întrebări frecvente

Este necesar ca toate cele 12 grupuri de date să fie completate pentru fiecare expediere?

Nu. Dovezile livrării, numerele de urmărire ulterioare și datele estimate de livrare pot să nu fie disponibile sau aplicabile. Solicitați definiții clare ale câmpurilor și un comportament previzibil pentru valorile lipsă, nu completarea universală a acestora. Verificați cele mai importante câmpuri în raport cu mixul real de expedieri.

Ar trebui să stocăm răspunsul brut sau doar câmpurile normalizate?

Stocați câmpurile normalizate pentru logica aplicației. Păstrarea payload-urilor relevante ale sursei poate ajuta, de asemenea, la depanare și la modificările de mapare, sub rezerva cerințelor dumneavoastră privind confidențialitatea, securitatea, contractele și păstrarea datelor. Restricționați accesul și evitați păstrarea conținutului sensibil doar pentru că apare într-un răspuns.

Care marcaj temporal ar trebui să determine cel mai recent eveniment?

Utilizați cronologia documentată a evenimentelor și regulile de ordonare ale furnizorului, ținând cont de fusurile orare și de corecții. Ora primirii vă spune când a aflat sistemul dumneavoastră despre un eveniment, nu neapărat când acesta a avut loc. Dacă marcajele temporale sunt incomplete sau contradictorii, păstrați ambiguitatea în loc să afirmați o secvență precisă.

Poate o API de urmărire confirma că un colet este pierdut?

Tratați o pierdere ca fiind raportată de transportator numai atunci când sursa susține explicit această interpretare. O perioadă lungă fără scanări poate justifica o investigație conform regulilor dumneavoastră operaționale, dar tăcerea singură nu stabilește că expedierea este pierdută. Păstrați „urmărire învechită” și „pierdut raportat” ca noțiuni separate.

Este suficientă starea „Livrat” pentru a închide o reclamație a clientului?

Nu automat. Aceasta stabilește rezultatul raportat al urmăririi, dar este posibil să nu rezolve disputa destinatarului. Examinați detaliile disponibile ale livrării, contul clientului și procesul dumneavoastră de asistență. Evitați tratarea unei etichete de stare ca înlocuitor pentru investigarea informațiilor contradictorii.

Surse