Skip to main content
ПочетакБлогVodičiKako dobiti najnoviji status pošiljke putem API-ja bez čekanja na webhook

Kako dobiti najnoviji status pošiljke putem API-ja bez čekanja na webhook

17TRACK

Da biste dobili najnoviji dostupni status pošiljke bez čekanja na webhook, pošaljite autentifikovani zahtev API-ju svog provajdera za upite o pošiljkama. Iskoristite odgovor da odmah ažurirate svoju aplikaciju, a zatim zadržite webhook-ove aktivnim za naknadne promene. Važna razlika je u tome što upit obično preuzima najnovije sačuvane informacije o praćenju kod provajdera; on ne mora nužno da pokrene novu proveru kod prevoznika.

Kako dobiti najnoviji status pošiljke putem API-ja bez čekanja

Ovaj pristup je koristan kada kupac otvori stranicu porudžbine, kada agent korisničke podrške treba ažurirane informacije ili kada vaš sistem treba da se oporavi od propuštenog obaveštenja. Pouzdana implementacija kombinuje upite na zahtev, jasne pokazatelje ažurnosti i zaštitne mehanizme protiv dupliranih ili vremenski nepravilno pristiglih ažuriranja.

Odredite šta znači „najnoviji status pošiljke“

Pre nego što izaberete krajnju tačku, razlikujte tri operacije koje mogu zvučati slično, ali daju različite rezultate.

OperacijaŠta radiŠta ne utvrđuje
Čitanje sopstvene baze podatakaVraća informacije o praćenju koje vaša aplikacija već poseduje.Da li je provajder primio novije ažuriranje.
Upit API-ju za praćenjePreuzima informacije dostupne putem operacije upita kod provajdera.Da li je tokom tog zahteva izvršena nova provera kod prevoznika.
Zahtev za osvežavanje praćenjaZahteva novu proveru na višem nivou, ako provajder nudi tu operaciju.Da prevoznik ima novo skeniranje ili da će se osvežavanje završiti sinhrono.

Koristite upit kada vam je odgovor potreban odmah. Operaciju osvežavanja istražujte samo kada je potrebno da provajder pokuša novu proveru na višem nivou. Nemojte pretpostavljati da će dodavanje parametra za zaobilaženje keša, ponavljanje zahteva ili slanje HTTP zaglavlja za kontrolu keša primorati prevoznika da dostavi nove informacije.

Vidljivost pošiljke ima nekoliko faza: prevoznik beleži događaj, provajder za praćenje ga preuzima, a vaša aplikacija ga prima ili preuzima. Direktan API zahtev može zaobići čekanje na dostavu obaveštenja, ali ne može ukloniti kašnjenja koja nastaju ranije u tom lancu.

Proverite ugovor za upit pre pisanja koda

Programer koji integriše uslugu praćenja odgovoran je za ovaj tok rada. Počnite od važeće dokumentacije provajdera, a ne od krajnje tačke preuzete iz starog primera integracije. Potvrdite sledeće detalje:

  • Identitet pošiljke: Da li upit prihvata broj za praćenje, interni ID pošiljke ili broj za praćenje u kombinaciji sa identifikatorom prevoznika?
  • Uslovi registracije: Da li pošiljka mora biti registrovana pre nego što se može pretraživati?
  • Autentifikacija: Koje zaglavlje ili mehanizam autentifikacije je potreban?
  • Značenje odgovora: Da li operacija vraća sačuvane informacije, pokreće prikupljanje ili vraća zadatak koji treba proveriti kasnije?
  • Obrada rezultata: Da li uspešan HTTP odgovor može sadržati grešku na nivou pošiljke ili rezultat na čekanju?
  • Ograničenja korišćenja: Koja ograničenja brzine, grupnog slanja i specifična ograničenja naloga važe?
  • Polja ažurnosti: Koje vremenske oznake predstavljaju događaje prevoznika, ažuriranja provajdera i generisanje odgovora?

Za integraciju sa 17TRACK, Tracking API je odgovarajući proizvod, a ne korisnička stranica za praćenje ili interfejs za praćenje u prodavnici. Koristite zvaničnu API dokumentaciju da potvrdite operaciju upita za informacije o praćenju, autentifikaciju, polja zahteva i strukturu odgovora za svoju integraciju. Tretirajte upite i obradu webhook-ova kao odvojene putanje aplikacije koje ažuriraju isti zapis pošiljke.

Izbegavajte čvrsto kodirane pretpostavke o ponašanju osvežavanja ili učestalosti upita. Ti detalji moraju odgovarati operaciji i uslovima usluge koju zaista koristite.

Napravite pretragu na zahtev preko svog pozadinskog sistema

Praktičan dizajn je da u sopstvenoj aplikaciji izložite autentifikovanu krajnju tačku. Pregledač traži ažuriranje pošiljke od te krajnje tačke; vaš server proverava ovlašćenje, odlučuje da li je upit provajderu potreban i vraća normalizovan rezultat.

Sledeća ruta je primer krajnje tačke koju biste napravili u svojoj aplikaciji. Ona nije 17TRACK krajnja tačka niti specifikacija zahteva provajdera.

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

Koristite identifikator porudžbine da na serveru pronađete pošiljku. Nemojte dozvoliti pozivaocu da preuzme istoriju praćenja drugog kupca jednostavnom zamenom broja za praćenje u zahtevu. Čuvajte akreditiv API-ja provajdera na pozadinskom sistemu, a ne u JavaScript-u pregledača ili paketu mobilne aplikacije.

Tok zahteva koji možete implementirati

  1. Odobrite pristup. Potvrdite da kupac ili član osoblja sme da vidi porudžbinu.
  2. Pronađite pošiljku. Pročitajte sačuvani identifikator za praćenje i informacije o prevozniku, gde je primenljivo.
  3. Proverite lokalnu ažurnost. Ako već postoji nedavni uspešan upit, ponovo ga upotrebite u skladu sa pravilima ažurnosti svoje aplikacije.
  4. Pošaljite upit provajderu kada je potrebno. Koristite dokumentovanu operaciju i ograničeno vreme čekanja zahteva.
  5. Potvrdite rezultat. Proverite i HTTP ishod i rezultat na nivou pošiljke.
  6. Sjedinite informacije. Primeniće se ista pravila normalizacije i usklađivanja koja se koriste za webhook događaje.
  7. Vratite status i ažurnost. Uključite vreme najnovijeg događaja i vreme poslednje uspešne provere kod provajdera, kada su dostupni.

Pravila lokalne ažurnosti predstavljaju inženjersku odluku, a ne tvrdnju o učestalosti ažuriranja prevoznika. Izaberite ih na osnovu zahteva interfejsa, ograničenja provajdera, obima pošiljki i uočene korisnosti upita. Kupac koji više puta klikne na dugme za ažuriranje ne bi trebalo da stvori neograničen tok zahteva prema višem nivou.

Normalizujte odgovor bez izmišljanja ažurnosti

Vaša aplikacija može vraćati stabilan interni format čak i kada se strukture odgovora provajdera razlikuju. Ovaj ilustrativni objekat predstavlja ugovor vaše aplikacije, a ne stvarni payload provajdera:

{
  "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"
}

Popunite svaku vremensku oznaku samo kada je njeno značenje poznato. Vreme kada je vaš server primio odgovor pripada metapodacima upita; ne sme biti predstavljeno kao vreme kada se paket kretao. Ako provajder ne dostavlja vremensku oznaku ažuriranja provajdera, ostavite to polje izostavljeno ili postavljeno na null umesto da zamenite drugom vremenskom oznakom.

U korisničkom interfejsu razdvojite poruke: „Najnoviji događaj prevoznika“ opisuje aktivnost pošiljke, dok „Praćenje provereno“ opisuje aktivnost preuzimanja vaše aplikacije. Ta razlika sprečava da se nepromenjeno skeniranje prikaže kao novozabeleženo.

Sprečite da API upiti i webhook-ovi međusobno prepisuju podatke

Kada su oba mehanizma aktivna, isti događaj može stići putem upita i webhook-a. Takođe mogu završiti drugačijim redosledom od onog kojim su pokrenuti. Upit pokrenut prvi može se završiti nakon što je webhook već dostavio novije informacije.

Nemojte koristiti logiku „poslednji odgovor pobeđuje“. Najskorije primljeni payload nije nužno najnovije stanje pošiljke.

  • Delite jedan tok ažuriranja. Rezultate upita i payload-e webhook-ova šaljite kroz iste funkcije za proveru, normalizaciju i čuvanje.
  • Uklanjajte duplirane događaje. Prednost dajte dokumentovanom identifikatoru događaja. Ako ne postoji, napravite pažljivo definisan otisak na osnovu dostupnih polja, kao što su vreme događaja, status, lokacija i opis.
  • Koristite polja za redosled sa poznatim značenjem. Dokumentovana revizija ili sekvenca korisnija je od pretpostavke da vreme prijema predstavlja redosled događaja.
  • Čuvajte istoriju. Novoprimljeni događaj može popuniti istorijsku prazninu bez promene trenutnog sažetka pošiljke.
  • Dozvolite ispravke. Statusi nisu univerzalna linearna lestvica. Pratite dokumentovano ponašanje ispravki umesto da trajno odbacujete svaki prividni korak unazad.

Kada je redosled događaja neizvestan, sačuvajte originalni payload i njegovo poreklo radi istrage. Ne rešavajte nejasnoću izmišljanjem vremenske oznake događaja ili pretpostavkom da sve vremenske oznake prevoznika koriste istu vremensku zonu.

Različito obradite nedostajuće podatke i neuspešne zahteve

Prazan rezultat, nepromenjeni rezultat i neuspešan zahtev ne bi trebalo da proizvode istu poruku kupcu.

Upit je uspešan, ali se status nije promenio

Zadržite postojeći status pošiljke i ažurirajte vreme poslednjeg uspešnog upita. Nemojte generisati novi događaj pošiljke samo zato što je završena nova pretraga. Ako kupcu treba više detalja, prikažite postojeću istoriju događaja i objasnite da nije vraćen noviji događaj praćenja.

Pošiljka još nema informacije o praćenju

Proverite da li je potrebna registracija, da li su identifikator i prevoznik ispravni i kako provajder predstavlja prikupljanje na čekanju. Nedostatak događaja sam po sebi ne dokazuje da je broj za praćenje nevažeći ili da je paket izgubljen. Sačuvajte razliku koju provajder pravi između nepoznatog identifikatora, registrovane pošiljke koja čeka informacije i zahteva koji nije mogao biti obrađen.

Zahtev provajdera ističe ili nije uspešan

Ako imate prethodni važeći status, vratite ga uz jasno naznačeno da poslednja provera nije uspela. Ostavite ranije vreme uspešnog upita nepromenjenim. Mrežna greška nije izuzetak u dostavi i ne bi trebalo da promeni poslovni status paketa.

Za odgovarajuće privremene greške koristite ograničene ponovne pokušaje sa povratnim čekanjem i slučajnim odstupanjem. Nemojte stalno ponavljati pokušaje sa nevažećim akreditivima ili neispravnim zahtevima. Kada odgovor sadrži Retry-After, tumačite ga u skladu sa ugovorom provajdera i HTTP semantikom. HTTP specifikacija dozvoljava da ta vrednost bude izražena kao kašnjenje u sekundama ili kao HTTP datum.

Stiže više zahteva za istu pošiljku

Objedinite istovremene pretrage tako da mogu deliti jedan zahtev prema višem nivou. Ograničenja primenite po nalogu i pošiljci i sprečite da se automatski ponovni pokušaj umnoži kroz više slojeva aplikacije. Kada je grupno slanje podržano, pregledajte rezultat svake pošiljke umesto da celu grupu smatrate uspešnom samo zato što je HTTP zahtev završen.

Koristite anketiranje kao kontrolisani rezervni mehanizam

Bez webhook-ova, periodično anketiranje može održavati vašu bazu podataka ažurnom, ali zahteva jasnu operativnu politiku. Odredite koje pošiljke ostaju podobne, kako greške utiču na raspored i kada se rutinsko anketiranje zaustavlja.

Za većinu integracija, hibridni dizajn je razuman početak: webhook-ovi obrađuju pozadinske promene, upiti na zahtev služe interaktivnim zahtevima, a poslovi usklađivanja proveravaju zapise kojima je potrebna pažnja. Ovo je arhitektonska preporuka, a ne garancija da će smanjiti troškove za svaki nalog.

  • Dajte prednost aktivnim pošiljkama i zapisima sa nerešenim greškama pri preuzimanju.
  • Izbegavajte upite za svaku istorijsku pošiljku pri svakom zakazanom pokretanju.
  • Definišite kako se obrađuju završene pošiljke, uključujući period za ispravke koji vaše poslovanje zahteva.
  • Pratite koliko često upiti pronalaze zaista nove informacije.
  • Istražite probleme sa dostavom webhook-ova umesto da ih prikrivate sve češćim anketiranjem.

Pratite kašnjenje zahteva provajdera, neuspešne upite, odgovore o ograničenju brzine i razlike između podataka dobijenih upitom i zapisa popunjenih putem webhook-ova. Odvojeno pratite starost najnovijeg događaja prevoznika. Uspešni API odgovori mogu postojati istovremeno sa informacijama o praćenju koje se nisu promenile.

Testirajte tok rada pre objavljivanja

Uspešan zahtev je samo prvi test. Proverite situacije koje bi inače mogle stvoriti obmanjujuća ažuriranja statusa:

  • Webhook stiže dok je upit na zahtev još u toku.
  • Dve korisničke ili službene sesije istovremeno traže istu pošiljku.
  • Provajder vraća HTTP uspeh, ali prijavljuje grešku na nivou pošiljke.
  • Zahtev nije uspešan nakon što vaša aplikacija već poseduje važeće informacije o praćenju.
  • Događaju nedostaje vremenska zona ili sadrži nepoznatu šifru statusa.
  • Ispravka prevoznika menja prethodno prikazan rezultat.
  • Korisnik pokušava da pristupi pošiljci koja pripada drugom nalogu.

Kriterijum za objavljivanje treba da bude da aplikacija vraća najbolje poznate informacije o pošiljci, tačno objašnjava njihovu ažurnost i ne kvari te informacije kada zahtevi ne uspeju ili stignu van redosleda.

Česta pitanja

Da li upit API-ju primorava prevoznika da skenira ili ažurira paket?

Ne. Preuzimanje informacija o praćenju ne može izazvati fizičko skeniranje. Da li zahtev pokreće proveru na višem nivou zavisi od dokumentovane operacije. Čak i podržano osvežavanje može vratiti nepromenjene informacije ako prevoznik nema noviji događaj.

Mogu li koristiti API upite bez konfigurisanja webhook-ova?

Ako provajder podržava potreban tok upita, možete napraviti integraciju zasnovanu na zahtevima na zahtev ili anketiranju. Najpre potvrdite uslove registracije i upita. Vaša aplikacija će zatim biti odgovorna za odlučivanje kada da proveri podatke, kontrolu obima zahteva i otkrivanje promena.

Koliko često treba da proveravam status pošiljke?

Ne postoji univerzalni interval. Izaberite raspored koji odgovara ograničenjima provajdera, obimu vaših pošiljki i poslovnoj vrednosti ranijeg pronalaženja ažuriranja. Izmerite koliko često anketiranje vraća nove događaje, a zatim prilagodite raspored umesto da pretpostavite da češći zahtevi daju svežije podatke prevoznika.

Zašto API vraća informacije koje sam već primio putem webhook-a?

Obe putanje mogu izložiti isti osnovni zapis pošiljke. Webhook dostavlja obaveštenje, dok upit preuzima informacije na zahtev. Primanje istog događaja kroz oba kanala nije nužno greška; vaša aplikacija treba da ga deduplikuje.

Da li dugme za ažuriranje treba da kaže „Osveži praćenje“?

Samo ako taj izraz tačno opisuje operaciju. Ako dugme preuzima sačuvane podatke provajdera, jasnije je „Proveri ažuriranja“. Prikažite poslednji događaj prevoznika odvojeno od vremena kada je vaša aplikacija poslednji put uspešno završila proveru.

Izvori