6 kontrol na overenie, že najnovšie udalosti sledovania prepravcu boli synchronizované prostredníctvom vášho API
Ak chcete overiť, či vaše API synchronizovalo najnovšie udalosti sledovania od prepravcu, porovnajte identitu zásielky, časové pečiatky udalostí, podrobnosti udalostí, trasu doručenia, poradie udalostí a aktuálnosť s nezávislým zobrazením sledovania. Úspešná odpoveď API alebo potvrdenie webhooku potvrdzuje iba jednu časť tohto reťazca; sama osebe nedokazuje, že vaša aplikácia obsahuje najnovšiu udalosť od prepravcu.

Táto príručka je určená vývojárom a prevádzkovým tímom zodpovedným za získavanie údajov o sledovaní do systému správy objednávok, stránky určenej zákazníkom, nástroja podpory alebo pracovného postupu upozornení. Cieľom je zistiť, kde sa udalosť stratila alebo zmenila, a potom rozhodnúť, či zopakovať spracovanie, opraviť mapovanie alebo počkať na nové informácie od prepravcu.
Skôr než začnete: definujte, čo znamená „najnovšie“
Rozlišujte tri časové údaje: kedy podľa prepravcu udalosť nastala, kedy ju váš poskytovateľ sledovania prijal alebo sprístupnil a kedy ju vaša aplikácia uložila. Tieto časy sa môžu líšiť. Prepravca môže zverejniť skenovanie až po fyzickej udalosti, zatiaľ čo vaša integrácia ho môže spracovať ešte neskôr. Najnovšia udalosť podľa času výskytu preto nemusí byť záznamom prijatým ako posledný.
Pred skúmaním si zvoľte porovnávací bod. V ideálnom prípade použite stránku sledovania prepravcu alebo iný autorizovaný záznam poskytnutý prepravcom pre tú istú zásielku. Ak to nie je možné, porovnajte svoju aplikáciu s aktuálnou odpoveďou API poskytovateľa sledovania. Toto užšie porovnanie môže potvrdiť, či sa vaša aplikácia zhoduje s poskytovateľom; nemôže však potvrdiť, že poskytovateľ už má každý sken od prepravcu. Zaznamenajte si, kedy ste porovnanie vykonali, aby neskoršia aktualizácia nespôsobila, že skorší výsledok bude vyzerať nekonzistentne.
1. Potvrďte, že oba systémy odkazujú na tú istú zásielku
Začnite číslom zásielky, prepravcom a akýmkoľvek identifikátorom účtu alebo zásielky používaným vašou integráciou. Samotné čísla zásielok nemusia na riešenie problémov stačiť: číslo môže obsahovať preklep, môže byť priradené nesprávnemu prepravcovi alebo opätovne použité v internom zázname po úprave objednávky. Číslo objednávky a číslo zásielky slúžia na odlišné účely. Jedna objednávka môže obsahovať viac balíkov, takže kontrola najnovšieho stavu objednávky môže skryť zastaraný balík.
- Nájdite presné číslo zásielky a prepravcu odoslaného do tracking API.
- Potvrďte, ktorý interný záznam zásielky alebo balíka prijal odpoveď.
- Skontrolujte, či bola zásielka po registrácii nahradená, rozdelená, zrušená alebo znova priradená.
- Porovnajte prepravcu a číslo uvedené v zdrojovom zázname s údajmi vo vašej aplikácii.
Ak sa identifikátory nezhodujú, prestaňte tento rozdiel považovať za oneskorenie synchronizácie. Najprv opravte priradenie a potom zopakujte porovnanie udalostí. Do diagnostických protokolov ukladajte dostatok identifikátorov na sledovanie zásielky, ale nevkladajte do nich citlivé prihlasovacie údaje účtu.
2. Porovnávajte časy udalostí bez straty ich významu
Pri každej kandidátskej najnovšej udalosti zaznamenajte čas výskytu nahlásený prepravcom, uvedené časové pásmo alebo posun, ak je k dispozícii, a časy prijatia a uloženia vo vašej aplikácii. Časové pečiatky pri porovnávaní preveďte na spoločný časový základ, ale pôvodnú hodnotu si ponechajte. RFC 3339 definuje formát internetovej časovej pečiatky s explicitnými informáciami o posune; je užitočnou referenciou pri navrhovaní vlastných polí časových pečiatok. Nezaručuje však, že prepravca alebo poskytovateľ dodá časové pásmo pre každú udalosť.
Zobrazenie iba času, predpokladané miestne pásmo alebo analyzátor, ktorý potichu zahodí posun, môže presunúť udalosť na iný kalendárny deň alebo ju zaradiť do nesprávneho poradia. Ak zdroj uvádza nejednoznačný miestny čas, označte porovnanie ako neisté namiesto vytvárania presného okamihu v UTC. Rozlišujte tiež čas výskytu udalosti od času odpovede API: odpoveď získaná teraz môže oprávnene obsahovať udalosť, ktorá sa stala skôr.
Zapíšte si čas, keď ste skontrolovali zobrazenie prepravcu alebo poskytovateľa. Ak zdroj zverejnil nový sken až po vašej požiadavke API, rozdiel medzi týmito zobrazeniami nedokazuje, že skoršia požiadavka zlyhala.
3. Kontrolujte obsah udalosti, nielen hlavný stav
Porovnajte popis najnovšej udalosti, miesto, stav alebo kód prepravcu a všetky relevantné polia doručenia s nadradeným záznamom. Normalizovaný stav, napríklad „v preprave“, môže sumarizovať niekoľko odlišných skenov. Ak vaša aplikácia ukladá iba súhrn, môže vyzerať nezmenene, hoci prišla nová udalosť.
Ak to pravidlá spracovania údajov povoľujú, skontrolujte nespracovanú odpoveď API alebo uchované telo webhooku. Potom sledujte udalosť cez analýzu, mapovanie polí, uloženie a zobrazenie. Hľadajte polia null prepísané predvolenými hodnotami, neočakávané stavové kódy zaradené do všeobecnej kategórie, skrátený text alebo používateľské rozhranie, ktoré zobrazuje iba vybrané typy udalostí. Rozdiel v označení stavu sa líši od chýbajúcej udalosti: poukazuje skôr na transformačnú alebo zobrazovaciu logiku než na doručenie.
Doručenie neodvodzujte iba z toho, že miesto alebo stav znie ako konečný. Potvrďte konkrétnu udalosť a polia, od ktorých závisí váš pracovný postup. Naopak, nezmenený všeobecný stav nedokazuje zastavenie synchronizácie; novo prijatý sken môže byť priradený do rovnakej kategórie. Diagnostický záznam by mal uchovávať nadradenú udalosť aj hodnotu zobrazenú používateľom.
4. Sledujte, ako sa udalosť dostala do vašej aplikácie
Ak používate webhooky, skontrolujte protokol prijatia pre príslušnú zásielku a udalosť. Overte, že koncový bod požiadavku prijal, správa prešla validáciou a následné spracovanie sa dokončilo. Úspešná odpoveď HTTP z vášho koncového bodu nedokazuje, že neskorší pracovník frontu udalosť uložil. Ak je spracovanie asynchrónne, preskúmajte prichádzajúcu požiadavku aj výsledok úlohy.
Ak používate dotazovanie API, skontrolujte poslednú dokončenú požiadavku, identifikátor zásielky v tejto požiadavke, jej odpoveď a všetku stránkovaciu alebo načítaciu logiku, ktorú integrácia používa. Po úspešnej požiadavke môže stále nasledovať neúspešný zápis do databázy alebo načítanie zastaranej vyrovnávacej pamäte. Pomocou príslušnej dokumentácie poskytovateľa overte skutočné polia odpovede, požiadavky na overenie a správanie doručovania pre svoju integráciu namiesto predpokladu, že každé tracking API používa rovnakú zmluvu. Pri integrácii 17TRACK sú relevantnými východiskami jeho stránka Tracking API a dokumentácia API; overte zdokumentované správanie koncového bodu a metódy, ktoré používate.
Spracovanie udalostí nastavte tak, aby bolo bezpečné ho opakovať. Opakovanie by nemalo vytvárať duplicitné skeny, opakovane odosielať rovnaké upozornenie zákazníkovi ani nahradiť novší uložený stav starším obsahom. Vhodný kľúč duplicity závisí od polí, ktoré poskytovateľ skutočne dodáva. Otestujte zvolený kľúč na odlišných udalostiach, ktoré náhodou zdieľajú stav alebo časovú pečiatku; tieto udalosti by sa nemali spájať len preto, že vyzerajú podobne.
5. Overte pravidlá poradia a prechodov stavov
Zaznamenané udalosti zoraďte podľa jasne definovaného pravidla a potom skontrolujte výsledok. Mnohé aplikácie musia rozlišovať medzi „najnovšou udalosťou, ktorá nastala“ a „najnovšou udalosťou, ktorú sme prijali“. Oneskorený skorší sken môže prísť po novšom skene. Ak databáza jednoducho nastaví naposledy spracovanú správu ako aktuálny stav zásielky, tento oneskorený sken môže zobrazený stav posunúť späť.
Porovnajte uloženú históriu s nadradenou históriou, nielen jediné pole stavu. Zistite, či bol novo prijatý záznam pridaný, zahodený ako duplicita alebo povolený na aktualizáciu aktuálneho stavu. Skontrolujte každé pravidlo, ktoré dáva určitým udalostiam prednosť pred inými. Takéto pravidlo môže byť zámerné, ale nemalo by skrývať základnú udalosť ani naznačovať, že prepravca vrátil míľnik späť, keď aplikácia iba neskoro prijala starší sken.
Na praktický test vezmite zásielku s viac než jednou udalosťou a v neprodukčnom prostredí prehrajte jej správy v inom poradí príchodu. Overte, že história udalostí zostane zachovaná a že stav zobrazený zákazníkovi sa riadi zdokumentovaným pravidlom. Tým sa odhalia chyby poradia, ktoré bežný test v správnom poradí nedokáže odhaliť.
6. Merajte aktuálnosť a riešte nezrovnalosti
Nakoniec porovnajte, čo každá vrstva vedela v rovnakom okamihu pozorovania: zobrazenie prepravcu, odpoveď poskytovateľa sledovania, prichádzajúci webhook alebo výsledok dotazovania, záznam v databáze a výstup určený zákazníkovi. Označte prvú vrstvu, v ktorej očakávaná udalosť zmizne. Táto hranica je užitočnejšia než všeobecné hlásenie, že „sledovanie mešká“.
Merajte vek najnovšej udalosti nahlásenej prepravcom aj čas od poslednej úspešnej kontroly alebo prijatia údajov vašou integráciou. Odpovedajú na odlišné otázky. Balík nemusí mať nový sken prepravcu, hoci vaša integrácia funguje správne; prípadne môže prepravca zobrazovať nový sken, zatiaľ čo posledná úspešná požiadavka je stará. Používajte limity upozornení, ktoré zodpovedajú vašim prevádzkovým požiadavkám a pozorovanému správaniu. Nesľubujte zákazníkom pevný interval aktualizácie, ak ho vaše dohody s prepravcami a poskytovateľmi nepodporujú.
Vytvorte malý front na zosúladenie zásielok, ktorých záznamy sa líšia od zvoleného porovnávacieho zdroja. Zahrňte identifikátory, chýbajúcu alebo nezhodujúcu sa udalosť, relevantné časové pečiatky, prvú zlyhávajúcu vrstvu a ďalšiu akciu. Napríklad udalosť prítomná v odpovedi poskytovateľa, ale chýbajúca v databáze, vyžaduje skúmanie integrácie. Udalosť prítomná v databáze, ale chýbajúca na stránke sledovania, vyžaduje kontrolu zobrazenia alebo vyrovnávacej pamäte. Ak samotný prepravca nezobrazuje nový sken, ďalšia požiadavka API ho nemôže vytvoriť.
Prevádzkový test je jednoduchý: dokážete identifikovať tú istú zásielku, nájsť jej najnovšiu známu nadradenú udalosť a sledovať túto udalosť až po zobrazenie určené používateľovi bez zmeny jej významu? Ak nie, týchto šesť kontrol zúži problém na konkrétnu hranicu a poskytne tímu obhájiteľný ďalší krok.
Často kladené otázky
Znamená úspešná odpoveď webhooku, že najnovšia udalosť je synchronizovaná?
Nie. Ukazuje iba, že váš koncový bod vrátil úspešnú odpoveď na požiadavku. Potvrďte, že úspešne prebehla aj validácia, spracovanie vo fronte, uloženie do databázy a zobrazenie. Skontrolujte obsah požiadavky, aby ste zistili, ktorú udalosť obsahovala.
Prečo stránka prepravcu zobrazuje novší sken než moja odpoveď API?
Najprv potvrďte, že zobrazujete ten istý balík a že obe pozorovania boli vykonané v porovnateľnom čase. Zverejnenie udalosti prepravcom a jej prijatie alebo sprístupnenie poskytovateľom sledovania môže prebehnúť v odlišných časoch. Ak rozdiel pretrváva, použite dokumentáciu a proces podpory poskytovateľa na preskúmanie konkrétnej zásielky namiesto predpokladu záruky aktualizácie.
Mám na výber najnovšieho stavu použiť časovú pečiatku udalosti alebo čas, keď ju môj systém prijal?
Použite zdokumentované pravidlo vhodné pre váš pracovný postup a uchovajte obe hodnoty. Časová pečiatka udalosti opisuje, kedy k nahlásenej činnosti došlo; čas prijatia opisuje, kedy sa o nej váš systém dozvedel. Ani jedno pole samostatne nevyrieši každý prípad, najmä keď sú zdrojové časy nejednoznačné alebo skoršie skeny prídu neskoro.
Čo ak sa stav API nezmenil, ale zoznam udalostí obsahuje nový záznam?
Môže to byť očakávané, ak sa viaceré udalosti prepravcu mapujú na jeden normalizovaný stav. Porovnajte podrobnosti udalosti a overte, či vaša aplikácia nový záznam uložila a podľa potreby ho zobrazuje. Chýbajúcu udalosť a nezmenené súhrnné označenie považujte za odlišné problémy.
Zdroje
- 17TRACK Tracking API — produktová referencia pre integrácie tracking API.
- Dokumentácia 17TRACK API — referenčný bod na kontrolu príslušnej integračnej zmluvy.
- RFC 3339: Dátum a čas na internete: časové pečiatky — referencia formátu časovej pečiatky a posunu UTC.


