Jaká data by mělo API pro sledování vracet? 12 polí nad rámec aktuálního stavu?
Aplikační programovací rozhraní pro sledování zásilek by mělo vracet více než štítek, jako je „V přepravě“. Kromě aktuálního stavu hledejte identifikátory zásilky, identitu dopravce, podrobné informace o stavu, původní zprávy dopravce, historii událostí, časová razítka událostí, místa, odhady doručení, výjimky, předání mezi dopravci, podrobnosti o doručení a metadata o aktuálnosti dat. Těchto 12 skupin údajů společně pomáhá vývojářům vytvářet spolehlivé pracovní postupy a poskytuje provozním týmům dostatek kontextu k jednání.

Jedná se o doporučený kontrakt odpovědi pro vývojáře, technické nákupčí a provozní týmy e-commerce, nikoli o tvrzení, že každý dopravce nebo API poskytuje každé pole. Některé hodnoty legitimně nemusí být k dispozici. Lepší návrh tyto mezery výslovně označí, místo aby je vyplňoval předpoklady.
Co činí data o sledování užitečnými?
Aktuální stav odpovídá na jednu úzce vymezenou otázku: jaký je souhrnný stav zásilky? Nemusí však vysvětlovat, co se stalo, kdy se to stalo, zda jsou informace aktuální nebo co by měl někdo udělat dál.
Například dvě zásilky mohou mít obě stav „V přepravě“, přesto mohou vyžadovat odlišnou reakci. U jedné může být k dispozici nedávný sken v přepravním zařízení a nemusí být hlášen žádný problém. U druhé může být v historii událostí zaznamenán nevyřešený problém s adresou. Aplikace, která čte pouze hlavní stav, může tento rozdíl přehlédnout.
Odpověď posuzujte podle tří praktických úkolů: přiřazení zásilky ke správné objednávce, přesné vysvětlení jejího průběhu a rozhodnutí, zda je oprávněné nějaké jednání. Následující pole tyto úkoly podporují. Názvy polí jsou ilustrativní; nejde o univerzální standard ani schéma konkrétního poskytovatele.
12 polí, která je třeba vyhodnotit nad rámec aktuálního stavu
1. Identifikátory zásilky a sledování
Odpověď by měla identifikovat zásilku, o které pojednává. Mezi užitečné hodnoty patří zadané sledovací číslo, identifikátor záznamu sledování v API a reference klienta, kterou může váš systém přiřadit k záznamu o plnění objednávky nebo balíku.
Nepředpokládejte, že jedna objednávka znamená jednu zásilku. Objednávka může být rozdělena do více balíků a náhradní zásilka může vytvořit další zásilku. Záznamy o sledování ukládejte na úrovni balíku nebo plnění objednávky a následně je propojte s objednávkou. Sledovací čísla uchovávejte jako řetězce, aby nedošlo ke ztrátě formátování a úvodních nul.
2. Identita dopravce
Vedle čitelného názvu dopravce hledejte stabilní identifikátor dopravce. Pokud je to možné, měla by odpověď rozlišovat dopravce výslovně zadaného vaší aplikací od dopravce vybraného automatickou detekcí.
Kontext dopravce je důležitý při interpretaci sledovacího čísla a jeho událostí. Pokud je detekce nejednoznačná, vaše integrace by měla mít možnost tento stav vyřešit, nikoli tiše zobrazit nejistou shodu jako potvrzenou. Informace o úrovni služby uchovávejte odděleně: samotný název dopravce neurčuje, zda zásilka využívá expresní, poštovní nebo jinou službu.
3. Normalizované podrobnosti stavu
Spolu s hlavním stavem si vyžádejte zdokumentovaný podrobný kód nebo podstav. Široká kategorie může zásilku označit jako výjimku, zatímco podrobnost určí neúspěšný pokus o doručení, problém s adresou nebo zadržení související s celním řízením.
Pro obchodní logiku používejte stabilní kódy a pro prezentaci čitelné štítky. Ověřte, jak poskytovatel mapuje události dopravce na tyto kódy, včetně toho, jak zpracovává neznámé nebo nenamapované události. Normalizovaný štítek usnadňuje práci s daty od různých dopravců, neměl by však mazat rozdíly, které váš tým podpory potřebuje.
4. Původní zprávy a kódy dopravce
Pokud jsou k dispozici, uchovávejte původní popis události a kód události dopravce. Tyto hodnoty poskytují pracovníkům podpory kontext, který může v normalizovaném stavu chybět, zejména když dopravce používá konkrétní provozní formulaci.
Původní text uchovávejte odděleně od přeložených nebo přeformulovaných popisů. Jinak může být vysvětlení určené zákazníkovi mylně považováno za přesné znění dopravce. Při zobrazování považujte text dopravce za nedůvěryhodný vstup: vhodně jej escapujte a nevykreslujte jej jako spustitelný HTML kód.
5. Historie událostí sledování
Užitečná odpověď by měla zpřístupnit časovou osu zásilky, nikoli pouze její poslední událost. Každá událost by ideálně měla obsahovat identifikátor, stav nebo kód, popis, časové razítko a dostupné informace o místě.
Ověřte, zda API vrací úplnou historii, omezené časové období nebo stránkované výsledky. Stanovte také, jak jsou reprezentovány opravy a duplicitní pozorování. Vaše aplikace by neměla předpokládat, že první položka je vždy nejnovější, pokud kontrakt odpovědi toto pořadí výslovně nezaručuje.
6. Časová razítka událostí a informace o časovém pásmu
Čas, kdy k události došlo, se liší od času, kdy ji API přijalo nebo vrátilo. Pokud je to možné, uchovávejte oba údaje. Toto rozlišení pomáhá vysvětlit, proč nově přijatá aktualizace může popisovat něco, co se stalo dříve.
Vyžadujte časová razítka s výslovným posunem UTC nebo s označením UTC. RFC 3339 definuje formát časového razítka vhodný pro internetové protokoly včetně číselných časových posunů. Pokud zdroj poskytuje pouze místní čas bez známého posunu, zachovejte tuto nejistotu, místo abyste jej tiše považovali za UTC. Nikdy nenaznačujte přesnost na úrovni sekund, pokud zdroj poskytuje pouze datum.
7. Místa událostí a geografie zásilky
Pokud jsou k dispozici, hledejte strukturované složky místa, jako je město, region, země a poštovní směrovací číslo. Pokud by převod na strukturovaná pole mohl vést ke ztrátě významu, uchovejte také nezpracovaný řetězec místa.
Místo skenu nemusí být skutečnou aktuální polohou balíku. Stejně tak poslední nahlášené přepravní zařízení není důkazem, že se tam zásilka stále nachází. Stránky pro zákazníky by jej měly popisovat jako poslední nahlášené místo. Z neúplného textu skenu neodvozujte souřadnice ani přesnou doručovací adresu.
8. Odhadované datum nebo časové okno doručení
Pole s odhadovaným doručením by mělo uvádět, zda obsahuje jedno datum nebo časové okno, kdo je vytvořil a kdy bylo naposledy aktualizováno. Odhad poskytnutý dopravcem a samostatně vypočtená předpověď by měly zůstat rozlišitelné.
Nepřevádějte odhad založený pouze na datu na přesný čas příjezdu. Vaše integrace by také měla zpracovat upravené nebo stažené odhady, aniž by na stránce sledování ponechala zastaralý příslib. Pokud žádný odhad neexistuje, zobrazte, že není k dispozici, místo abyste jej vypočítávali na základě nepodloženého předpokladu.
9. Důvod výjimky a požadované opatření
Informace o výjimce by měla vysvětlovat problém a pokud to zdroj podporuje, uvést opatření, odpovědnou stranu nebo lhůtu. Obecné oznámení o zpoždění se z provozního hlediska liší od žádosti o informace o příjemci.
Nahlášená fakta uchovávejte odděleně od rozhodnutí ve vlastním pracovním postupu. Vaše firma může například po stanovené době bez aktualizace otevřít úkol pro podporu. Jde o interní pravidlo eskalace, nikoli o důkaz, že dopravce prohlásil zásilku za ztracenou. Z nejednoznačného textu sledování negenerujte pokyny k platbě ani žádosti o citlivé informace.
10. Předání mezi dopravci a související sledovací čísla
Pokud zásilka přechází mezi provozovateli, užitečná data zahrnují dalšího dopravce, související sledovací číslo a vztah mezi původními a navazujícími záznamy. To může pomoci zachovat kontinuitu, když je pro doručovací úsek použito jiné identifikační číslo.
Nahlášené předání považujte za vztah, nikoli za důvod k přepsání původního dopravce. Záznamy neslučujte pouze proto, že jejich cíle nebo sledovací čísla vypadají podobně. Pokud vztah není uveden nebo jinak potvrzen, ponechte jej nevyřešený a nevymýšlejte souvislou cestu zásilky.
11. Výsledek doručení a reference na důkaz doručení
Pokud je doručení nahlášeno, měla by odpověď poskytnout zaznamenaný čas doručení a dostupné podrobnosti, například popis bezpečného místa nebo kategorii příjemce. Pokud to dopravce a služba umožňují, může být užitečná také reference na důkaz doručení.
Stav „Doručeno“ by neměl být považován za důkaz, že zásilku osobně převzal zamýšlený příjemce. Podpisy, fotografie, jména a přesná místa mohou obsahovat osobní údaje. Omezte k nim přístup, nezobrazujte tyto podrobnosti na veřejných stránkách sledování a ověřte požadavky na oprávnění nebo platnost odkazů na důkaz doručení.
12. Aktuálnost, stav načtení a metadata odpovědi
Vyžádejte si dostatek metadat k rozlišení poslední události zásilky od posledního úspěšného načtení dat. Mezi užitečné hodnoty patří poslední úspěšná kontrola, poslední neúspěšný pokus, čas vytvoření odpovědi a informace, zda jsou vrácená data uložená v mezipaměti nebo neúplná.
Úspěšný požadavek API sám o sobě nepotvrzuje, že dopravce zveřejnil nový sken. Sémantika odpovědi HTTP popisuje výsledek požadavku; průběh zásilky patří do aplikačních dat. Chyby načtení uchovávejte odděleně od výjimek zásilky, aby se dočasný problém s připojením nestal falešným upozorněním na doručení.
Chybějící data musí mít definovaný význam
Přítomnost pole je pouze částí kontraktu. Váš tým také potřebuje rozumět tomu, co znamená chybějící hodnota. Odhad doručení může být nedostupný u zdroje, dosud nenačtený nebo po doručení nepoužitelný. Tyto situace by neměly automaticky vést ke stejné zprávě pro zákazníka.
- Neznámé: Hodnota dosud nebyla stanovena.
- Neposkytnuté: Zdroj hodnotu v načtených datech neposkytl.
- Nepoužitelné: Pole se na tento záznam nebo stav nevztahuje.
- Načtení se nezdařilo: Systém nemohl dokončit příslušné vyhledání.
Jde o doporučená rozlišení, nikoli o povinné doslovné hodnoty. Ať už zvolíte jakoukoli reprezentaci, zdokumentujte ji. Vyhněte se zástupným datům, prázdným objektům připomínajícím platné záznamy a výchozím souřadnicím, které by mohly být zaměněny za skutečná místa.
Jak otestovat odpověď před integrací
Vyhodnoťte skutečné datové struktury od dopravců, služeb a přepravních tras, které vaše firma používá. Schéma může uvádět volitelné pole, aniž by zaručovalo, že jej každý zdroj naplní. Pro integraci se službou 17TRACK použijte oficiální dokumentaci Tracking API a ověřte kontrakt odpovědi; koncepční názvy polí v této příručce nepovažujte za parametry připravené ke zkopírování.
- Vytvořte reprezentativní vzorek. Zahrňte nově registrované zásilky, aktivní zásilky, pokusy o doručení, dokončená doručení a dostupné případy předání.
- Dohledávejte původ polí v událostech. Ověřte, že zobrazený stav, poslední událost a podrobnosti doručení popisují konzistentní záznam. Rozdíly zkoumejte, místo abyste je skrývali.
- Testujte opožděné a opakované aktualizace. Zpracujte znovu stejné údaje a přijměte starší událost po novější. Ověřte, že ani jeden případ nevytvoří duplicitní oznámení nebo nesprávně nevrátí zobrazený stav.
- Testujte chybějící a nesprávně formátované hodnoty. Zahrňte chybějící odhady, neznámá místa, neznámé kódy stavu a neúplná časová razítka. Aplikace by měla zůstat použitelná, aniž by si vymýšlela náhrady.
- Oddělte selhání přenosu od výsledků sledování. Selhání ověřování, vypršení časového limitu nebo nesprávně formátovaná odpověď patří do cesty chyby integrace, nikoli do pracovního postupu výjimky zásilky.
- Ověřte zobrazení pro zákazníka. Zkontrolujte, že se interní reference, nezpracované diagnostické údaje a osobní informace nepropíší na veřejné stránky ani do oznámení.
U aktualizací založených na webhooku také v dokumentaci poskytovatele ověřte identifikátory doručení, ověřování, chování při opakování a zpracování opakovaného přehrání. Jde o požadavky integrace, nikoli o fakta o zásilce. Váš přijímač by měl bezpečně zpracovávat opakovaná doručení a neměl by předpokládat, že pořadí příchodu odpovídá pořadí událostí.
Kritérium přijetí by mělo být praktické: dokáže vaše aplikace vysvětlit stav zásilky bez nepodložených tvrzení a dokáže váš provozní tým určit další oprávněný krok? Menší, dobře definovaná datová struktura může být užitečnější než větší odpověď plná nevysvětlených volitelných hodnot.
Časté dotazy
Musí být u každé zásilky vyplněno všech 12 skupin údajů?
Ne. Důkazy o doručení, navazující sledovací čísla a odhadovaná data doručení nemusí být dostupné nebo použitelné. Vyžadujte jasné definice polí a předvídatelné chování u chybějících hodnot, nikoli univerzální vyplnění. Ověřte nejdůležitější pole na skutečné skladbě vašich přeprav.
Máme ukládat nezpracovanou odpověď, nebo pouze normalizovaná pole?
Pro aplikační logiku ukládejte normalizovaná pole. Uchování relevantních zdrojových datových struktur může pomoci také při ladění a změnách mapování, s ohledem na vaše požadavky na soukromí, bezpečnost, smlouvy a dobu uchování. Omezte přístup a neuchovávejte citlivý obsah pouze proto, že se v odpovědi objevil.
Které časové razítko by mělo určovat nejnovější událost?
Řiďte se zdokumentovanou chronologií událostí a pravidly pořadí poskytovatele a zohledněte časová pásma a opravy. Čas přijetí říká, kdy se váš systém o události dozvěděl, nikoli nutně kdy k ní došlo. Pokud jsou časová razítka neúplná nebo si odporují, zachovejte nejednoznačnost místo tvrzení o přesném pořadí.
Může API pro sledování potvrdit, že je balík ztracený?
Ztrátu považujte za nahlášenou dopravcem pouze tehdy, pokud zdroj takovou interpretaci výslovně podporuje. Dlouhé období bez skenů může podle vašich provozních pravidel odůvodnit šetření, samotné ticho však ztrátu nepotvrzuje. „Neaktuální sledování“ a „nahlášeno jako ztracené“ uchovávejte jako oddělené pojmy.
Stačí stav „Doručeno“ k uzavření stížnosti zákazníka?
Ne automaticky. Potvrzuje nahlášený výsledek sledování, ale nemusí vyřešit spor příjemce. Prozkoumejte dostupné podrobnosti doručení, účet zákazníka a svůj proces podpory. Se stavovým štítkem nezacházejte jako s náhradou za prověření protichůdných informací.
Zdroje
- Dokumentace 17TRACK Tracking API — produktově specifická reference pro ověření zdokumentovaných polí a chování integrace; výše uvedených 12 skupin představuje redakční doporučení, nikoli kopii jejího schématu.
- RFC 3339: Datum a čas na internetu: časová razítka — reprezentace časových razítek a konvence časových posunů.
- RFC 9110: Sémantika HTTP — sémantika odpovědí HTTP odlišná od obchodního stavu na úrovni zásilky.


