Kako pridobiti najnovejši status pošiljke prek API-ja brez čakanja na Webhook
Če želite pridobiti najnovejši razpoložljivi status pošiljke brez čakanja na spletni kavelj, pošljite overjeno zahtevo API-ju svojega ponudnika za poizvedbe o pošiljkah. Z odgovorom takoj posodobite svojo aplikacijo, nato pa pustite spletne kavlje omogočene za poznejše spremembe. Pomembna razlika je, da poizvedba običajno pridobi najnovejše shranjene podatke o sledenju pri ponudniku; ni pa nujno, da sproži novo preverjanje pri prevozniku.

Ta pristop je uporaben, ko stranka odpre stran naročila, ko podporni agent potrebuje posodobitev ali ko mora vaš sistem obnoviti podatke po zgrešenem obvestilu. Zanesljiva izvedba združuje poizvedbe na zahtevo, jasne kazalnike ažurnosti ter zaščito pred podvojenimi ali časovno napačno razvrščenimi posodobitvami.
Odločite se, kaj pomeni »najnovejši status pošiljke«
Pred izbiro končne točke ločite med tremi postopki, ki se lahko slišijo podobno, vendar dajejo različne rezultate.
| Postopek | Kaj naredi | Česa ne potrdi |
|---|---|---|
| Branje lastne podatkovne zbirke | Vrne podatke o sledenju, ki jih vaša aplikacija že hrani. | Ali je ponudnik prejel novejšo posodobitev. |
| Poizvedba API-ja za sledenje | Pridobi podatke, ki so na voljo prek poizvedbenega postopka ponudnika. | Ali je bilo med zahtevo izvedeno novo preverjanje pri prevozniku. |
| Zahteva za osvežitev sledenja | Zahteva novo preverjanje pri nadrejenem viru, če ponudnik ta postopek ponuja. | Da ima prevoznik novo skeniranje ali da se osvežitev izvede sinhrono. |
Poizvedbo uporabite, ko potrebujete odgovor takoj. O postopku osvežitve razmislite le, ko želite, da ponudnik poskusi novo preverjanje pri nadrejenem viru. Ne domnevajte, da bo dodajanje parametra za preprečevanje predpomnjenja, ponavljanje zahteve ali pošiljanje glave HTTP cache-control prisililo prevoznika, da zagotovi nove podatke.
Vidnost pošiljke ima več stopenj: prevoznik zabeleži dogodek, ponudnik sledenja ga pridobi, vaša aplikacija pa ga prejme ali pridobi. Neposredna zahteva API-ja lahko zaobide čakanje na dostavo obvestila, vendar ne more odpraviti zamud v prejšnjih delih te verige.
17TRACK Order Tracking — Stranke obveščajte o statusu dostave in izboljšajte blagovno izkušnjo po nakupu za DTC.
17TRACK API Global Shipment Tracking Solution — Prek enega API-ja se povežite z več kot 3.500 prevozniki po vsem svetu za preprosto, natančno in zanesljivo sledenje paketom.
Sorodni članek: Kako izbrati API za sledenje pošiljkam za dostave v Franciji
Pred pisanjem kode preverite pogodbo poizvedbe
Razvijalec, ki vključuje storitev sledenja, je odgovoren za ta potek. Začnite z aktualno dokumentacijo ponudnika, ne s končno točko, kopirano iz starega primera integracije. Potrdite naslednje podrobnosti:
- Identiteta pošiljke: Ali poizvedba sprejme številko za sledenje, notranji ID pošiljke ali številko za sledenje skupaj z identifikatorjem prevoznika?
- Zahteve za registracijo: Ali mora biti pošiljka registrirana, preden je po njej mogoče poizvedovati?
- Preverjanje pristnosti: Katera glava ali mehanizem preverjanja pristnosti je zahtevan?
- Pomen odgovora: Ali postopek vrne shranjene podatke, začne zbiranje podatkov ali vrne opravilo, ki ga je treba preveriti pozneje?
- Obravnava rezultatov: Ali lahko uspešen odgovor HTTP vsebuje napako na ravni pošiljke ali čakajoči rezultat?
- Omejitve uporabe: Katere omejitve hitrosti, paketne omejitve in omejitve, povezane z računom, veljajo?
- Polja ažurnosti: Kateri časovni žigi predstavljajo dogodke prevoznika, posodobitve ponudnika in ustvarjanje odgovora?
Pri integraciji 17TRACK je Tracking API ustrezen izdelek, ne potrošniška stran za sledenje ali vmesnik trgovine. Za potrditev postopka poizvedbe informacij o sledenju, preverjanja pristnosti, polj zahtev in strukture odgovora za svojo integracijo uporabite uradno dokumentacijo API-ja. Poizvedovanje in obravnavo spletnih kavljev obravnavajte kot ločeni poti aplikacije, ki posodabljata isti zapis pošiljke.
Nadaljujte z branjem: Kako izbrati API za sledenje pošiljkam za e-trgovino?
Izogibajte se trdemu kodiranju predpostavk o vedenju osveževanja ali pogostosti poizvedb. Te podrobnosti se morajo ujemati s postopkom in pogoji storitve, ki jih dejansko uporabljate.
Vzpostavite iskanje na zahtevo prek zalednega sistema
Praktična zasnova je, da v svoji aplikaciji izpostavite overjeno končno točko. Brskalnik od te končne točke zahteva posodobitev pošiljke; vaš strežnik preveri dovoljenja, odloči, ali je poizvedba pri ponudniku potrebna, in vrne normaliziran rezultat.
17RETURNS Returns & Exchanges Solution — Z avtomatiziranimi vračili in zamenjavami, podprtimi s pametnimi orodji za ohranjanje strank, zmanjšajte stroške podpore in obdržite več prihodkov.
Naslednja pot je primer končne točke, ki bi jo ustvarili v svoji aplikaciji. Ni končna točka 17TRACK ali specifikacija zahteve ponudnika.
GET /api/orders/{order_id}/shipment-statusIdentifikator naročila uporabite za iskanje pošiljke na strežniku. Klicatelju ne dovolite, da bi pridobil zgodovino sledenja druge stranke samo z zamenjavo številke za sledenje v zahtevi. Poverilnico API-ja ponudnika hranite v zalednem sistemu, ne v JavaScriptu brskalnika ali paketu mobilne aplikacije.
Potek zahteve, ki ga lahko izvedete
- Pooblastite dostop. Potrdite, da si stranka ali član osebja lahko ogleda naročilo.
- Razrešite pošiljko. Preberite shranjeni identifikator za sledenje in po potrebi podatke o prevozniku.
- Preverite lokalno ažurnost. Če že obstaja nedavna uspešna poizvedba, jo ponovno uporabite v skladu s pravilnikom aplikacije o ažurnosti.
- Po potrebi poizvedujte pri ponudniku. Uporabite dokumentirani postopek in omejeno časovno omejitev zahteve.
- Preverite rezultat. Preverite izid HTTP in rezultat na ravni pošiljke.
- Združite podatke. Uporabite ista pravila normalizacije in usklajevanja kot pri dogodkih spletnih kavljev.
- Vrnite status in ažurnost. Kadar sta na voljo, vključite čas najnovejšega dogodka in čas zadnjega uspešnega preverjanja pri ponudniku.
Pravilnik lokalne ažurnosti je inženirska odločitev, ne izjava o pogostosti posodobitev prevoznika. Določite ga glede na zahteve vmesnika, omejitve ponudnika, obseg pošiljk in opaženo uporabnost poizvedb. Stranka, ki večkrat klikne gumb za posodobitev, ne sme ustvariti neomejenega toka zahtev do nadrejenega vira.
Normalizirajte odgovor brez izmišljanja ažurnosti
Vaša aplikacija lahko vrne stabilno notranjo obliko, tudi če se strukture odgovorov ponudnikov razlikujejo. Ta ponazoritveni objekt je vaša pogodba aplikacije, ne dejanski tovor ponudnika:
{
"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"
}Vsak časovni žig izpolnite samo, če je njegov pomen znan. Čas, ko je vaš strežnik prejel odgovor, spada v metapodatke poizvedbe; ne smete ga prikazati kot čas premika paketa. Če ponudnik ne zagotovi časovnega žiga posodobitve ponudnika, pustite polje prazno ali nastavljeno na null, namesto da bi nadomestili drug časovni žig.
V vmesniku za stranke ločite sporočili: »Najnovejši dogodek prevoznika« opisuje dejavnost pošiljke, »Sledenje preverjeno« pa dejavnost pridobivanja podatkov vaše aplikacije. Ta razlika preprečuje, da bi bilo nespremenjeno skeniranje videti kot novo zabeleženo.
Preprečite, da bi API-poizvedbe in spletni kavlji prepisovali drug drugega
Ko sta oba mehanizma aktivna, lahko isti dogodek prispe prek poizvedbe in spletnega kavlja. Prav tako se lahko zaključita v drugačnem vrstnem redu, kot sta se začela. Poizvedba, zagnana prva, se lahko zaključi šele po tem, ko je spletni kavelj že posredoval novejše podatke.
Ne uporabljajte logike »zmaga zadnji odgovor«. Nazadnje prejeti tovor ni nujno najnovejše stanje pošiljke.
- Uporabite en cevovod posodobitev. Rezultate poizvedb in tovore spletnih kavljev pošljite skozi iste funkcije za preverjanje, normalizacijo in shranjevanje.
- Odstranjujte podvojene dogodke. Prednost dajte dokumentiranemu identifikatorju dogodka. Če ga ni, sestavite skrbno opredeljen prstni odtis iz razpoložljivih polj, kot so čas dogodka, status, lokacija in opis.
- Uporabljajte polja za razvrščanje z znanim pomenom. Dokumentirana revizija ali zaporedje je uporabnejše od predpostavke, da čas prihoda predstavlja vrstni red dogodkov.
- Ohranite zgodovino. Novo prejeti dogodek lahko zapolni zgodovinsko vrzel, ne da bi spremenil trenutni povzetek pošiljke.
- Dovolite popravke. Statusi niso univerzalna linearna lestvica. Upoštevajte dokumentirano vedenje popravkov, namesto da bi trajno zavrnili vsak navidezni korak nazaj.
Ko je vrstni red dogodkov negotov, za preiskavo ohranite izvirni tovor in njegov izvor. Ne razrešujte dvoumnosti z izmišljanjem časovnega žiga dogodka ali s predpostavko, da imajo vsi časovni žigi prevoznikov isti časovni pas.
Manjkajoče podatke in neuspešne zahteve obravnavajte različno
Prazen rezultat, nespremenjen rezultat in neuspešna zahteva ne smejo povzročiti istega sporočila za stranko.
Poizvedba uspe, vendar se status ni spremenil
Ohranite obstoječi status pošiljke in posodobite čas zadnje uspešne poizvedbe. Ne ustvarite novega dogodka pošiljke samo zato, ker je bilo opravljeno novo iskanje. Če stranka potrebuje več podrobnosti, prikažite obstoječo zgodovino dogodkov in pojasnite, da ni bil vrnjen noben novejši dogodek sledenja.
Pošiljka še nima podatkov o sledenju
Preverite, ali je potrebna registracija, ali sta identifikator in prevoznik pravilna ter kako ponudnik predstavlja čakajoče zbiranje podatkov. Pomanjkanje dogodkov samo po sebi ne dokazuje, da je številka za sledenje neveljavna ali da je paket izgubljen. Ohranite razlikovanje ponudnika med neznanim identifikatorjem, registrirano pošiljko, ki čaka na podatke, in zahtevo, ki je ni bilo mogoče obdelati.
Zahteva ponudniku poteče ali ne uspe
Če imate prejšnji veljavni status, ga vrnite z jasnim pojasnilom, da najnovejše preverjanje ni uspelo. Čas prejšnje uspešne poizvedbe pustite nespremenjen. Omrežna napaka ni izjema pri dostavi in ne sme spremeniti poslovnega statusa paketa.
Nadaljnje branje: Vodnik za »v dostavi«: kaj pomeni in kaj morate storiti naslednje
Za ustrezne začasne napake uporabite omejeno število ponovnih poskusov z naraščajočim zamikom in naključnim razpršenjem. Ne ponavljajte zahtev z neveljavnimi poverilnicami ali napačno oblikovanimi podatki. Če odgovor vsebuje Retry-After, ga razlagajte v skladu s pogodbo ponudnika in semantiko HTTP. Specifikacija HTTP dovoljuje, da je ta vrednost izražena kot zakasnitev v sekundah ali kot datum HTTP.
Za isto pošiljko prispe več zahtev
Sočasna iskanja združite, da lahko delijo eno zahtevo do nadrejenega vira. Uveljavite omejitve po računu in pošiljki ter preprečite, da bi se samodejni ponovni poskus množil skozi več plasti aplikacije. Če je paketna obdelava podprta, preglejte rezultat vsake pošiljke, namesto da bi celoten paket obravnavali kot uspešen samo zato, ker je bila zahteva HTTP zaključena.
Uporabite periodično preverjanje kot nadzorovano rezervno možnost
Brez spletnih kavljev lahko načrtovano periodično preverjanje ohranja posodobljeno podatkovno zbirko, vendar zahteva izrecno operativno politiko. Določite, katere pošiljke ostanejo upravičene, kako napake vplivajo na urnik in kdaj se rutinsko preverjanje ustavi.
Za večino integracij je hibridna zasnova smiselno izhodišče: spletni kavlji obravnavajo spremembe v ozadju, poizvedbe na zahtevo služijo interaktivnim zahtevam, opravila usklajevanja pa preverjajo zapise, ki potrebujejo pozornost. To je arhitekturno priporočilo, ne zagotovilo, da bo zmanjšalo stroške za vsak račun.
- Dajte prednost aktivnim pošiljkam in zapisom z nerešenimi napakami pri pridobivanju.
- Izogibajte se poizvedovanju po vseh zgodovinskih pošiljkah pri vsakem načrtovanem zagonu.
- Določite obravnavo zaključenih pošiljk, vključno z morebitnim časovnim oknom za popravke, ki ga zahteva vaše podjetje.
- Spremljajte, kako pogosto poizvedbe najdejo resnično nove podatke.
- Preiskujte težave pri dostavi spletnih kavljev, namesto da jih prikrivate z vedno pogostejšim periodičnim preverjanjem.
Spremljajte zakasnitev zahtev ponudniku, neuspešne poizvedbe, odgovore o omejitvi hitrosti ter razlike med podatki iz poizvedb in zapisi, napolnjenimi prek spletnih kavljev. Ločeno spremljajte starost najnovejšega dogodka prevoznika. Uspešni odgovori API-ja lahko obstajajo skupaj s podatki o sledenju, ki se niso spremenili.
Pred izdajo preizkusite potek
Uspešna zahteva je šele prvi preizkus. Preverite situacije, ki bi sicer lahko ustvarile zavajajoče posodobitve statusa:
- Spletni kavelj prispe, medtem ko poizvedba na zahtevo še teče.
- Dve stranki ali seji osebja hkrati zahtevata isto pošiljko.
- Ponudnik vrne uspeh HTTP, vendar poroča o napaki na ravni pošiljke.
- Zahteva ne uspe, potem ko vaša aplikacija že vsebuje veljavne podatke o sledenju.
- Dogodek nima časovnega pasu ali vsebuje neznano kodo statusa.
- Popravek prevoznika spremeni prej prikazan rezultat.
- Uporabnik poskuša dostopati do pošiljke, ki pripada drugemu računu.
Merilo za izdajo naj bo, da aplikacija vrne najboljše znane podatke o pošiljki, natančno pojasni njihovo ažurnost in teh podatkov ne poškoduje, ko zahteve ne uspejo ali prispejo v napačnem vrstnem redu.
Pogosta vprašanja
Ali poizvedovanje po API-ju prisili prevoznika, da skenira ali posodobi paket?
Ne. Pridobivanje podatkov o sledenju ne more povzročiti fizičnega skeniranja. Ali zahteva sproži iskanje pri nadrejenem viru, je odvisno od dokumentiranega postopka. Tudi podprta osvežitev lahko vrne nespremenjene podatke, če prevoznik nima novejšega dogodka.
Ali lahko uporabljam poizvedbe API-ja brez nastavitve spletnih kavljev?
Če ponudnik podpira zahtevani potek poizvedb, lahko integracijo zgradite okoli zahtev na zahtevo ali periodičnega preverjanja. Najprej potrdite zahteve za registracijo in poizvedbo. Vaša aplikacija bo nato odgovorna za odločanje, kdaj preverjati, nadzor količine zahtev in zaznavanje sprememb.
Kako pogosto naj preverjam status pošiljke?
Univerzalnega intervala ni. Izberite urnik, ki ustreza omejitvam ponudnika, obsegu vaših pošiljk in poslovni vrednosti zgodnejšega odkrivanja posodobitev. Izmerite, kako pogosto periodično preverjanje vrne nove dogodke, nato urnik prilagodite, namesto da bi domnevali, da pogoste zahteve zagotavljajo sveže podatke prevoznika.
Zakaj API vrne podatke, ki sem jih že prejel prek spletnega kavlja?
Obe poti lahko razkrijeta isti osnovni zapis pošiljke. Spletni kavelj dostavi obvestilo, poizvedba pa na zahtevo pridobi podatke. Prejem istega dogodka prek obeh poti ni nujno napaka; vaša aplikacija ga mora odstraniti kot dvojnik.
Ali naj bo na gumbu za posodobitev napis »Osveži sledenje«?
Le če ta izraz natančno opisuje postopek. Če gumb pridobi shranjene podatke ponudnika, je jasnejši napis »Preveri posodobitve«. Najnovejši dogodek prevoznika prikažite ločeno od časa, ko je vaša aplikacija nazadnje uspešno zaključila preverjanje.
Viri
- 17TRACK Tracking API — uradna referenca izdelka za integracijo API-ja za sledenje, obravnavano v tem vodniku.
- Dokumentacija API-ja 17TRACK — referenca za postopke, preverjanje pristnosti, polja zahtev in obravnavo odgovorov, specifične za ponudnika.
- RFC 9110, razdelek 10.2.3: Retry-After — opredeljuje obliki zamude v sekundah in datuma HTTP za glavo.


