Pracovní postup API pro sledování zásilek: od registrace zásilky po získání podrobností o sledování
Pracovní postup API pro sledování zásilek začíná odesláním sledovacího čísla a všech požadovaných informací o dopravci, kontrolou, zda registrace proběhla úspěšně, umožněním zpřístupnění sledovacích údajů a načtením stavu zásilky a historie událostí. V produkční integraci musí vývojáři také propojit každý záznam sledování s objednávkou, zvládat částečná selhání, bezpečně zpracovávat aktualizace a rozlišovat mezi přijatou registrací a skutečným skenem dopravce.
Tato příručka vysvětluje tento pracovní postup vývojářům, kteří propojují platformu elektronického obchodu, systém pro správu objednávek, skladovou aplikaci nebo nástroj zákaznické podpory. Odděluje doporučení týkající se návrhu aplikace od požadavků API specifických pro poskytovatele. Pro integraci se službou 17TRACK použijte oficiální dokumentaci API a před implementací níže uvedených příkladů ověřte schéma požadavků, autentizaci, podporované operace a pole odpovědí.
Pochopte, co registrace dělá — a co nedělá
Registrace zásilky u služby pro sledování znamená odeslání identifikátoru, aby služba mohla zásilku sledovat nebo spravovat v souladu se smlouvou API. Nejde o stejnou operaci jako nákup poštovného, vytvoření přepravního štítku, objednání vyzvednutí nebo předání balíku dopravci.
Ve své aplikaci rozlišujte tři výsledky:
- Požadavek přijat: API vrátilo odpověď na váš HTTP požadavek.
- Registrace přijata: Služba přijala jednotlivý záznam sledování ke zpracování.
- Sledovací informace jsou k dispozici: Služba má informace o zásilce, které může vaše aplikace načíst nebo přijmout.
Tyto výsledky by neměly být sloučeny do jediného příznaku „úspěch“. Přijaté sledovací číslo ještě nemusí obsahovat žádné události dopravce. Stejně tak úspěšná HTTP odpověď na dávkový požadavek neznamená, že byla přijata každá položka dávky; zkontrolujte strukturu výsledku na úrovni aplikace definovanou poskytovatelem.
1. Připravte identitu zásilky a konfiguraci API
Před odesláním registračního požadavku určete, jak bude zásilka identifikována ve vašem vlastním systému. Samotný identifikátor objednávky obvykle nestačí, protože jednu objednávku lze rozdělit do několika balíků. Každé zásilce nebo balíku vytvořte vlastní interní záznam a přiřaďte jej k příslušné objednávce.
Užitečný interní záznam obsahuje následující informace. Jde o navrhovaná aplikační pole, nikoli o schéma požadavku 17TRACK.
- Interní ID zásilky: Stabilní identifikátor balíku ve vašem systému.
- Odkaz na objednávku: Objednávka nebo záznam expedice, ke kterému zásilka patří.
- Sledovací číslo: Identifikátor vydaný dopravcem, uložený jako text, aby se zachovaly počáteční nuly.
- Informace o dopravci: Identita dopravce dodaná vaším systémem expedice, pokud je známa.
- Reference poskytovatele: Jakýkoli identifikátor vrácený službou sledování, který je potřebný pro pozdější operace.
- Stav registrace: Záznam o tom, zda čeká odeslání, byla přijata, zamítnuta nebo čeká na odsouhlasení.
- Stav sledování: Nejnovější stav zásilky udržovaný odděleně od stavu registrace.
Před odesláním ověřte vstupní údaje. Odstraňte náhodné mezery na začátku a na konci, ale nepřepisujte sledovací číslo na základě předpokladů o formátu dopravce. Původní hodnotu zachovejte pro řešení problémů. Pokud je dopravce znám, namapujte jej na zdokumentovaný identifikátor dopravce poskytovatele namísto odeslání neformálního zobrazovaného názvu.
Autentizaci konfigurujte na straně serveru. Uchovávejte přihlašovací údaje mimo správu zdrojového kódu, oddělte vývojovou a produkční konfiguraci a z protokolů odstraňujte tajné údaje. Ověřte zdokumentovanou verzi API, limity požadavků, limity dávek a požadavky na účet, místo abyste přebírali hodnoty z nesouvisející integrace.
2. Zaregistrujte zásilku a zaznamenejte výsledek na úrovni položky
Odešlete záznam sledování pomocí registrační operace popsané v dokumentaci vašeho poskytovatele. Uveďte pouze povinná pole a volitelné informace, které mají jasný účel. Neodesílejte jména zákazníků, adresy ani jiné osobní údaje jen proto, že jsou k dispozici ve vaší databázi objednávek.
Následující pseudokód znázorňuje posloupnost v aplikaci. Názvy funkcí jsou ilustrativní; nejde o koncové body API ani metody SDK.
shipment = load_internal_shipment(shipment_id)
validate_tracking_input(shipment)
result = tracking_adapter.register(shipment)
if result.item_accepted:
save_registration_result(shipment_id, result)
elif result.outcome_unknown:
schedule_registration_reconciliation(shipment_id)
else:
save_registration_error(shipment_id, result)
route_for_retry_or_correction(result)
Uchovávejte dostatek informací k vysvětlení toho, co se stalo: interní ID zásilky, čas odeslání, číslo pokusu, výsledek na úrovni položky a případnou referenci požadavku poskytovatele. Nespoléhejte pouze na dočasný protokol pracovního procesu. Týmy zákaznické podpory a provozu potřebují trvalou odpověď na otázku, zda byla zásilka úspěšně zaregistrována.
Zpracovávejte dávková odeslání jednotlivě
Pokud API podporuje dávkovou registraci, propojte každou vrácenou položku s původní zásilkou. Neoznačujte celou dávku jako přijatou jen proto, že HTTP požadavek byl úspěšně dokončen. Uložte přijaté položky, oddělte zamítnuté položky a nejednoznačné výsledky zkoumejte samostatně.
Tím zabráníte tomu, aby jedno chybně vytvořené sledovací číslo vyvolalo zbytečné opakování záznamů, které již uspěly. Provoznímu personálu to také poskytne praktický seznam záznamů vyžadujících opravu.
Považujte vypršení časového limitu za neznámý výsledek
Vypršení časového limitu nedokazuje, že registrace selhala. Poskytovatel mohl požadavek přijmout ještě před přerušením vašeho připojení. Před opětovným odesláním naslepo použijte zdokumentované chování idempotence, zpracování duplicit nebo vyhledávací operace k odsouhlasení výsledku.
Pokud není chování poskytovatele při duplicitách jasné, otestujte je na kontrolovaných záznamech a před povolením automatických opakovaných pokusů potvrďte smluvní podmínky. Interní deduplikace registračních úloh je stále užitečná, ale nenahrazuje pochopení toho, jak vzdálená služba zpracovává opakované požadavky.
3. Počkejte na příchod prvních sledovacích informací
Po přijetí registrace nemusí být podrobnosti sledování okamžitě k dispozici. Štítek může existovat ještě předtím, než dopravce zaznamená fyzickou manipulační událost. Chybějící informace mohou také vyžadovat kontrolu sledovacího čísla, volby dopravce nebo požadavků na vyhledání konkrétní zásilky.
Tento stav znázorněte explicitně. „Zaregistrováno; čeká se na sledovací informace“ je přesnější než „V přepravě“ nebo „Registrace selhala“. Nevymýšlejte odhad doručení ani událost pohybu, abyste zaplnili prázdné rozhraní.
Pokud záznam zůstává prázdný, postupujte při prověřování prakticky v tomto pořadí:
- Potvrďte, že jednotlivá registrace byla přijata.
- Porovnejte odeslané sledovací číslo se záznamem expedice.
- Zkontrolujte mapování dopravce a všechny zdokumentované další požadavky na vyhledávání.
- Na vlastní sledovací stránce dopravce zkontrolujte stejnou zásilku.
- Pokud dopravce události má, ale vaše integrace je nemá, zkontrolujte odpovědi načítání a kontaktujte poskytovatele API s diagnostickými informacemi zbavenými citlivých údajů.
Nepřijímejte univerzální čekací dobu bez důkazů. Pravidla eskalace by měla zohledňovat přepravní službu, očekávaný proces předání a vaše vlastní provozní závazky.
4. Načítejte podrobnosti sledování a správně je interpretujte
Jakmile je záznam k dispozici, zavolejte zdokumentovanou operaci pro načtení podrobností sledování pomocí požadovaných identifikátorů. Nepředpokládejte, že registrace a načtení přijímají stejná pole. Některé smlouvy API rozlišují mezi sledovacími čísly, identifikátory dopravců a referencemi záznamů vytvořenými poskytovatelem.
Vaše aplikace by měla rozlišovat tři vrstvy informací:
- Souhrn zásilky: Celkový stav používaný v panelech, na stránkách objednávek a v provozních filtrech.
- Historie událostí: Jednotlivá pozorování včetně popisů událostí, časových údajů a míst, pokud jsou dodány.
- Metadata načtení: Kdy aplikace informace přijala nebo načetla a zda byl požadavek úspěšně dokončen.
Úspěšné vyhledání znamená, že operace načtení proběhla úspěšně. Neznamená to, že se balík od předchozího vyhledání pohnul. Před vytvořením oznámení nebo navazujícího pracovního postupu porovnejte vrácené sledovací informace s uloženým záznamem.
Oddělujte čas události od času načtení
Čas spojený s událostí dopravce ukládejte odděleně od času, kdy jej váš systém přijal. Událost načtená dnes odpoledne může popisovat dřívější sken. Nahrazení času události časem načtení by způsobilo, že stará aktualizace bude vypadat jako nový fyzický pohyb.
Zachovejte původní časové razítko a případný dodaný posun. Časová razítka normalizujte pro porovnání pouze tehdy, pokud je časové pásmo známé. Pokud událost neobsahuje informaci o časovém pásmu, zachovejte tuto nejistotu namísto tichého přiřazení časového pásma vašeho serveru.
Vedle normalizovaného stavu zachovávejte původní význam
Normalizovaný stav je užitečný pro seskupování zásilek napříč dopravci, ale původní popis události může provozní problém vysvětlit přesněji. Pokud je to možné, uchovávejte obojí. Samotná obecná kategorie výjimky nemusí pracovníkovi podpory říci, zda má zkontrolovat adresu, kontaktovat příjemce nebo počkat na další aktualizaci.
Z nejasného stavu nevyvozujte záruku doručení, potvrzenou ztrátu ani konkrétní výsledek celního řízení. Eskalaci provádějte podle podkladových informací a provozních pravidel.
5. Udržujte záznamy aktualizované pomocí dotazování nebo webhooků
Jednorázové načtení podrobností stačí k otestování připojení, ale nestačí k udržení přehledu o zásilce. Produkční návrh potřebuje mechanismus aktualizací. Ověřte mechanismy podporované zvoleným poskytovatelem a podmínky, které se na ně vztahují.
Při dotazování vaše aplikace požaduje podrobnosti sledování podle harmonogramu. Plánujte požadavky v rámci zdokumentovaných limitů, bezdůvodně opakovaně nevyhledávejte nezměněné záznamy a při opakovatelných selháních používejte postupné prodlevy. Otevření stránky objednávky zákazníkem by nemělo automaticky spustit neomezený požadavek směrem k poskytovateli; stránku může obsloužit uložené zobrazení sledování, zatímco řízený proces na pozadí jej aktualizuje.
Pokud používáte webhooky, ověřujte příchozí požadavky pomocí zdokumentovaného ověřovacího mechanismu poskytovatele. Přijaté zprávy uložte nebo trvale zařaďte do fronty ještě před jejich potvrzením podle smlouvy webhooku a poté události zpracujte asynchronně.
Příjemce navrhněte tak, aby toleroval duplicity a neočekávané pořadí doručení, pokud zdokumentovaná smlouva o doručení nezaručuje opak. Pokud je k dispozici, použijte k deduplikaci identifikátor události poskytovatele. Jinak definujte a otestujte otisk založený na vhodných polích události a počítejte s tím, že takový otisk může vyžadovat úpravy podle vašich dat.
Integrace založená na webhoocích může pro odsouhlasení využívat také řízené načítání. Například obnovovací úloha může zkontrolovat záznamy ovlivněné výpadkem příjemce. Jde o vzor odolnosti, nikoli o povolení ignorovat limity rychlosti nebo pokyny specifické pro poskytovatele.
6. Proměňte sledovací informace v bezpečné obchodní akce
Před spuštěním akcí vůči zákazníkům aktualizujte interní záznam zásilky. Uchovávejte trvalý záznam oznámení a přechodů pracovních postupů, aby opakovaná událost nevytvářela opakované zprávy.
Obchodní akce mapujte na smysluplné změny, nikoli na každou odpověď API. Nově zaznamenaná událost doručení může odůvodnit oznámení o doručení. Opakovaná odpověď obsahující stejnou událost nikoli. Výjimka může odůvodnit interní kontrolu, ale zpráva zákazníkovi by měla odpovídat tomu, co událost skutečně říká.
Definujte, jak budete zpracovávat události přijaté poté, co byla zásilka považována za dokončenou. Historii událostí nemažte ani trvale neblokujte všechny pozdější aktualizace jen proto, že souhrn dosáhl koncového stavu. Pravidla uchovávání, odsouhlasení a oznámení by měla zohledňovat oprávněné opravy, aniž by opakovaně znovu otevírala dokončené pracovní postupy.
Použití pracovního postupu v integraci 17TRACK
Pro vlastní integraci sledování jsou vhodnými výchozími body stránka Tracking API 17TRACK a její dokumentace pro vývojáře. Produktovou stránku použijte k posouzení nabídky a dokumentaci k určení skutečné smlouvy integrace. Spotřebitelské stránky sledování nenahrazují specifikace API.
Před napsáním adaptéru ověřte formát autentizace, registrační a načítací operace, pravidla identifikace dopravce, zpracování odpovědí na úrovni položek a příslušné limity požadavků. U zpracování založeného na webhoocích ověřte také schéma dat, proces ověření, požadavky na potvrzení a chování při opakování.
Tyto podrobnosti specifické pro poskytovatele uchovávejte uvnitř adaptéru, místo abyste předpoklady o polích odpovědí rozšířili po celém systému objednávek. Zbytek aplikace pak může pracovat s interními pojmy, jako je výsledek registrace, stav zásilky, historie událostí a poslední úspěšná synchronizace.
Kontroly před spuštěním, které odhalí nákladné chyby
- Přijatý, ale prázdný záznam: Rozhraní zobrazuje, že sledovací informace čekají, nikoli že se balík pohybuje.
- Smíšený výsledek dávky: Každá zásilka obdrží vlastní uložený výsledek.
- Vypršení časového limitu po odeslání: Pracovní proces odsouhlasí nejistý výsledek namísto předpokladu selhání.
- Opakovaná událost: Časová osa zásilky i oznámení zákazníkovi zůstanou deduplikované.
- Starší událost přijatá později: Událost se zachová, aniž by bez rozmyslu nahradila novější souhrn.
- Nedostupná nadřazená služba: Stránka zákazníka může zobrazit poslední uložený výsledek s vhodným údajem o aktuálnosti.
- Nesprávné mapování dopravce: Záznam lze opravit prostřednictvím zdokumentované cesty obnovy.
- Rozdělená objednávka: Každý balík si zachová vlastní stav sledování a historii událostí.
- Odhalení přihlašovacích údajů nebo dat: Protokoly obsahují diagnostické reference, aniž by prozrazovaly tajné údaje nebo zbytečné osobní informace.
Praktickým kritériem dokončení není jen obdržení úspěšné odpovědi registrace. Jde o schopnost sledovat balík od odeslání přes aktualizace, vysvětlit prázdný nebo neúspěšný výsledek a zotavit se z přerušeného zpracování bez ztráty událostí nebo duplicitních akcí vůči zákazníkům.
Časté dotazy
Vytvoří registrace sledovacího čísla zásilku?
Ne v pracovním postupu popsaném zde. Registrace sledování odesílá existující identifikátor službě pro sledování. Vytvoření štítku, nákup poštovného a objednání přepravy jsou samostatné operace, pokud je konkrétní API výslovně nekombinuje.
Proč jsou po úspěšné registraci podrobnosti sledování prázdné?
Přijetí registrace a dostupnost sledovacích údajů jsou odlišné podmínky. Dopravce ještě nemusel zaznamenat událost nebo může být nutné zkontrolovat sledovací číslo, mapování dopravce či další informace pro vyhledávání. Před označením záznamu za úspěšně zaregistrovaný zkontrolujte výsledek na úrovni položky.
Mám zásilku registrovat pokaždé, když načítám její stav?
Nepoužívejte opakovanou registraci jako výchozí mechanismus aktualizace. Uložte stav přijaté registrace a použijte zdokumentovaný mechanismus načítání nebo aktualizace. Řiďte se výslovnými pravidly poskytovatele pro opravy, opětovnou aktivaci nebo duplicitní odeslání.
Mám použít dotazování, nebo webhooky?
Použijte mechanismus, který odpovídá zdokumentované smlouvě API a vašim provozním požadavkům. Dotazování vyžaduje řízený harmonogram požadavků. Webhooky vyžadují bezpečného a trvalého příjemce a zpracování odolné vůči duplicitám. Pokud jsou podporovány, mohou aktualizace pomocí webhooků s cíleným odsouhlasením poskytnout praktickou cestu obnovy.
Mohu sledovací číslo použít jako jediný identifikátor zásilky v databázi?
Místo toho použijte interní identifikátor zásilky. Sledovací číslo a příslušný kontext dopravce uložte jako atributy tohoto záznamu. Díky tomu lze snáze spravovat rozdělené objednávky, opravená sledovací čísla a reference specifické pro poskytovatele, aniž by se měnila identita interní zásilky.
Zdroje
- 17TRACK Tracking API — oficiální produktový výchozí bod pro posouzení integrace API 17TRACK.
- Dokumentace API 17TRACK — oficiální reference pro formáty požadavků, operace, odpovědi a požadavky na integraci specifické pro implementaci. Pseudokód a návrhy interních polí v této příručce jsou příklady návrhu aplikace, nikoli citace této smlouvy API.


