Průvodce pro vývojáře webhooků
Úvod
Webhooky FedEx Tracking Webhook poskytují informace o zásilce téměř v reálném čase během celého jejího životního cyklu.
Na rozdíl od rozhraní API pro sledování, která vyžadují, aby aplikace požádaly o stav zásilky, webhooky automaticky doručují aktualizace o zásilce, jakmile jsou k dispozici nové informace.
Témata této příručky:
- Tři principy integrace
- Jak fungují webhooky
- Zpracování datových obsahů webhooků
- Oznámení zákazníkům
- Časová razítka
- Osvědčené postupy a běžné problémy při integraci
Tři principy integrace
Úspěšná integrace webhooků se řídí třemi principy.
Považovat každý datový obsah webhooku za aktualizaci stavu zásilky
Nepředpokládejte, že každý datový obsah představuje nový milník sledování. FedEx publikuje nový datový obsah, kdykoli jsou k dispozici nové informace o zásilce.
Datový obsah může zahrnovat tyto údaje:
- Nová událost sledování
- Aktualizované předpokládané doručení
- Informace o potvrzení o doručení
- Informace o příjemci
- Další změny údajů o zásilce
Více datových obsahů může mít stejný milník sledování a přitom zahrnovat různé informace o zásilce.
Uchovávat a slučovat údaje o zásilce
Každý datový obsah může zahrnovat nové nebo aktualizované informace o zásilce. Uložte každý datový obsah webhooku a nové informace začleňte do stávajícího záznamu o zásilce.
Nepřepisujte stávající záznam o zásilce nejnovějším datovým obsahem. Místo toho zachovejte dříve přijatá data o zásilce a začleňte nové informace, abyste po celý její životní cyklus zásilky udrželi úplný a aktuální záznam o zásilce.
Řídit akce podle obchodních pravidel
Podle obchodních pravidel určete, kdy aktualizovat systémy nebo informovat zákazníky.
Nespouštějte akce pouze na základě kódu události. Před aktualizací aplikací určených zákazníkům nebo odesláním oznámení posuďte:
- Milníky sledování
- Dostupnost zásilky
- Načasování oznámení
- Obchodní požadavky
Doporučený model zpracování
Následující diagram znázorňuje, jak tři principy integrace webhooků při typické implementaci dohromady fungují. Každý datový obsah webhooku se zpracuje jako aktualizace stavu zásilky, sloučí se do centralizovaného záznamu o zásilce a vyhodnotí se podle obchodních pravidel před aktualizací aplikací nebo odesláním oznámení zákazníkům.
Jak fungují webhooky
FedEx publikuje nový datový obsah webhooku pokaždé, když se informace o zásilce změní nebo jsou nově k dispozici. Zásilka může během životního cyklu generovat více datových obsahů, včetně několika datových obsahů spojených se stejným milníkem sledování.
Další datové obsahy mohou zahrnovat:
- Milníky sledování: Vyzvednuto, V přepravě, Předáno k doručení a Doručeno.
- Údaje o zásilce: potvrzení o doručení zásilky ve formě fotografie (PPOD), podepsané potvrzení o doručení (SPOD), GPS potvrzení o doručení (GPS POD) a informace o příjemci.
- Aktualizace předpokládaného doručení: změny předpokládaného data a času doručení.
- Výjimky při doručení: aktualizace výjimek týkajících se zásilky a doručení včetně jejich důvodů.
- Aktualizace metadat zásilky: změny adres, reference a podrobnosti o službě.
- Provozní opravy: další milníky sledování a aktualizace
previousEvents.
Poznámka: Fotografické potvrzení není k dispozici u všech doručených zásilek. Dostupnost závisí na typu doručení, požadavcích na podpis a dalších obchodních pravidlech.
Každý datový obsah představuje nejnovější známý stav zásilky. Zpracujte každý datový obsah, aby záznam o zásilce zůstal úplný a aktuální.
Princip aktualizací webhooků
Následující příklad ukazuje, jak může pro tutéž zásilku během jejího životního cyklu vzniknout několik datových obsahů webhooku. Některé datové obsahy přinášejí nový milník sledování. Jiné přidávají informace o zásilce, například předpokládané doručení, údaje o potvrzení o doručení nebo podrobnosti o zásilce.
Důležité: Pro stejný milník sledování může být vygenerováno více datových obsahů webhooku. Zpracujte každý datový obsah, abyste zajistili, že nové informace o zásilce budou začleněny do záznamu o zásilce.
Zpracování datových obsahů webhooků
Zpracujte každý datový obsah webhooku jako aktualizaci stavu zásilky.
Nepředpokládejte, že každý datový obsah webhooku představuje nový milník sledování. FedEx odesílá nový datový obsah, kdykoli jsou k dispozici nové informace o zásilce. Doručená zásilka může například vygenerovat další datové obsahy, když jsou doplněny nebo aktualizovány informace o potvrzení o doručení, informace o příjemci nebo jiné údaje o zásilce.
U každého datového obsahu si položte tyto otázky:
- Který milník sledování se změnil?
- Které informace o zásilce se změnily?
- Ovlivňuje tato aktualizace aplikaci určenou zákazníkům?
- Vyvolá tato aktualizace oznámení?
Zpracování historie zásilky
Sledujte jak scanEvent, tak previousEvents.
scanEventobsahuje aktuální milník sledování spojený s datovým obsahem.previousEventsobsahuje další historii zásilky, včetně milníků, které se nemusí zobrazit jako aktuálníscanEvent.
Některé milníky sledování se zobrazují v previousEvents místo toho, aby byly publikovány jako nová událost scanEvent. Aplikace, které zpracovávají pouze scanEvent, nemusí zaznamenat aktualizace zásilek, a vytvoří tak neúplnou historii zásilek. Zpracujte obě kolekce, abyste získali úplný přehled o zásilce.
Udržování záznamu o zásilce
Uložte každý datový obsah webhooku a nové informace začleňte do stávajícího záznamu o zásilce.
Kompletní záznam o zásilce poskytuje přehled téměř v reálném čase pro:
- Řídicí panely pro sledování zásilek
- Aplikace zákaznického servisu
- Systémy pro správu objednávek (OMS)
Záznam o zásilce aktualizujte s každým datovým obsahem, abyste zachovali co nejpřesnější a nejúplnější přehled o zásilce.
Oznámení zákazníkům
Zvolte strategii oznámení na základě svých obchodních požadavků a úrovně podrobností o zásilce, které chcete poskytovat.
Webhooky FedEx Tracking Webhook zasílají aktualizace o milnících sledování a změnách údajů o zásilkách téměř v reálném čase. Podle obchodních pravidel určete, které aktualizace jsou pro vaše podnikání relevantní a které lze ignorovat.
Mezi běžné strategie oznámení patří:
Oznámení téměř v reálném čase
Odesílejte oznámení ihned poté, co nastane milník sledování.
Výhody
- Nejrychlejší komunikace se zákazníky
- Nejnižší prodleva
Na co si dát pozor: Další informace o zásilce nemusí být ještě k dispozici.
Rozšířená oznámení
Počkejte několik minut po milníku sledování, aby mohly dorazit další informace o zásilce.
Například po milníku doručení počkejte několik minut, abyste shromáždili:
- Potvrzení o doručení (POD)
- Podepsané potvrzení o doručení (SPOD)
- Potvrzení o doručení s údaji GPS
- Informace o příjemci
Výhody
- Úplnější aktualizace zásilek pro zákazníky
- Méně následných oznámení
- Méně dotazů na zákaznickou podporu
FedEx doporučuje počkat přibližně pět minut po milníku doručení, protože informace o potvrzení o doručení se často doplňují krátce po prvotní události doručení.
Doporučení ohledně načasování oznámení
Načasování oznámení se liší podle zákazníka a konkrétního případu použití. Následující doporučení se však běžně používají pro oznámení určená příjemcům po nákupu. U ostatních typů oznámení (pro firemní uživatele, zástupce zákaznického servisu apod.) zvolte strategii oznámení, která odpovídá vašemu případu použití.
- Odhadované datum doručení: Počkejte přibližně 15 minut poté, co budou k dispozici jak datum závazku, tak první předpokládané datum doručení (EDD).
- Předáno k doručení: Odesílejte ihned nebo podle svého obchodního harmonogramu (například denně v 8:00).
- Doručeno: Počkejte přibližně pět minut, než dorazí doplňující údaje o doručení.
- Pokus o doručení: Použijte stejný postup jako u události Doručeno, aby mohly dorazit informace o doručení.
Tvorba pravidel oznámení na základě obchodních dat
Ne každá aktualizace zásilky vyžaduje oznámení. Definujte pravidla oznámení, která podporují vaše obchodní požadavky.
Doporučený postup
Nespouštějte oznámení pouze na základě eventCode.
Co je třeba vyhodnotit:
- Milník sledování
- Potřebné údaje o zásilce
- Obchodní pravidla
Generujte oznámení pouze tehdy, když jsou k dispozici požadované informace.
Tento přístup pomáhá předcházet:
- Duplicitním oznámením
- Chybějícím informacím o doručení
- Neúplným oznámením o doručení
- Zbytečným následným oznámením
Časová razítka
Použijte vhodné časové razítko podle případu použití.
eventCreateTime: Kdy k události zásilky došlo. Použijte je pro historii sledování určenou zákazníkům.- Čas odeslání zprávy: Kdy společnost FedEx odeslala datový obsah webhooku. Používejte je pouze k ladění a monitorování, nikoli pro zákaznické prostředí.
eventCreateTime udává, kdy k události zásilky došlo. FedEx tuto hodnotu neaktualizuje, pokud jsou další informace o zásilce přidány později. Například událost doručení si zachová původní hodnotu eventCreateTime, i když následné datové obsahy přidá informace o potvrzení o doručení nebo jiné aktualizace zásilky. Proto by se hodnota eventCreateTime měla používat k určení, kdy k události došlo, a nikoli kdy byly přidány související informace o zásilce.
V některých případech nemusí být čas události k dispozici. Když k tomu dojde, časové razítko může obsahovat výchozí hodnotu 00:00:00. Další datové obsahy mohou zahrnovat přesnější časové razítko, jakmile bude k dispozici.
Osvědčené postupy a běžné problémy při integraci
Osvědčené postupy
- Zpracujte každý datový obsah webhooku – každá zpráva může obsahovat novou událost sledování nebo aktualizaci údajů o zásilce.
- Slučte průběžné aktualizace do stávajícího záznamu o zásilce.
- Sledujte jak
scanEvent, takpreviousEvents, abyste zachytili úplnou historii zásilky. - Spouštějte oznámení zákazníkům podle obchodních pravidel, nikoli pouze na základě nezpracovaných událostí.
- Před informováním zákazníků počkejte, než budou k dispozici očekávané doplňující údaje (např. PPOD, SPOD, GPS).
- Navrhněte idempotentní a robustní zpracování, které zvládá duplicitní zprávy i zprávy přicházející mimo pořadí.
Běžné problémy při integraci
- Předpoklad, že každý datový obsah představuje nový milník sledování.
- Přepsání záznamu o zásilce nejnovějším datovým obsahem.
- Spoléhání pouze na
scanEvent. - Spouštění oznámení výhradně na základě
eventCode. - Předpoklad, že první doručený datový obsah obsahuje veškeré podrobnosti o doručení.
- Předpoklad, že zprávy webhooku dorazí pouze jednou nebo v chronologickém pořadí.
Shrnutí
Zpracujte každý datový obsah webhooku jako aktualizaci stavu zásilky. Ukládejte a slučujte aktualizace zásilek, sledujte jak scanEvent, tak previousEvents, a pomocí obchodních pravidel určujte, kdy aktualizovat aplikace nebo informovat zákazníky.
Tento přístup pomáhá zajistit přesný přehled o zásilkách, úplnou historii sledování a informovanější komunikaci se zákazníky.
