6 provera za potvrdu da su najnoviji događaji praćenja prevoznika sinhronizovani putem vašeg API-ja
Da biste proverili da li je vaš API sinhronizovao najnovije događaje praćenja pošiljke, proverite identitet pošiljke, vremenske oznake događaja, detalje događaja, putanju isporuke, redosled događaja i ažurnost u odnosu na nezavisan prikaz praćenja. Uspešan API odgovor ili potvrda prijema webhook-a potvrđuju samo jedan deo tog lanca; sami po sebi ne dokazuju da vaša aplikacija ima najnoviji događaj prevoznika.

Ovaj vodič je namenjen programerima i operativnim timovima odgovornim za unos podataka o praćenju u sistem za upravljanje porudžbinama, stranicu namenjenu korisnicima, alat za podršku ili tok rada za slanje upozorenja. Cilj je da se utvrdi gde je događaj nestao ili izmenjen, a zatim odluči da li treba ponoviti obradu, ispraviti mapiranje ili sačekati nove informacije od prevoznika.
Pre nego što počnete: definišite šta znači najnovije
Razlikujte tri vremena: kada prevoznik navodi da se događaj desio, kada ga je vaš provajder za praćenje primio ili prikazao i kada ga je vaša aplikacija sačuvala. Ta vremena mogu da se razlikuju. Prevoznik može objaviti skeniranje nakon fizičkog događaja, dok vaša integracija može da ga obradi još kasnije. Zato najnoviji događaj prema vremenu nastanka nije nužno i zapis koji je najskorije primljen.
Pre istrage odredite tačku poređenja. U idealnom slučaju koristite stranicu za praćenje prevoznika ili drugi ovlašćeni zapis koji je prevoznik obezbedio za istu pošiljku. Ako to nije moguće, uporedite svoju aplikaciju sa trenutnim API odgovorom provajdera za praćenje. Ovo uže poređenje može pokazati da li se vaša aplikacija podudara sa provajderom, ali ne može potvrditi da provajder već ima svako skeniranje prevoznika. Zabeležite kada ste izvršili poređenje kako kasnije ažuriranje ne bi učinilo raniji rezultat nedoslednim.
1. Potvrdite da se oba sistema odnose na istu pošiljku
Počnite od broja za praćenje, prevoznika i svih naloga ili identifikatora pošiljke koje vaša integracija koristi. Sam broj za praćenje možda nije dovoljan za rešavanje problema: broj može biti unet sa greškom, povezan sa pogrešnim prevoznikom ili ponovo upotrebljen u internom zapisu nakon izmene porudžbine. Broj porudžbine i broj za praćenje takođe imaju različite namene. Jedna porudžbina može imati više paketa, pa provera najnovijeg statusa porudžbine može prikriti zastareli paket.
- Pronađite tačan broj za praćenje i prevoznika prosleđene API-ju za praćenje.
- Potvrdite koji je interni zapis pošiljke ili paketa primio odgovor.
- Proverite da li je pošiljka nakon registracije zamenjena, podeljena, otkazana ili ponovo povezana.
- Uporedite prevoznika i broj prikazane u izvornom zapisu sa onima prikazanim u vašoj aplikaciji.
Ako se identifikatori ne podudaraju, prestanite da razliku tretirate kao kašnjenje sinhronizacije. Najpre ispravite povezivanje, a zatim ponovite poređenje događaja. U dijagnostičkim zapisima čuvajte dovoljno identifikatora za praćenje pošiljke, ali u njih ne unosite osetljive akreditive naloga.
2. Uporedite vremena događaja ne gubeći njihovo značenje
Za svaki kandidat za najnoviji događaj zabeležite vreme nastanka koje je prijavio prevoznik, njegovu navedenu vremensku zonu ili pomak ako je dostupan, kao i vreme prijema i čuvanja u vašoj aplikaciji. Pretvorite vremenske oznake u zajedničku vremensku osnovu radi poređenja, ali zadržite izvornu vrednost. RFC 3339 definiše format internet vremenske oznake sa eksplicitnim informacijama o pomaku; predstavlja korisnu referencu pri projektovanju sopstvenih polja za vremenske oznake. On ne garantuje da prevoznik ili provajder za svaki događaj dostavlja vremensku zonu.
Prikaz koji sadrži samo vreme, pretpostavljena lokalna zona ili parser koji neprimetno odbacuje pomak mogu pomeriti događaj na drugi kalendarski dan ili ga postaviti u pogrešan redosled. Kada izvor daje dvosmisleno lokalno vreme, označite poređenje kao neizvesno umesto da izmišljate precizan UTC trenutak. Takođe razlikujte vreme nastanka događaja od vremena API odgovora: odgovor preuzet sada legitimno može sadržati događaj koji se desio ranije.
Zapišite vreme kada ste proverili prikaz prevoznika ili provajdera. Ako je izvor objavio novo skeniranje nakon vašeg API zahteva, razlika između dva prikaza ne dokazuje da je raniji zahtev neuspešan.
3. Proverite sadržaj događaja, a ne samo glavni status
Uporedite opis najnovijeg događaja, lokaciju, status ili šifru prevoznika i sva relevantna polja isporuke sa zapisom iz izvora. Normalizovani status kao što je „u tranzitu“ može sažeti nekoliko različitih skeniranja. Ako vaša aplikacija čuva samo sažetak, može izgledati nepromenjeno iako je stigao novi događaj.
Pregledajte sirovi API odgovor ili sačuvano telo webhook-a tamo gde vaša pravila za rukovanje podacima to dozvoljavaju. Zatim pratite događaj kroz parsiranje, mapiranje polja, čuvanje i prikaz. Potražite polja null koja su zamenjena podrazumevanim vrednostima, neočekivane šifre statusa svrstane u opštu kategoriju, skraćen tekst ili korisnički interfejs koji prikazuje samo odabrane vrste događaja. Neslaganje oznake statusa razlikuje se od nedostajućeg događaja: ono ukazuje na logiku transformacije ili prikaza, a ne na isporuku.
Ne zaključujte da je isporuka završena samo zato što lokacija ili status zvuče konačno. Potvrdite konkretan događaj i polja na kojima se vaš tok rada zasniva. Obrnuto, nepromenjen status višeg nivoa nije dokaz da je sinhronizacija prekinuta; novo skeniranje može biti mapirano u istu kategoriju. Dijagnostički zapis treba da sačuva i događaj iz izvora i vrednost prikazanu korisnicima.
4. Pratite kako je događaj stigao do vaše aplikacije
Ako koristite webhook-ove, proverite zapis prijema za relevantnu pošiljku i događaj. Potvrdite da je vaša krajnja tačka prihvatila zahtev, da je poruka prošla validaciju i da je naknadna obrada završena. HTTP uspešan odgovor vaše krajnje tačke ne dokazuje da je kasniji radnik reda sačuvao događaj. Ako je obrada asinhrona, pregledajte i ulazni zahtev i ishod zadatka.
Ako pozivate API periodično, proverite poslednji završen zahtev, identifikator pošiljke u tom zahtevu, njegov odgovor i svu logiku paginacije ili preuzimanja koju vaša integracija koristi. Nakon uspešnog zahteva i dalje može uslediti neuspešno upisivanje u bazu ili čitanje zastarelog keša. Koristite odgovarajuću dokumentaciju provajdera da proverite stvarna polja odgovora, zahteve za autentifikaciju i ponašanje isporuke za svoju integraciju, umesto da pretpostavite da svaki API za praćenje koristi isti ugovor. Za integraciju sa 17TRACK, relevantne početne tačke su njegova stranica Tracking API i API dokumentacija; potvrdite dokumentovano ponašanje krajnje tačke i metode koju koristite.
Obezbedite da obrada događaja može bezbedno da se ponovi. Ponovljeni pokušaj ne sme da kreira duplikate skeniranja, više puta pošalje isto obaveštenje korisniku ili zameni novije sačuvano stanje starijim sadržajem. Odgovarajući ključ duplikata zavisi od polja koja vaš provajder zaista dostavlja. Testirajte izabrani ključ na različitim događajima koji slučajno dele status ili vremensku oznaku; takvi događaji ne smeju biti spojeni samo zato što izgledaju slično.
5. Proverite pravila redosleda i prelaza stanja
Poređajte zabeležene događaje prema jasno definisanom pravilu, a zatim pregledajte rezultat. Mnoge aplikacije moraju da razlikuju „najnoviji događaj koji se desio“ od „najnovijeg događaja koji smo primili“. Zakasnelo ranije skeniranje može stići nakon novijeg skeniranja. Ako vaša baza podataka jednostavno postavlja poslednju obrađenu poruku kao trenutno stanje pošiljke, to zakasnelo skeniranje može vratiti prikazani status unazad.
Uporedite sačuvanu istoriju sa istorijom iz izvora, a ne samo jedno polje statusa. Proverite da li je novoprimljeni zapis dodat, odbačen kao duplikat ili mu je dozvoljeno da ažurira trenutno stanje. Proverite svako pravilo koje nekim događajima daje prednost u odnosu na druge. Takvo pravilo može biti namerno, ali ne sme sakriti osnovni događaj niti sugerisati da je prevoznik poništio prekretnicu kada je aplikacija samo kasno primila starije skeniranje.
Za praktičan test uzmite pošiljku sa više od jednog događaja i ponovo reprodukujte njene poruke drugačijim redosledom prijema u neproduktivnom okruženju. Potvrdite da istorija događaja ostaje potpuna i da status namenjen korisnicima prati dokumentovano pravilo. Tako ćete otkriti greške u redosledu koje uobičajeni test sa pravilnim redosledom ne može da pokaže.
6. Izmerite ažurnost i uskladite izuzetke
Na kraju uporedite šta je svaki sloj znao u istoj tački posmatranja: prikaz prevoznika, odgovor provajdera za praćenje, ulazni webhook ili rezultat poziva, zapis u bazi i izlaz namenjen korisnicima. Označite prvi sloj na kojem očekivani događaj nestaje. Ta granica je korisnija od opšteg izveštaja da „praćenje kasni“.
Izmerite i starost najnovijeg događaja koji je prijavio prevoznik i vreme od kada je vaša integracija poslednji put uspešno proverila ili primila podatke. Oni odgovaraju na različita pitanja. Paket možda nema novo skeniranje prevoznika iako je vaša integracija ispravna; alternativno, prevoznik može prikazivati novo skeniranje dok je vaš poslednji uspešni zahtev star. Koristite pragove upozorenja koji odgovaraju vašim operativnim zahtevima i ponašanju koje ste uočili. Ne obećavajte korisnicima fiksni interval ažuriranja ako ga vaši aranžmani sa prevoznikom i provajderom ne podržavaju.
Napravite mali red za usklađivanje pošiljki čiji se zapisi razlikuju od izabranog izvora poređenja. Uključite identifikatore, nedostajući ili neusaglašeni događaj, relevantne vremenske oznake, prvi sloj koji je otkazao i sledeću radnju. Na primer, događaj prisutan u odgovoru provajdera, ali odsutan iz vaše baze, zahteva istragu integracije. Događaj prisutan u vašoj bazi, ali odsutan sa stranice za praćenje, zahteva proveru prikaza ili keširanja. Ako sam prevoznik ne prikazuje novo skeniranje, još jedan API zahtev ne može da ga proizvede.
Operativni test je jednostavan: možete li identifikovati istu pošiljku, pronaći njen poslednji poznati događaj iz izvora i pratiti taj događaj sve do prikaza namenjenog korisniku, a da mu ne promenite značenje? Ako ne možete, šest provera sužavaju problem na konkretnu granicu i vašem timu daju opravdan sledeći korak.
Česta pitanja
Da li uspešan odgovor webhook-a znači da je najnoviji događaj sinhronizovan?
Ne. On pokazuje da je vaša krajnja tačka vratila uspešan odgovor na zahtev. Potvrdite da su validacija, obrada reda, čuvanje u bazi i prikaz takođe uspešni. Proverite sadržaj da biste utvrdili koji je događaj zahtev sadržao.
Zašto stranica prevoznika prikazuje novije skeniranje od mog API odgovora?
Najpre potvrdite da gledate isti paket i da su oba posmatranja izvršena u približno uporedivo vreme. Objavljivanje prevoznika i prijem ili prikaz događaja kod provajdera za praćenje mogu se desiti u različitim trenucima. Ako razlika ostane, koristite dokumentaciju i proces podrške provajdera da istražite konkretnu pošiljku, umesto da pretpostavite da postoji garancija ažuriranja.
Da li za izbor najnovijeg statusa treba da koristim vremensku oznaku događaja ili vreme kada ga je moj sistem primio?
Koristite dokumentovano pravilo koje odgovara vašem toku rada i sačuvajte obe vrednosti. Vremenska oznaka događaja opisuje kada se prijavljena aktivnost dogodila; vreme prijema opisuje kada je vaš sistem saznao za nju. Nijedno polje samo po sebi ne rešava svaki slučaj, naročito kada su vremena iz izvora dvosmislena ili kada ranija skeniranja stižu sa zakašnjenjem.
Šta ako je API status nepromenjen, ali lista događaja ima novi unos?
To može biti očekivano ako se više događaja prevoznika mapira na jedan normalizovani status. Uporedite detalje događaja i proverite da li je vaša aplikacija sačuvala i prikazala novi unos tamo gde je potrebno. Nedostajući događaj i nepromenjena sažeta oznaka statusa tretirajte kao različite probleme.
Izvori
- 17TRACK Tracking API — referenca proizvoda za integracije API-ja za praćenje.
- 17TRACK API documentation — referentna tačka za proveru odgovarajućeg ugovora integracije.
- RFC 3339: Date and Time on the Internet: Timestamps — referenca za format vremenskih oznaka i UTC pomaka.


