Stav doručení Shipping API: stavové kódy, webhooky a upozornění na výjimky
Stav doručení v přepravním API popisuje postup zásilky, nikoli to, zda byl požadavek API úspěšný. Chcete-li vytvořit spolehlivé sledování, oddělujte kódy odpovědí HTTP od stavů zásilky, zpracovávejte webhooky bez předpokladu, že dorazí právě jednou nebo ve správném pořadí, a převádějte výjimky vyžadující akci na upozornění s jasně určenými vlastníky. Pro týmy vývoje a provozu e-commerce je cílem záznam zásilky, který zůstane důvěryhodný i tehdy, když jsou aktualizace přepravce opožděné, duplicitní nebo opravené.
Tato příručka vysvětluje, jak takový záznam strukturovat, jak zpracovávat příchozí události sledování a jak rozlišit problém s doručením od problému s integrací sledování.
Oddělte kódy HTTP, výsledky API a stavy zásilky
Výraz „stavový kód“ může označovat tři různé vrstvy. Jejich směšování vytváří zavádějící přehledy a zbytečná upozornění pro zákazníky.
| Vrstva | Co vám sděluje | Příklad interpretace |
|---|---|---|
| Odpověď HTTP | Výsledek požadavku HTTP | Odpověď 200 označuje úspěch na úrovni HTTP; neznamená, že byla zásilka doručena. |
| Obchodní výsledek API | Zda požadovaná operace uspěla podle aplikačních pravidel poskytovatele | Tělo odpovědi může oznámit, že registrace sledování byla odmítnuta, a to i v rámci úspěšné odpovědi HTTP, pokud API používá takový návrh. |
| Stav zásilky | Oznámený fyzický nebo provozní stav zásilky | V přepravě, čeká na vyzvednutí nebo doručeno. |
Standard sémantiky HTTP definuje významy odpovědí HTTP. Například 202 Accepted znamená, že požadavek byl přijat ke zpracování, ale zpracování nemusí být dokončeno. Není to důkaz, že přepravce zásilku převzal.
Stejně tak neúspěšný požadavek na sledování nedokazuje, že se zásilka přestala pohybovat. Vaše aplikace může dočasně ztratit přehled, zatímco fyzické doručení normálně pokračuje. Tyto vrstvy monitorujte nezávisle.
Vytvořte model stavů, aniž byste zahodili podrobnosti přepravce
Neexistuje univerzální číselný kód stavu doručení sdílený všemi přepravními API a přepravci. Hodnota z jedné integrace by neměla být interpretována pomocí mapování jiného poskytovatele. Použijte dokumentaci konkrétní verze API, kterou implementujete.
Praktický interní model kombinuje malou sadu normalizovaných stavů s původní událostí přepravce. Normalizace podporuje konzistentní vykazování; původní událost zachovává podrobnosti potřebné k šetření.
| Ilustrativní interní stav | Význam | Provozní upozornění |
|---|---|---|
| Informace přijaty | Existují elektronické informace o zásilce. | Nepovažujte vytvoření štítku za potvrzené fyzické předání. |
| V přepravě | Záznam sledování uvádí pohyb prostřednictvím doručovací sítě. | Tato široká kategorie může zahrnovat různé fáze přepravy. |
| Na cestě k doručení | U zásilky je oznámeno, že se nachází na doručovací trase. | Nepřevádějte tento stav na bezpodmínečnou záruku doručení. |
| Čeká na vyzvednutí | Očekává se, že příjemce zásilku vyzvedne. | Pokyny k vyzvednutí nebo lhůty uvádějte pouze tehdy, pokud je podporuje zdroj. |
| Doručeno | Zdroj sledování oznámil doručení. | Sken doručení sám o sobě neřeší tvrzení zákazníka, že zásilku neobdržel. |
| Výjimka | Událost může vyžadovat pozornost nebo přerušit běžný postup. | Uchovejte důvod místo toho, abyste každou výjimku považovali za ztrátu. |
| Probíhá vrácení nebo vráceno | Zásilka se vrací nebo bylo oznámeno dokončení jejího vrácení. | Rozlišujte průběh vrácení od doručení původnímu příjemci. |
| Neznámý | Dostupné informace nelze s jistotou namapovat. | Prověřte mapování nebo chybějící data, místo abyste vytvořili smyšlený stav doručení. |
Tyto štítky jsou navrhovaným aplikačním modelem, nikoli oficiálním seznamem kódů 17TRACK. Pokud jsou k dispozici, uchovávejte stavový kód poskytovatele, podstav, popis, čas události, informace o časovém pásmu, polohu a čas přijetí. Uchovávejte také verzi mapování, aby bylo možné pozdější změny mapování auditovat.
Pro implementaci s více přepravci je 17TRACK Tracking API relevantní možností integrace. K vytvoření implementační smlouvy použijte oficiální dokumentaci API, místo abyste kopírovali ilustrativní štítky do polí specifických pro poskytovatele. Před vytvořením adaptéru ověřte příslušné definice stavů, konfiguraci webhooků, požadavky na autentizaci a sémantiku odpovědí.
Postavte zpracování webhooků na trvalém přijetí
Webhook je požadavek HTTP odeslaný na váš endpoint za účelem oznámení události. Může omezit potřebu opakovaného dotazování, neměl by však být považován za záruku okamžitého, uspořádaného nebo právě jednorázového doručení. Navrhněte přijímač tak, aby toleroval opakování, přerušení a neočekávané datové struktury, pokud poskytovatel výslovně nezaručuje opak.
- Autentizujte požadavek. Použijte zdokumentovanou metodu ověření poskytovatele. Pokud jsou podporovány podpisy, ověřte je pomocí určeného algoritmu a původních bajtů požadavku. Nevymýšlejte hlavičku podpisu a nepředpokládejte, že každá služba používá HMAC.
- Ověřte datovou strukturu. Zkontrolujte povinná pole, typy, velikost dat a vazbu na zásilku spravovanou vaším účtem. Neznámá volitelná pole zpracujte bez zbytečného narušení dopředné kompatibility.
- Uložte před potvrzením. Přijatou událost uložte nebo ji před odesláním zdokumentované úspěšné odpovědi vložte do trvalé fronty. Pokud uložení selže, nepotvrzujte bezpečné přijetí události.
- Zpracovávejte asynchronně. Mapování stavů, aktualizace objednávek a rozhodování o upozorněních provádějte, pokud je to praktické, mimo obsluhu požadavku.
- Zajistěte idempotenci vedlejších účinků. Opakovaná událost by neměla vytvořit další požadavek na podporu ani odeslat další kopii stejné zprávy zákazníkovi.
Přesný kód potvrzení, časový limit, plán opakování a chování při opětovném přehrání závisí na poskytovateli. Tyto podrobnosti výslovně ověřte. Obecný pokyn „vracejte 200“ nenahrazuje smlouvu webhooku.
Používejte HTTPS a přihlašovací údaje neukládejte do URL ani běžných protokolů. Na uložená data aplikujte řízení přístupu, protože údaje o sledování mohou obsahovat osobní informace. OWASP REST Security Cheat Sheet poskytuje relevantní pokyny k ochraně přenosu, ověřování vstupů a zabezpečení endpointů.
Deduplicujte události, aniž byste potlačili skutečné aktualizace
Pokud je k dispozici, upřednostněte zdokumentovaný a stabilní identifikátor události. Jinak vytvořte deduplikační klíč z pečlivě zvolené kombinace identity zásilky, časového razítka události, kódu události a polohy. Tento přístup testujte na skutečných datech: dvě legitimní události mohou sdílet časové razítko a stejná událost může dorazit s mírně odlišným popisným textem.
Pro příjem událostí a následné akce používejte oddělené deduplikační mechanismy. Aktualizaci stavu může být nutné znovu uložit jako opravu, zatímco upozornění zákazníka by mělo zůstat potlačené. Každému upozornění nebo akci požadavku na podporu přidělte vlastní trvalou identitu.
Oddělujte čas události od času přijetí
Představte si, že událost „v přepravě“ dorazí do vašeho systému po události „na cestě k doručení“, ale její časové razítko přepravce je dřívější. Uložte ji do historie, aniž byste automaticky změnili aktuální stav zpět na „v přepravě“.
Samotné řazení podle časových razítek nestačí pro každý případ. Chybějící časová pásma, opravené skeny a konfliktní zdroje vyžadují výslovná pravidla. Zachovávejte přesnost časového razítka a posuny, zaznamenávejte, kdy váš systém každou událost přijal, a pokud jsou k dispozici, používejte zdokumentované informace poskytovatele o pořadí. Nevynucujte pevnou stavovou posloupnost pouze směrem vpřed: pokusy o doručení, přesměrování, vrácení a opravy mohou vytvářet legitimní přechody, které vypadají jako krok zpět.
Převádějte výjimky na konkrétní úkoly s vlastníkem
Upozornění na výjimku by mělo vysvětlit, co se stalo, jaká akce je nutná a kdo vlastní další krok. Obecná zpráva „výjimka zásilky“ nutí provozní pracovníky opakovat stejné šetření a může znepokojit zákazníky, aniž by jim pomohla.
Začněte s malými pravidly směrování:
- Problém s adresou nebo přístupem: Předejte případ zákaznické podpoře k ověření problému a dostupného postupu opravy u přepravce. Neslibujte změnu adresy, dokud nepotvrdíte, že je možná.
- Vyžadováno vyzvednutí: Upozorněte příjemce, pokud zdroj poskytuje použitelné pokyny k vyzvednutí. Zachovejte ověřenou lhůtu.
- Vyžadována celní akce: Přiřaďte případ podle toho, kdo musí poskytnout požadované dokumenty nebo informace. Samotná celní událost neznamená, že je nutná platba.
- Neúspěšný pokus o doručení: Před doporučením opětovného doručení nebo vyzvednutí ověřte oznámený další krok.
- Vrácení odesílateli: Zahajte provozní kontrolu. Automaticky nevystavujte refundaci pouze na základě obecného štítku sledování, pokud to vaše pravidla výslovně nepovolují.
- Ztráta nebo poškození oznámené přepravcem: Předejte případ vlastníkovi reklamace a uchovejte důkazy o události. Rozhodnutí o reklamaci oddělujte od obecného zjišťování zpoždění.
Každé upozornění by mělo obsahovat identifikátor zásilky, referenci objednávky, důvod události, časové razítko zdroje, poslední známý stav, přiřazeného vlastníka a další akci. Místo zveřejňování zbytečných údajů o zákazníkovi ve sdílených komunikačních kanálech uveďte odkaz na příslušný interní záznam.
Považujte „žádná aktualizace“ za samostatný stav
Zásilka bez nedávného skenu není automaticky ztracená. Může se nacházet mezi kontrolními body, čekat na první fyzický sken nebo být ovlivněna výpadkem viditelnosti.
Prahové hodnoty neaktivity definujte podle služby, trasy, fáze přepravy a obchodního závazku, nikoli pomocí jediného univerzálního časovače. Rozlišujte zásilku, která nikdy neobdržela sken převzetí, od zásilky, jejíž aktualizace se zastavily po vstupu do sítě. Pokud jsou historické důkazy omezené, použijte práh ke spuštění šetření, nikoli k prohlášení zásilky za ztracenou.
Potlačte opakovaná upozornění, dokud zůstává nezměněný případ otevřený. Eskalujte, když se objeví nové důkazy, zmešká se dohodnutá kontrola nebo závazek doručení zákazníkovi vyžaduje zásah.
Monitorujte stav integrace odděleně od výkonu doručení
Monitorování API odpovídá na otázku, zda vaše integrace sledování funguje. Monitorování doručení odpovídá na otázku, co se děje se zásilkami. Funkční endpoint může přijímat zastaralá data přepravce, zatímco nedostupný endpoint může zmeškat aktualizace zásilek, které se normálně pohybují.
- Stav požadavků: Sledujte selhání autentizace, časové limity, odpovědi na překročení limitu, chyby serveru a odmítnutí na aplikační úrovni.
- Stav webhooků: Sledujte selhání ověření, latenci potvrzení, selhání ukládání, duplicitní doručení a chyby zpracování.
- Stav zpracování: Monitorujte stáří fronty, nezpracované události, chyby mapování a chyby upozornění.
- Aktuálnost sledování: Měřte dobu od poslední události zdroje odděleně od doby od posledního úspěšného příjmu.
- Provozní výsledky: Sledujte nevyřešené výjimky, dobu do přiřazení vlastníka a zmeškané následné kroky.
Při opakování požadavků dodržujte pokyny poskytovatele k limitům a opakováním. Vyhněte se slepému opakování operací, které by mohly vytvořit duplicitní registrace nebo jiné vedlejší účinky; pokud jsou k dispozici, používejte zdokumentované mechanismy idempotence.
Pokud je podporován, použijte po výpadcích nebo při podezření na zmeškané události proces odsouhlasení k načtení nejnovějšího záznamu sledování. Jeho frekvenci nastavte v rámci smluvních a rychlostních limitů. Webhooky a odsouhlasení slouží různým účelům: jedno doručuje změny, druhé pomáhá odhalovat a opravovat mezery.
Před povolením upozornění zákazníkům otestujte chybové případy
Začněte zpracováním pouze pro interní účely a před povolením odesílání zpráv zákazníkům zkontrolujte reprezentativní zásilky. Testujte více než běžný postup od „v přepravě“ po „doručeno“.
- Duplicitní webhook vytvoří jedno zamýšlené upozornění zákazníkovi.
- Pozdě dorazivší starší událost nesprávně nenahradí aktuální stav.
- Neznámý stav se zachová a označí, místo aby byl tiše namapován na „doručeno“.
- Neúspěšný trvalý zápis nevytvoří úspěšné potvrzení.
- Dočasný výpadek následného systému ponechá události dostupné pro opakování.
- Událost „doručeno“ následovaná opravou zůstane auditovatelná.
- Objednávka s více zásilkami nebude označena jako plně doručená, když byla doručena pouze jedna zásilka.
- Výpadek API upozorní vývojový tým, aniž by zákazníkům automaticky oznámil zpoždění zásilek.
Kritériem vydání by měla být provozní konzistence: záznam zásilky, zpráva zákazníkovi a akce podpory musí vycházet ze stejných podkladů a vzájemně si odpovídat. Samotná úspěšná odpověď webhooku neprokazuje, že doručování funguje.
Časté dotazy
Znamená HTTP 200, že byla zásilka doručena?
Ne. Označuje úspěch požadavku na úrovni HTTP. Výsledek obchodní operace API a pole stavu zásilky čtěte samostatně. U webhooku se úspěšné potvrzení týká přijetí oznámení, nikoli fyzického doručení zásilky.
Mám pro aktualizace sledování používat webhooky, nebo dotazování?
Pokud je poskytovatel podporuje, používejte pro aktualizace řízené událostmi webhooky. Pokud je to podporováno a provozně odůvodněno, přidejte omezené dotazování pro odsouhlasení a obnovu mezer. Samotné dotazování může být vhodné, když webhooky nejsou k dispozici, jeho frekvence však musí respektovat limity poskytovatele a vaše požadavky na aktuálnost.
Proč se může stav sledování změnit po označení „doručeno“?
Zdroj může událost opravit nebo může vaše integrace obdržet opožděné či konfliktní informace. Zachovejte historii a vyhodnoťte novější důkazy, místo abyste stav „doručeno“ považovali z technického hlediska za neměnný. Oznámené doručení a potvrzení převzetí zákazníkem jsou také dvě odlišné skutečnosti.
Jak rychle by mělo být odesláno upozornění na výjimku?
Naléhavost založte na požadované akci a ověřené lhůtě. Problém vyžadující akci příjemce vyžaduje jiné zpracování než informativní zpoždění. Rychlost zpracování nemůže napravit událost přepravce zveřejněnou pozdě, proto zachovávejte časová razítka zdroje i přijetí.
Měli by zákazníci vidět nezpracovaný stav přepravce?
Zákazníci obvykle více ocení jasné vysvětlení a podporovaný další krok než nevysvětlený kód. Nezpracované podrobnosti uchovávejte pro podporu a audit. Stav nikdy nezjednodušujte na silnější příslib, než jaký podporuje podkladová událost.
Zdroje
- RFC 9110: HTTP Semantics — reference k významům stavových kódů HTTP včetně 200 a 202.
- OWASP REST Security Cheat Sheet — bezpečnostní pokyny relevantní pro endpointy API a webhooků.
- 17TRACK Tracking API — oficiální reference produktu pro diskutovanou možnost integrace sledování.
- 17TRACK API Documentation — oficiální reference požadavků integrace specifických pro poskytovatele; ilustrativní schémata a doporučení pracovních postupů v této příručce tuto smlouvu nenahrazují.
