Skip to main content
DomůBlogPrůvodci6 kontrol pro ověření, že nejnovější události sledování zásilek přepravce byly synchronizovány prostřednictvím vašeho API

6 kontrol pro ověření, že nejnovější události sledování zásilek přepravce byly synchronizovány prostřednictvím vašeho API

17TRACK

Chcete-li ověřit, zda vaše API synchronizovalo nejnovější události sledování zásilky od dopravce, porovnejte s nezávislým pohledem na sledování identitu zásilky, časová razítka událostí, podrobnosti událostí, trasu doručení, pořadí událostí a aktuálnost dat. Úspěšná odpověď API nebo potvrzení webhooku potvrzuje pouze jednu část tohoto řetězce; sama o sobě nedokazuje, že vaše aplikace obsahuje nejnovější událost dopravce.

6 kontrol pro ověření synchronizace nejnovějších událostí sledování zásilky od dopravce

Tato příručka je určena vývojářům a provozním týmům odpovědným za načítání údajů o sledování do systému pro správu objednávek, stránky pro zákazníky, podpůrného nástroje nebo pracovního postupu upozornění. Cílem je zjistit, kde se událost ztratila nebo změnila, a následně rozhodnout, zda zpracování zopakovat, opravit mapování, nebo počkat na nové informace od dopravce.

Než začnete: definujte, co znamená „nejnovější“

Rozlišujte tři časové údaje: kdy dopravce uvádí, že k události došlo, kdy ji váš poskytovatel sledování přijal nebo zpřístupnil a kdy ji vaše aplikace uložila. Tyto časy se mohou lišit. Dopravce může sken zveřejnit až po fyzickém uskutečnění události, zatímco vaše integrace jej může zpracovat ještě později. Nejnovější událost podle času výskytu proto nemusí být záznamem přijatým jako poslední.

Před zahájením šetření si zvolte srovnávací bod. V ideálním případě použijte sledovací stránku dopravce nebo jiný autorizovaný záznam poskytnutý dopravcem pro stejnou zásilku. Pokud není k dispozici, porovnejte svou aplikaci s aktuální odpovědí API poskytovatele sledování. Toto užší srovnání může potvrdit, zda vaše aplikace odpovídá poskytovateli; nemůže však potvrdit, že poskytovatel již má každý sken dopravce. Zaznamenejte, kdy jste srovnání provedli, aby pozdější aktualizace nezpůsobila, že dřívější výsledek bude vypadat nekonzistentně.

1. Ověřte, že se oba systémy vztahují ke stejné zásilce

Začněte sledovacím číslem, dopravcem a případným identifikátorem účtu nebo zásilky používaným vaší integrací. Samotná sledovací čísla nemusí k řešení problémů stačit: číslo může obsahovat překlep, být spojeno s nesprávným dopravcem nebo být po úpravě objednávky znovu použito v interním záznamu. Číslo objednávky a sledovací číslo slouží také k různým účelům. Jedna objednávka může obsahovat více balíků, takže kontrola nejnovějšího stavu objednávky může skrýt zastaralý balík.

  • Vyhledejte přesné sledovací číslo a dopravce odeslané do API sledování.
  • Ověřte, který interní záznam zásilky nebo balíku obdržel odpověď.
  • Zkontrolujte, zda zásilka nebyla po registraci nahrazena, rozdělena, zrušena nebo znovu přiřazena.
  • Porovnejte dopravce a číslo uvedené ve zdrojovém záznamu s údaji zobrazenými ve vaší aplikaci.

Pokud se identifikátory neshodují, přestaňte tento rozdíl považovat za zpoždění synchronizace. Nejprve opravte přiřazení a poté porovnání událostí zopakujte. Do diagnostických protokolů ukládejte dostatek identifikátorů, aby bylo možné zásilku dohledat, ale nevkládejte do nich citlivé přihlašovací údaje k účtu.

2. Porovnávejte časy událostí, aniž byste ztratili jejich význam

U každé kandidátní nejnovější události zaznamenejte čas výskytu nahlášený dopravcem, uvedené časové pásmo nebo posun, pokud jsou k dispozici, a časy přijetí a uložení ve vaší aplikaci. Pro porovnání převeďte časová razítka na společný časový základ, ale zachovejte původní hodnotu. RFC 3339 definuje formát internetového časového razítka s explicitní informací o posunu; jde o užitečnou referenci při návrhu vlastních polí časových razítek. Nezaručuje však, že dopravce nebo poskytovatel dodává časové pásmo pro každou událost.

Zobrazení pouze času, předpokládané místní pásmo nebo analyzátor, který bez upozornění zahodí posun, může přesunout událost na jiný kalendářní den nebo ji zařadit do nesprávného pořadí. Pokud zdroj uvádí nejednoznačný místní čas, označte porovnání jako nejisté, místo abyste vymýšleli přesný okamžik v UTC. Rozlišujte také čas výskytu události od času odpovědi API: odpověď získaná nyní může oprávněně obsahovat událost, ke které došlo dříve.

Zapište si čas, kdy jste zkontrolovali pohled dopravce nebo poskytovatele. Pokud zdroj zveřejnil nový sken až po vašem požadavku API, rozdíl mezi oběma pohledy nedokazuje, že dřívější požadavek selhal.

3. Kontrolujte datovou část události, nejen hlavní stav

Porovnejte popis nejnovější události, místo, stav nebo kód dopravce a všechny relevantní údaje o doručení s nadřazeným záznamem. Normalizovaný stav, například „v přepravě“, může shrnovat několik odlišných skenů. Pokud vaše aplikace ukládá pouze souhrn, může se zdát, že se nic nezměnilo, i když dorazila nová událost.

Pokud to vaše pravidla pro nakládání s daty dovolují, prozkoumejte nezpracovanou odpověď API nebo uchované tělo webhooku. Poté sledujte událost při analýze, mapování polí, ukládání a prezentaci. Hledejte přepisování hodnot null výchozími hodnotami, neočekávané stavové kódy zařazené do obecné kategorie, zkrácený text nebo uživatelské rozhraní, které zobrazuje pouze vybrané typy událostí. Nesrovnalost štítku stavu se liší od chybějící události: ukazuje spíše na logiku transformace nebo zobrazení než na doručení.

Neusuzujte na doručení pouze proto, že místo nebo stav zní jako konečný. Ověřte konkrétní událost a pole, na kterých váš pracovní postup závisí. Naopak nezměněný stav na vysoké úrovni není důkazem, že se synchronizace zastavila; nově přijatý sken může být mapován do stejné kategorie. Diagnostický záznam by měl uchovávat jak událost z nadřazeného zdroje, tak hodnotu zobrazenou uživatelům.

4. Sledujte, jak se událost dostala do vaší aplikace

Pokud používáte webhooky, zkontrolujte protokol přijetí pro příslušnou zásilku a událost. Ověřte, že váš koncový bod požadavek přijal, že zpráva prošla validací a že následné zpracování bylo dokončeno. Úspěšná odpověď HTTP z vašeho koncového bodu nedokazuje, že pozdější pracovník fronty událost uložil. Pokud je zpracování asynchronní, prozkoumejte příchozí požadavek i výsledek úlohy.

Pokud dotazujete API, zkontrolujte poslední dokončený požadavek, identifikátor zásilky v tomto požadavku, jeho odpověď a veškerou logiku stránkování nebo získávání, kterou vaše integrace používá. Po úspěšném požadavku může stále následovat neúspěšný zápis do databáze nebo načtení zastaralých dat z mezipaměti. Pomocí příslušné dokumentace poskytovatele ověřte skutečná pole odpovědi, požadavky na autentizaci a chování doručování pro vaši integraci, místo abyste předpokládali, že každé API sledování se řídí stejnou smlouvou. U integrace 17TRACK jsou relevantními výchozími body její stránka Tracking API a dokumentace API; ověřte zdokumentované chování koncového bodu a metody, které používáte.

Zpracování událostí navrhněte tak, aby bylo bezpečné je opakovat. Opakování by nemělo vytvářet duplicitní skeny, opakovaně odesílat stejné upozornění zákazníkovi ani nahrazovat novější uložený stav starší datovou částí. Vhodný klíč duplicity závisí na polích, která váš poskytovatel skutečně dodává. Otestujte zvolený klíč na odlišných událostech, které náhodou sdílejí stav nebo časové razítko; tyto události by neměly být sloučeny jen proto, že vypadají podobně.

5. Ověřte pravidla řazení a přechodů stavů

Zaznamenané události seřaďte podle jasně definovaného pravidla a poté výsledek prozkoumejte. Mnoho aplikací musí rozlišovat mezi „nejnovější událostí, ke které došlo“ a „nejnovější událostí, kterou jsme přijali“. Zpožděný dřívější sken může dorazit po novějším skenu. Pokud databáze jednoduše nastaví jako aktuální stav zásilky zprávu zpracovanou naposledy, může tento zpožděný sken posunout zobrazený stav zpět.

Porovnávejte uloženou historii s historií nadřazeného zdroje, nikoli pouze jediné stavové pole. Zjistěte, zda byl nově přijatý záznam přidán, zamítnut jako duplicita nebo povolen k aktualizaci aktuálního stavu. Zkontrolujte všechna pravidla, která některým událostem přidělují přednost před jinými. Takové pravidlo může být záměrné, nemělo by však skrývat podkladovou událost ani naznačovat, že dopravce zrušil milník, když aplikace pouze pozdě přijala starší sken.

Pro praktický test vezměte zásilku s více než jednou událostí a v neprodukčním prostředí přehrajte její zprávy v jiném pořadí příchodu. Ověřte, že historie událostí zůstane neporušená a že stav zobrazený zákazníkovi odpovídá zdokumentovanému pravidlu. Tím odhalíte chyby v pořadí, které běžný test v pořadí příchodu nedokáže odhalit.

6. Měřte aktuálnost a řešte výjimky

Nakonec porovnejte, co každá vrstva věděla ve stejném okamžiku pozorování: pohled dopravce, odpověď poskytovatele sledování, příchozí webhook nebo výsledek dotazu, záznam v databázi a výstup pro zákazníka. Označte první vrstvu, ve které očekávaná událost zmizí. Tato hranice je užitečnější než obecné oznámení, že „sledování je opožděné“.

Měřte jak stáří poslední události nahlášené dopravcem, tak dobu od poslední úspěšné kontroly nebo přijetí dat vaší integrací. Odpovídají na různé otázky. Balík nemusí mít nový sken dopravce, i když je vaše integrace v pořádku; alternativně může dopravce zobrazovat nový sken, zatímco váš poslední úspěšný požadavek je starý. Používejte prahové hodnoty upozornění, které odpovídají vašim provozním požadavkům a pozorovanému chování. Neslibujte zákazníkům pevný interval aktualizací, pokud jej vaše dohody s dopravcem a poskytovatelem nepodporují.

Vytvořte malou frontu pro sjednocování zásilek, jejichž záznamy se liší od zvoleného srovnávacího zdroje. Zahrňte identifikátory, chybějící nebo neshodující se událost, relevantní časová razítka, první neúspěšnou vrstvu a další krok. Událost přítomná v odpovědi poskytovatele, ale chybějící v databázi, například vyžaduje prošetření integrace. Událost přítomná v databázi, ale chybějící na stránce sledování, vyžaduje kontrolu zobrazení nebo mezipaměti. Pokud samotný dopravce nezobrazuje nový sken, další požadavek API jej nemůže vytvořit.

Provozní test je jednoduchý: dokážete identifikovat stejnou zásilku, najít její poslední známou událost v nadřazeném zdroji a sledovat tuto událost až k pohledu zobrazenému uživateli, aniž by se změnil její význam? Pokud ne, šest kontrol zúží problém na konkrétní hranici a poskytne vašemu týmu obhajitelný další krok.

Časté dotazy

Znamená úspěšná odpověď webhooku, že je nejnovější událost synchronizována?

Ne. Ukazuje, že váš koncový bod vrátil na požadavek úspěšnou odpověď. Ověřte, že úspěšně proběhla také validace, zpracování ve frontě, uložení do databáze a zobrazení. Zkontrolujte datovou část, abyste zjistili, kterou událost požadavek obsahoval.

Proč stránka dopravce zobrazuje novější sken než moje odpověď API?

Nejprve ověřte, že sledujete stejný balík a že obě pozorování proběhla ve srovnatelných časech. Zveřejnění události dopravcem a její přijetí nebo zpřístupnění poskytovatelem sledování může proběhnout v různých časech. Pokud rozdíl přetrvává, použijte dokumentaci a proces podpory poskytovatele k prošetření konkrétní zásilky, místo abyste předpokládali záruku aktualizace.

Mám při výběru nejnovějšího stavu použít časové razítko události, nebo čas, kdy jej můj systém přijal?

Použijte zdokumentované pravidlo vhodné pro váš pracovní postup a uchovávejte obě hodnoty. Časové razítko události popisuje, kdy k nahlášené aktivitě došlo; čas přijetí popisuje, kdy se o ní váš systém dozvěděl. Ani jedno pole samo o sobě neřeší každý případ, zejména když jsou zdrojové časy nejednoznačné nebo pozdě dorazí starší skeny.

Co když se stav API nezměnil, ale seznam událostí obsahuje nový záznam?

To může být očekávané, pokud je více událostí dopravce mapováno na jeden normalizovaný stav. Porovnejte podrobnosti událostí a ověřte, že vaše aplikace nový záznam uložila a případně jej zobrazuje. Chybějící událost a nezměněný souhrnný štítek považujte za odlišné problémy.

Zdroje