Skip to main content
DomůBlogPrůvodciJak získat nejnovější stav zásilky prostřednictvím API bez čekání na webhook

Jak získat nejnovější stav zásilky prostřednictvím API bez čekání na webhook

17TRACK

Chcete-li získat nejnovější dostupný stav zásilky bez čekání na webhook, odešlete ověřený požadavek do rozhraní API vašeho poskytovatele pro dotazy na zásilky. Pomocí odpovědi ihned aktualizujte svou aplikaci a poté ponechte webhooky povolené pro následné změny. Důležitý rozdíl spočívá v tom, že dotaz obvykle načte nejnovější uložené informace o sledování od poskytovatele; nemusí nutně spustit novou kontrolu u přepravce.

Jak získat nejnovější stav zásilky prostřednictvím API bez čekání

Tento přístup je užitečný, když zákazník otevře stránku objednávky, pracovník podpory potřebuje aktualizaci nebo váš systém potřebuje obnovit stav po zmeškaném oznámení. Spolehlivá implementace kombinuje dotazy na vyžádání, jasné indikátory aktuálnosti a ochranu před duplicitními nebo časově neuspořádanými aktualizacemi.

Rozhodněte, co znamená „nejnovější stav zásilky“

Před výběrem koncového bodu rozlišujte mezi třemi operacemi, které mohou znít podobně, ale poskytují odlišné výsledky.

OperaceCo provádíCo nepotvrzuje
Čtení vlastní databázeVrátí informace o sledování, které vaše aplikace již obsahuje.Zda poskytovatel obdržel novější aktualizaci.
Dotaz na API pro sledováníNačte informace dostupné prostřednictvím dotazovací operace poskytovatele.Zda během tohoto požadavku proběhla nová kontrola u přepravce.
Požadavek na aktualizaci sledováníPožádá o další kontrolu u nadřazeného zdroje, pokud poskytovatel tuto operaci nabízí.Že přepravce zaznamenal nové skenování nebo že aktualizace proběhne synchronně.

Dotaz použijte, když potřebujete odpověď ihned. Operaci aktualizace zkoumejte pouze tehdy, když potřebujete, aby se poskytovatel pokusil o další kontrolu u nadřazeného zdroje. Nepředpokládejte, že přidání parametru pro obejití mezipaměti, opakování požadavku nebo odeslání hlavičky HTTP cache-control přiměje přepravce poskytnout nové informace.

Viditelnost zásilky má několik fází: přepravce zaznamená událost, poskytovatel sledování ji získá a vaše aplikace ji obdrží nebo načte. Přímý požadavek API může obejít čekání na doručení oznámení, ale nemůže odstranit zpoždění v dřívějších částech tohoto řetězce.

Před psaním kódu zkontrolujte specifikaci dotazu

Vývojář integrující službu sledování odpovídá za tento pracovní postup. Začněte aktuální dokumentací poskytovatele, nikoli koncovým bodem zkopírovaným ze starého příkladu integrace. Ověřte tyto podrobnosti:

  • Identita zásilky: Přijímá dotaz sledovací číslo, interní ID zásilky nebo sledovací číslo v kombinaci s identifikátorem přepravce?
  • Požadavky na registraci: Musí být zásilka zaregistrována, než se na ni lze dotázat?
  • Ověření: Která hlavička nebo mechanismus ověření je vyžadován?
  • Význam odpovědi: Vrací operace uložené informace, zahajuje získávání údajů nebo vrací úlohu, jejíž stav je třeba později ověřit?
  • Zpracování výsledku: Může úspěšná odpověď HTTP obsahovat selhání na úrovni zásilky nebo výsledek ve stavu čekání?
  • Omezení používání: Jaké limity rychlosti, dávkové limity a omezení specifická pro účet platí?
  • Údaje o aktuálnosti: Která časová razítka představují události přepravce, aktualizace poskytovatele a vytvoření odpovědi?

Pro integraci se službou 17TRACK je relevantním produktem Tracking API, nikoli spotřebitelská stránka sledování nebo sledovací rozhraní obchodu. Pomocí oficiální dokumentace API ověřte operaci dotazu na informace o sledování, ověřování, pole požadavku a strukturu odpovědi pro svou integraci. Dotazy a zpracování webhooků považujte za oddělené aplikační cesty, které aktualizují stejný záznam zásilky.

Vyhněte se pevnému zakódování předpokladů o chování aktualizace nebo frekvenci dotazů. Tyto podrobnosti musí odpovídat operaci a podmínkám služby, které skutečně používáte.

Vytvořte vyhledávání na vyžádání prostřednictvím backendu

Praktickým návrhem je vystavit v rámci vlastní aplikace ověřený koncový bod. Prohlížeč požádá tento koncový bod o aktualizaci zásilky; server zkontroluje oprávnění, rozhodne, zda je dotaz na poskytovatele nutný, a vrátí normalizovaný výsledek.

Následující trasa je příkladem koncového bodu, který byste vytvořili ve své aplikaci. Nejde o koncový bod 17TRACK ani o specifikaci požadavku poskytovatele.

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

Identifikátor objednávky použijte k vyhledání zásilky na serveru. Nedovolte volajícímu načíst historii sledování jiného zákazníka pouhou náhradou sledovacího čísla v požadavku. Přihlašovací údaje k API poskytovatele uchovávejte na backendu, nikoli v JavaScriptu prohlížeče nebo v balíčku mobilní aplikace.

Pracovní postup požadavku, který můžete implementovat

  1. Ověřte oprávnění. Potvrďte, že zákazník nebo pracovník smí zobrazit objednávku.
  2. Vyřešte zásilku. Načtěte uložený identifikátor sledování a případně informace o přepravci.
  3. Zkontrolujte místní aktuálnost. Pokud již existuje nedávný úspěšný dotaz, znovu jej použijte podle zásad aktuálnosti aplikace.
  4. V případě potřeby se dotázejte poskytovatele. Použijte zdokumentovanou operaci a omezený časový limit požadavku.
  5. Ověřte výsledek. Zkontrolujte výsledek HTTP i výsledek na úrovni zásilky.
  6. Sloučte informace. Použijte stejná pravidla normalizace a odsouhlasení jako u událostí z webhooků.
  7. Vraťte stav a aktuálnost. Pokud jsou k dispozici, uveďte čas nejnovější události a čas poslední úspěšné kontroly u poskytovatele.

Zásady místní aktuálnosti jsou technickým rozhodnutím, nikoli tvrzením o frekvenci aktualizací přepravce. Zvolte je podle požadavků rozhraní, limitů poskytovatele, objemu zásilek a pozorované užitečnosti dotazů. Zákazník, který opakovaně kliká na tlačítko aktualizace, by neměl vytvářet neomezený proud požadavků k nadřazenému zdroji.

Normalizujte odpověď, aniž byste vytvářeli neexistující aktuálnost

Vaše aplikace může vracet stabilní interní formát, i když se struktury odpovědí poskytovatelů liší. Tento ilustrační objekt je vlastní smlouvou vaší aplikace, nikoli skutečným datovým objektem poskytovatele:

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

Každé časové razítko vyplňte pouze tehdy, když znáte jeho význam. Čas, kdy váš server obdržel odpověď, patří do metadat dotazu; nesmí být prezentován jako čas pohybu zásilky. Pokud poskytovatel neposkytuje časové razítko aktualizace poskytovatele, ponechte toto pole prázdné nebo null, místo abyste dosadili jiné časové razítko.

V zákaznickém rozhraní oddělte zprávy: „Nejnovější událost přepravce“ popisuje aktivitu zásilky, zatímco „Sledování zkontrolováno“ popisuje aktivitu aplikace při načítání údajů. Toto rozlišení zabrání tomu, aby se nezměněné skenování zobrazilo jako nově zaznamenané.

Zabraňte vzájemnému přepisování dotazů API a webhooků

Jakmile jsou aktivní oba mechanismy, může stejná událost dorazit prostřednictvím dotazu i webhooku. Mohou také skončit v jiném pořadí, než byly spuštěny. Dotaz spuštěný jako první může být dokončen až poté, co webhook již poskytl novější informace.

Nepoužívejte logiku „vyhrává poslední odpověď“. Naposledy přijatý datový obsah nemusí představovat nejnovější stav zásilky.

  • Sdílejte jeden kanál aktualizací. Výsledky dotazů a datové obsahy webhooků posílejte prostřednictvím stejných funkcí pro ověření, normalizaci a ukládání.
  • Odstraňujte duplicity událostí. Upřednostněte zdokumentovaný identifikátor události. Pokud neexistuje, vytvořte pečlivě definovaný otisk z dostupných polí, jako jsou čas události, stav, místo a popis.
  • Používejte řadicí pole se známou sémantikou. Zdokumentovaná revize nebo sekvence je užitečnější než předpoklad, že čas přijetí představuje pořadí událostí.
  • Uchovávejte historii. Nově přijatá událost může doplnit historickou mezeru, aniž by změnila aktuální souhrn zásilky.
  • Umožněte opravy. Stavy netvoří univerzální lineární žebříček. Řiďte se zdokumentovaným chováním oprav namísto trvalého odmítání každého zdánlivého zpětného přechodu.

Pokud je pořadí událostí nejisté, uchovejte původní datový obsah a jeho původ pro další šetření. Neřešte nejednoznačnost vytvořením časového razítka události ani předpokladem, že všechna časová razítka přepravce používají stejné časové pásmo.

Rozlišujte chybějící data a neúspěšné požadavky

Prázdný výsledek, nezměněný výsledek a neúspěšný požadavek by neměly vést ke stejné zprávě pro zákazníka.

Dotaz proběhne úspěšně, ale stav se nezměnil

Ponechte stávající stav zásilky a aktualizujte čas posledního úspěšného dotazu. Nevytvářejte novou událost zásilky jen proto, že bylo dokončeno další vyhledávání. Pokud zákazník potřebuje více podrobností, zobrazte stávající historii událostí a vysvětlete, že nebyla vrácena žádná novější událost sledování.

Zásilka zatím nemá žádné informace o sledování

Ověřte, zda je vyžadována registrace, zda jsou identifikátor a přepravce správní a jak poskytovatel reprezentuje čekající získávání údajů. Absence událostí sama o sobě nedokazuje, že sledovací číslo je neplatné nebo že se zásilka ztratila. Zachovejte rozlišení poskytovatele mezi neznámým identifikátorem, zaregistrovanou zásilkou čekající na informace a požadavkem, který nebylo možné zpracovat.

Požadavek poskytovateli vyprší nebo selže

Pokud máte předchozí platný stav, vraťte jej s výslovným uvedením, že nejnovější kontrola nebyla úspěšná. Časové razítko předchozího úspěšného dotazu ponechte beze změny. Síťová chyba není výjimkou při doručení a neměla by změnit obchodní stav zásilky.

Pro vhodná dočasná selhání používejte omezené opakování s postupným prodlužováním prodlevy a náhodným rozptylem. Neopakujte neustále požadavky s neplatnými přihlašovacími údaji nebo nesprávným formátem. Pokud odpověď obsahuje Retry-After, interpretujte ji podle smlouvy poskytovatele a sémantiky HTTP. Specifikace HTTP umožňuje vyjádřit tuto hodnotu jako prodlevu v sekundách nebo jako datum HTTP.

Pro stejnou zásilku dorazí více požadavků

Sloučte souběžná vyhledávání, aby mohla sdílet jeden požadavek k nadřazenému zdroji. Uplatňujte limity podle účtu a zásilky a zabraňte tomu, aby se automatické opakování násobilo v několika aplikačních vrstvách. Pokud je podporováno dávkové zpracování, zkontrolujte výsledek každé zásilky, místo abyste celou dávku považovali za úspěšnou jen proto, že byl dokončen požadavek HTTP.

Používejte dotazování jako řízenou záložní možnost

Bez webhooků může plánované dotazování udržovat databázi aktuální, ale vyžaduje výslovná provozní pravidla. Rozhodněte, které zásilky zůstanou způsobilé, jak selhání ovlivní plán a kdy se běžné dotazování zastaví.

Pro většinu integrací je hybridní návrh rozumným výchozím bodem: webhooky zpracovávají změny na pozadí, dotazy na vyžádání obsluhují interaktivní požadavky a úlohy odsouhlasení kontrolují záznamy vyžadující pozornost. Jde o architektonické doporučení, nikoli o záruku, že minimalizuje náklady pro každý účet.

  • Upřednostněte aktivní zásilky a záznamy s nevyřešenými chybami načítání.
  • Vyhněte se dotazování na každou historickou zásilku při každém plánovaném spuštění.
  • Definujte, jak se zpracovávají dokončené zásilky, včetně případného období pro opravy, které vaše firma vyžaduje.
  • Sledujte, jak často dotazy naleznou skutečně nové informace.
  • Prošetřujte problémy s doručováním webhooků, místo abyste je maskovali stále častějším dotazováním.

Sledujte latenci požadavků poskytovatele, neúspěšné dotazy, odpovědi s omezením rychlosti a rozdíly mezi daty získanými dotazem a záznamy naplněnými webhooky. Samostatně sledujte stáří nejnovější události přepravce. Úspěšné odpovědi API mohou existovat současně s informacemi o sledování, které se nezměnily.

Před vydáním pracovní postup otestujte

Úspěšný požadavek je pouze prvním testem. Ověřte situace, které by jinak mohly vytvářet zavádějící aktualizace stavu:

  • Webhook dorazí, zatímco dotaz na vyžádání stále probíhá.
  • Dva zákazníci nebo pracovní relace požádají současně o stejnou zásilku.
  • Poskytovatel vrátí úspěch HTTP, ale oznámí chybu na úrovni zásilky.
  • Požadavek selže poté, co vaše aplikace již obsahuje platné informace o sledování.
  • Události chybí časové pásmo nebo obsahují neznámý kód stavu.
  • Oprava přepravce změní dříve zobrazený výsledek.
  • Uživatel se pokusí získat přístup k zásilce patřící jinému účtu.

Kritériem vydání by mělo být, že aplikace vrací nejlépe známé informace o zásilce, přesně vysvětluje jejich aktuálnost a nepoškodí je při selhání požadavků nebo jejich příchodu v nesprávném pořadí.

Často kladené otázky

Přinutí dotazování API přepravce zásilku naskenovat nebo aktualizovat?

Ne. Načtení informací o sledování nemůže způsobit fyzické skenování. Zda požadavek spustí kontrolu u nadřazeného zdroje, závisí na zdokumentované operaci. I podporovaná aktualizace může vrátit nezměněné informace, pokud přepravce nemá novější událost.

Mohu používat dotazy API bez konfigurace webhooků?

Pokud poskytovatel podporuje požadovaný pracovní postup dotazování, můžete integraci založit na požadavcích na vyžádání nebo na pravidelném dotazování. Nejprve ověřte požadavky na registraci a dotazy. Vaše aplikace pak bude odpovídat za rozhodování, kdy kontrolovat, řízení objemu požadavků a zjišťování změn.

Jak často bych měl dotazovat stav zásilky?

Neexistuje univerzální interval. Zvolte plán, který odpovídá limitům poskytovatele, objemu vašich zásilek a obchodní hodnotě rychlejšího nalezení aktualizací. Změřte, jak často dotazování vrací nové události, a poté plán upravte, místo abyste předpokládali, že časté požadavky poskytují aktuálnější data přepravce.

Proč API vrací informace, které jsem již obdržel prostřednictvím webhooku?

Obě cesty mohou zpřístupňovat stejný základní záznam zásilky. Webhook doručuje oznámení, zatímco dotaz načítá informace na vyžádání. Přijetí stejné události oběma cestami nemusí být chybou; vaše aplikace by ji měla deduplikovat.

Mělo by tlačítko aktualizace říkat „Aktualizovat sledování“?

Pouze pokud toto označení přesně popisuje danou operaci. Pokud tlačítko načítá uložená data poskytovatele, je jasnější text „Zkontrolovat aktualizace“. Nejnovější událost přepravce zobrazte odděleně od času, kdy vaše aplikace naposledy úspěšně dokončila kontrolu.

Zdroje