Skip to main content
AcasăBlogGhiduriCum să obții cel mai recent status al expedierii prin API fără a aștepta un webhook

Cum să obții cel mai recent status al expedierii prin API fără a aștepta un webhook

17TRACK

Pentru a obține cel mai recent status disponibil al expedierii fără a aștepta un webhook, trimiteți o solicitare autentificată către API-ul de interogare a expedierilor al furnizorului de tracking. Folosiți răspunsul pentru a actualiza imediat aplicația, apoi mențineți webhook-urile activate pentru modificările ulterioare. Distincția importantă este că o interogare preia de obicei cele mai recente informații de tracking stocate de furnizor; aceasta nu declanșează neapărat o nouă verificare la transportator.

Cum să obțineți cel mai recent status al expedierii prin API fără

Această abordare este utilă atunci când un client deschide pagina unei comenzi, un agent de asistență are nevoie de o actualizare sau sistemul trebuie să se recupereze după o notificare omisă. O implementare fiabilă combină interogări la cerere, indicatori clari de actualitate și măsuri de protecție împotriva actualizărilor duplicate sau sosite într-o ordine greșită.

Decideți ce înseamnă „cel mai recent status al expedierii”

Înainte de a alege un endpoint, diferențiați între trei operațiuni care pot suna similar, dar produc rezultate diferite.

OperațiuneCe faceCe nu stabilește
Citiți propria bază de dateReturnează informațiile de tracking pe care aplicația le deține deja.Dacă furnizorul a primit o actualizare mai nouă.
Interogați API-ul de trackingPreia informațiile disponibile prin operațiunea de interogare a furnizorului.Dacă în timpul solicitării a avut loc o nouă căutare la transportator.
Solicitați o reîmprospătare a trackinguluiSolicită o altă verificare în amonte, dacă furnizorul oferă această operațiune.Că transportatorul are o scanare nouă sau că reîmprospătarea se finalizează sincron.

Folosiți o interogare atunci când aveți nevoie de un răspuns imediat. Investigați o operațiune de reîmprospătare numai atunci când aveți nevoie ca furnizorul să încerce o altă verificare în amonte. Nu presupuneți că adăugarea unui parametru pentru evitarea cache-ului, repetarea unei solicitări sau trimiterea unui antet HTTP cache-control va obliga transportatorul să furnizeze informații noi.

Vizibilitatea expedierii are mai multe etape: transportatorul înregistrează un eveniment, furnizorul de tracking îl obține, iar aplicația îl primește sau îl preia. O solicitare directă API poate evita așteptarea livrării notificării, dar nu poate elimina întârzierile apărute mai devreme în acest lanț.

Verificați contractul interogării înainte de a scrie cod

Dezvoltatorul care integrează serviciul de tracking deține acest flux de lucru. Începeți cu documentația actuală a furnizorului, nu cu un endpoint copiat dintr-un exemplu vechi de integrare. Confirmați aceste detalii:

  • Identitatea expedierii: Interogarea acceptă un număr de tracking, un ID intern al expedierii sau un număr de tracking combinat cu un identificator al transportatorului?
  • Cerințe de înregistrare: Expedierea trebuie înregistrată înainte de a putea fi interogată?
  • Autentificare: Ce antet sau mecanism de autentificare este necesar?
  • Semnificația răspunsului: Operațiunea returnează informații stocate, inițiază colectarea sau returnează o sarcină care trebuie verificată ulterior?
  • Gestionarea rezultatului: Un răspuns HTTP de succes poate conține o eroare la nivelul expedierii sau un rezultat în așteptare?
  • Restricții de utilizare: Ce limite de frecvență, limite pentru loturi și restricții specifice contului se aplică?
  • Câmpuri privind actualitatea: Ce marcaje temporale reprezintă evenimentele transportatorului, actualizările furnizorului și generarea răspunsului?

Pentru o integrare 17TRACK, Tracking API este produsul relevant, nu o pagină de tracking pentru consumatori sau o interfață de tracking a magazinului. Folosiți documentația oficială API pentru a confirma operațiunea de interogare a informațiilor de tracking, autentificarea, câmpurile solicitării și structura răspunsului pentru integrarea dvs. Tratați interogarea și gestionarea webhook-urilor ca fluxuri separate ale aplicației, care actualizează aceeași înregistrare a expedierii.

Evitați să codificați în mod rigid presupuneri despre comportamentul de reîmprospătare sau frecvența interogărilor. Aceste detalii trebuie să corespundă operațiunii și condițiilor serviciului pe care îl utilizați efectiv.

Construiți o căutare la cerere prin backend-ul dvs.

Un design practic este să expuneți un endpoint autentificat în propria aplicație. Browserul solicită o actualizare a expedierii de la acel endpoint; serverul verifică autorizarea, decide dacă este necesară o interogare a furnizorului și returnează un rezultat normalizat.

Ruta următoare este un exemplu de endpoint pe care l-ați crea în aplicația dvs. Nu este un endpoint 17TRACK sau o specificație de solicitare a furnizorului.

GET /api/orders/{order_id}/shipment-status

Folosiți identificatorul comenzii pentru a căuta expedierea pe server. Nu permiteți unui apelant să recupereze istoricul de tracking al altui client doar prin înlocuirea unui număr de tracking într-o solicitare. Păstrați acreditarea API a furnizorului în backend, nu în JavaScript-ul browserului sau în pachetul unei aplicații mobile.

Un flux de solicitare pe care îl puteți implementa

  1. Autorizați accesul. Confirmați că clientul sau membrul personalului poate vizualiza comanda.
  2. Identificați expedierea. Citiți identificatorul de tracking stocat și informațiile despre transportator, acolo unde este cazul.
  3. Verificați actualitatea locală. Dacă există deja o interogare recentă finalizată cu succes, reutilizați-o conform politicii de actualitate a aplicației.
  4. Interogați furnizorul atunci când este necesar. Folosiți operațiunea documentată și un timeout limitat pentru solicitare.
  5. Validați rezultatul. Verificați atât rezultatul HTTP, cât și rezultatul la nivelul expedierii.
  6. Îmbinați informațiile. Aplicați aceleași reguli de normalizare și reconciliere utilizate pentru evenimentele webhook.
  7. Returnați statusul și actualitatea. Includeți ora celui mai recent eveniment și ora ultimei verificări reușite la furnizor, atunci când sunt disponibile.

Politica locală de actualitate este o decizie de inginerie, nu o declarație despre frecvența actualizărilor transportatorului. Alegeți-o pe baza cerințelor interfeței, limitelor furnizorului, volumului expedierilor și utilității observate a interogărilor. Un client care apasă în mod repetat un buton de actualizare nu ar trebui să creeze un flux nelimitat de solicitări în amonte.

Normalizați răspunsul fără a inventa actualitatea

Aplicația dvs. poate returna un format intern stabil chiar și atunci când structurile răspunsurilor furnizorilor diferă. Acest obiect ilustrativ reprezintă contractul propriei aplicații, nu un payload real al furnizorului:

{
  "shipment_id": "internal-shipment-id",
  "status": "in_transit",
  "latest_event_at": null,
  "provider_updated_at": null,
  "last_successful_query_at": null,
  "retrieval_state": "success",
  "source": "provider_query"
}

Completați fiecare marcaj temporal numai atunci când îi cunoașteți semnificația. Ora la care serverul dvs. a primit un răspuns aparține metadatelor interogării; nu trebuie prezentată ca ora la care s-a deplasat coletul. Dacă furnizorul nu oferă un marcaj temporal pentru actualizarea furnizorului, lăsați acel câmp absent sau null, în loc să substituiți un alt marcaj temporal.

Pentru interfața clientului, separați mesajele: „Ultimul eveniment al transportatorului” descrie activitatea expedierii, în timp ce „Tracking verificat” descrie activitatea de preluare a aplicației. Această distincție împiedică afișarea unei scanări neschimbate ca fiind înregistrată recent.

Împiedicați interogările API și webhook-urile să se suprascrie reciproc

Odată ce ambele mecanisme sunt active, același eveniment poate sosi printr-o interogare și un webhook. De asemenea, acestea se pot finaliza într-o ordine diferită de cea în care au început. O interogare lansată prima se poate finaliza după ce un webhook a furnizat deja informații mai noi.

Nu folosiți logica „ultimul răspuns câștigă”. Payload-ul primit cel mai recent nu reprezintă neapărat cel mai recent status al expedierii.

  • Partajați un singur flux de actualizare. Trimiteți rezultatele interogărilor și payload-urile webhook prin aceleași funcții de validare, normalizare și persistență.
  • Eliminați evenimentele duplicate. Preferați un identificator de eveniment documentat. Dacă acesta nu există, construiți o amprentă definită cu atenție din câmpurile disponibile, precum ora evenimentului, statusul, locația și descrierea.
  • Folosiți câmpuri de ordonare cu semnificație cunoscută. O revizie sau o secvență documentată este mai utilă decât presupunerea că ora sosirii reprezintă ordinea evenimentelor.
  • Păstrați istoricul. Un eveniment primit recent poate completa o lacună istorică fără a modifica rezumatul actual al expedierii.
  • Permiteți corecțiile. Statusurile nu formează o scară liniară universală. Urmați comportamentul documentat pentru corecții în loc să respingeți permanent fiecare tranziție aparent regresivă.

Atunci când ordinea evenimentelor este incertă, păstrați payload-ul original și proveniența acestuia pentru investigații. Nu rezolvați ambiguitatea inventând un marcaj temporal al evenimentului sau presupunând că toate marcajele temporale ale transportatorului folosesc același fus orar.

Tratați diferit datele lipsă și solicitările eșuate

Un rezultat gol, un rezultat neschimbat și o solicitare eșuată nu ar trebui să genereze același mesaj pentru client.

Interogarea reușește, dar statusul nu s-a schimbat

Păstrați statusul existent al expedierii și actualizați ora ultimei interogări reușite. Nu generați un nou eveniment al expedierii doar pentru că s-a finalizat o altă căutare. Dacă clientul are nevoie de mai multe detalii, afișați istoricul existent al evenimentelor și explicați că nu a fost returnat niciun eveniment de tracking mai nou.

Expedierea nu are încă informații de tracking

Verificați dacă este necesară înregistrarea, dacă identificatorul și transportatorul sunt corecte și cum reprezintă furnizorul colectarea în așteptare. Lipsa evenimentelor nu dovedește prin ea însăși că numărul de tracking este invalid sau că pachetul s-a pierdut. Păstrați distincția furnizorului între un identificator necunoscut, o expediere înregistrată care așteaptă informații și o solicitare care nu a putut fi procesată.

Solicitarea către furnizor expiră sau eșuează

Dacă aveți un status valid anterior, returnați-l cu o indicație explicită că ultima verificare nu a reușit. Păstrați neschimbată ora interogării reușite anterioare. O eroare de rețea nu reprezintă o excepție de livrare și nu ar trebui să schimbe statusul comercial al coletului.

Folosiți reîncercări limitate cu backoff și jitter pentru erorile tranzitorii potrivite. Nu reîncercați în mod repetat acreditările invalide sau solicitările incorecte. Atunci când un răspuns furnizează Retry-After, interpretați-l conform contractului furnizorului și semnificației HTTP. Specificația HTTP permite exprimarea acestei valori ca o întârziere în secunde sau ca o dată HTTP.

Sosesc mai multe solicitări pentru aceeași expediere

Combinați căutările concurente astfel încât acestea să poată partaja o singură solicitare în amonte. Aplicați limite per cont și per expediere și împiedicați multiplicarea unei reîncercări automate în mai multe straturi ale aplicației. Atunci când este acceptată procesarea pe loturi, inspectați rezultatul fiecărei expedieri în loc să considerați întregul lot ca fiind reușit deoarece solicitarea HTTP s-a finalizat.

Folosiți sondarea ca soluție de rezervă controlată

Fără webhook-uri, sondarea programată poate menține baza de date actualizată, dar necesită o politică operațională explicită. Decideți ce expedieri rămân eligibile, cum afectează erorile programarea și când se oprește sondarea de rutină.

Pentru majoritatea integrărilor, un design hibrid este un punct de pornire rezonabil: webhook-urile gestionează modificările din fundal, interogările la cerere deservesc solicitările interactive, iar sarcinile de reconciliere verifică înregistrările care necesită atenție. Aceasta este o recomandare arhitecturală, nu o garanție că minimizează costurile pentru fiecare cont.

  • Prioritizați expedierile active și înregistrările cu erori de preluare nerezolvate.
  • Evitați interogarea fiecărei expedieri istorice la fiecare rulare programată.
  • Definiți modul în care sunt gestionate expedierile finalizate, inclusiv orice perioadă de corecție necesară afacerii dvs.
  • Urmăriți cât de des interogările găsesc informații cu adevărat noi.
  • Investigați problemele de livrare a webhook-urilor în loc să le mascați prin sondări din ce în ce mai frecvente.

Monitorizați latența solicitărilor către furnizor, interogările nereușite, răspunsurile privind limitele de frecvență și diferențele dintre datele interogate și înregistrările alimentate prin webhook. Monitorizați separat vechimea celui mai recent eveniment al transportatorului. Răspunsurile API reușite pot coexista cu informații de tracking care nu s-au schimbat.

Testați fluxul de lucru înainte de lansare

O solicitare reușită este doar primul test. Verificați situațiile care pot genera altfel actualizări înșelătoare ale statusului:

  • Un webhook sosește în timp ce o interogare la cerere este încă în desfășurare.
  • Doi clienți sau membri ai personalului solicită simultan aceeași expediere.
  • Furnizorul returnează succes HTTP, dar raportează o eroare la nivelul expedierii.
  • O solicitare eșuează după ce aplicația dvs. deține deja informații valide de tracking.
  • Un eveniment nu conține fusul orar sau include un cod de status necunoscut.
  • O corecție a transportatorului modifică un rezultat afișat anterior.
  • Un utilizator încearcă să acceseze o expediere care aparține altui cont.

Criteriul de lansare ar trebui să fie ca aplicația să returneze cele mai bune informații cunoscute despre expediere, să explice corect actualitatea acestora și să nu le corupă atunci când solicitările eșuează sau sosesc într-o ordine greșită.

Întrebări frecvente

Interogarea API-ului obligă transportatorul să scaneze sau să actualizeze un colet?

Nu. Preluarea informațiilor de tracking nu poate provoca o scanare fizică. Dacă o solicitare declanșează o căutare în amonte depinde de operațiunea documentată. Chiar și o reîmprospătare acceptată poate returna informații neschimbate dacă transportatorul nu are un eveniment mai nou.

Pot folosi interogări API fără să configurez webhook-uri?

Dacă furnizorul acceptă fluxul de interogare necesar, puteți construi o integrare bazată pe solicitări la cerere sau sondare. Confirmați mai întâi cerințele de înregistrare și interogare. Aplicația dvs. va fi apoi responsabilă să decidă când să verifice, să controleze volumul solicitărilor și să detecteze modificările.

Cât de des ar trebui să sondez statusul expedierii?

Nu există un interval universal. Alegeți un program care se potrivește limitelor furnizorului, volumului expedierilor și valorii comerciale a identificării mai rapide a actualizărilor. Măsurați cât de des sondarea returnează evenimente noi, apoi ajustați-o în loc să presupuneți că solicitările frecvente produc date mai actuale de la transportator.

De ce returnează API-ul informații pe care le-am primit deja printr-un webhook?

Ambele căi pot expune aceeași înregistrare de bază a expedierii. Un webhook livrează o notificare, în timp ce o interogare preia informații la cerere. Primirea aceluiași eveniment prin ambele căi nu este neapărat o eroare; aplicația dvs. ar trebui să elimine dublurile.

Butonul de actualizare ar trebui să spună „Reîmprospătați trackingul”?

Numai dacă formularea descrie cu exactitate operațiunea. Dacă butonul preia date stocate ale furnizorului, „Verificați actualizările” este mai clar. Afișați separat ultimul eveniment al transportatorului și momentul în care aplicația dvs. a finalizat ultima verificare reușită.

Surse