Skip to main content
DomovBlogPríručkyAké údaje by malo rozhranie API na sledovanie vracať? 12 polí okrem aktuálneho stavu?

Aké údaje by malo rozhranie API na sledovanie vracať? 12 polí okrem aktuálneho stavu?

17TRACK

Aplikačné rozhranie API na sledovanie zásielok by malo vracať viac než len označenie, napríklad „Na ceste“. Okrem aktuálneho stavu hľadajte identifikátory zásielky, identitu dopravcu, podrobné informácie o stave, pôvodné správy dopravcu, históriu udalostí, časové pečiatky udalostí, lokality, odhady doručenia, výnimky, odovzdanie zásielky medzi dopravcami, podrobnosti o doručení a metadáta o aktuálnosti údajov. Týchto 12 skupín údajov spoločne pomáha vývojárom vytvárať spoľahlivé pracovné postupy a prevádzkovým tímom poskytuje dostatok kontextu na prijatie opatrení.

What Data Should a Tracking API Return 12 Fields Beyond

Ide o odporúčanú zmluvu odpovede pre vývojárov, technických nákupcov a tímy elektronického obchodu, nie o tvrdenie, že každý dopravca alebo API poskytuje každé pole. Niektoré hodnoty budú oprávnene nedostupné. Lepší návrh tieto medzery jasne označí namiesto ich vypĺňania domnienkami.

Čo robí údaje o sledovaní užitočnými?

Aktuálny stav odpovedá na jednu úzku otázku: aký je zhrnutý stav zásielky? Nemusí však vysvetľovať, čo sa stalo, kedy sa to stalo, či sú informácie aktuálne alebo čo by mal niekto urobiť ďalej.

Napríklad dve zásielky môžu mať obe stav „Na ceste“, no vyžadovať odlišné reakcie. Jedna môže mať nedávny sken v zariadení a žiadny nahlásený problém. Druhá môže mať v histórii udalostí zaznamenaný nevyriešený problém s adresou. Aplikácia, ktorá číta iba hlavný stav, môže tento rozdiel prehliadnuť.

Odpoveď posudzujte podľa troch praktických úloh: priradenie zásielky k správnej objednávke, presné vysvetlenie jej priebehu a rozhodnutie, či je opodstatnené prijať opatrenie. Nasledujúce polia tieto úlohy podporujú. Názvy polí sú ilustračné; nejde o univerzálny štandard ani schému konkrétneho poskytovateľa.

12 polí, ktoré treba posudzovať nad rámec aktuálneho stavu

1. Identifikátory zásielky a sledovania

Odpoveď by mala identifikovať opisovanú zásielku. Užitočné hodnoty zahŕňajú zadané sledovacie číslo, identifikátor záznamu sledovania v API a referenciu klienta, ktorú môže váš systém namapovať na záznam o plnení alebo balíku.

Nepredpokladajte, že jedna objednávka sa rovná jednej zásielke. Objednávka môže byť rozdelená do viacerých balíkov a náhradná zásielka môže vytvoriť ďalšiu zásielku. Záznamy o sledovaní ukladajte na úrovni balíka alebo plnenia a následne ich priraďte k objednávke. Sledovacie čísla uchovávajte ako reťazce, aby sa nestratilo formátovanie ani úvodné nuly.

2. Identita dopravcu

Hľadajte stabilný identifikátor dopravcu spolu s čitateľným názvom dopravcu. Ak je to možné, odpoveď by mala rozlišovať dopravcu výslovne zadaného vašou aplikáciou od dopravcu vybraného automatickou detekciou.

Kontext dopravcu je dôležitý pri interpretácii sledovacieho čísla a jeho udalostí. Ak je detekcia nejednoznačná, integrácia by mala umožniť jej vyriešenie namiesto tichého prezentovania neistého výsledku ako potvrdenej zhody. Informácie o úrovni služby uchovávajte oddelene: samotný názov dopravcu nepotvrdzuje, či zásielka využíva expresnú, poštovú alebo inú službu.

3. Normalizované podrobnosti o stave

Popri hlavnom stave si vyžiadajte zdokumentovaný kód podrobností alebo podstav. Široká kategória môže zásielku označiť ako výnimku, zatiaľ čo podrobnosť identifikuje neúspešný pokus o doručenie, problém s adresou alebo zadržanie súvisiace s colným konaním.

Na obchodnú logiku používajte stabilné kódy a na prezentáciu čitateľné označenia. Overte, ako poskytovateľ mapuje udalosti dopravcu na tieto kódy vrátane spôsobu spracovania neznámych alebo nenamapovaných udalostí. Normalizované označenie uľahčuje využívanie údajov od rôznych dopravcov, nemalo by však vymazať rozdiely potrebné pre váš tím podpory.

4. Pôvodné správy a kódy dopravcu

Ak sú k dispozícii, uchovávajte pôvodný opis udalosti a kód udalosti dopravcu. Tieto hodnoty poskytujú pracovníkom podpory kontext, ktorý môže v normalizovanom stave chýbať, najmä keď dopravca používa konkrétnu prevádzkovú formuláciu.

Pôvodný text uchovávajte oddelene od preložených alebo prepísaných opisov. Inak môže byť vysvetlenie určené zákazníkovi omylom považované za presné znenie dopravcu. Text dopravcu pri zobrazovaní považujte za nedôveryhodný vstup: správne ho escapujte a nevykresľujte ho ako spustiteľný HTML kód.

5. História udalostí sledovania

Užitočná odpoveď by mala sprístupniť časovú os zásielky, nielen jej poslednú udalosť. Každá udalosť by mala v ideálnom prípade obsahovať identifikátor, stav alebo kód, opis, časovú pečiatku a dostupné informácie o lokalite.

Overte, či API vracia úplnú históriu, obmedzené časové obdobie alebo stránkované výsledky. Stanovte tiež, ako sa reprezentujú opravy a duplicitné pozorovania. Aplikácia by nemala predpokladať, že prvá položka je vždy najnovšia, pokiaľ zmluva odpovede výslovne nezaručuje toto poradie.

6. Časové pečiatky udalostí a informácie o časovom pásme

Čas, keď k udalosti došlo, sa líši od času, keď ju API prijalo alebo vrátilo. Ak je to možné, uchovávajte oba údaje. Toto rozlíšenie pomáha vysvetliť, prečo môže novo prijatá aktualizácia opisovať niečo, čo sa stalo skôr.

Vyžadujte časové pečiatky s explicitným posunom UTC alebo zápisom UTC. RFC 3339 definuje formát časovej pečiatky vhodný pre internetové protokoly vrátane číselných časových posunov. Ak zdroj poskytuje iba miestny čas bez známeho posunu, uchovajte túto neistotu namiesto tichého považovania času za UTC. Nikdy nenaznačujte presnosť na úrovni sekúnd, ak zdroj poskytuje iba dátum.

7. Lokality udalostí a geografia zásielky

Ak sú k dispozícii, hľadajte štruktúrované súčasti lokality, napríklad mesto, región, krajinu a poštové smerovacie číslo. Ak by prevod na štruktúrované polia mohol viesť k strate významu, uchovávajte aj nespracovaný reťazec lokality.

Lokalita skenu nemusí byť aktuálnou polohou balíka. Rovnako posledné nahlásené zariadenie nie je dôkazom, že sa tam balík stále nachádza. Stránky určené zákazníkom by ho mali označiť ako poslednú nahlásenú lokalitu. Z neúplného textu skenu neodvodzujte súradnice ani presnú doručovaciu adresu.

8. Odhadovaný dátum alebo interval doručenia

Odhadované doručenie by malo uvádzať, či obsahuje jeden dátum alebo interval, kto ho vytvoril a kedy bol naposledy aktualizovaný. Odhad poskytnutý dopravcom musí zostať odlíšiteľný od samostatne vypočítanej predikcie.

Odhad obsahujúci iba dátum neprevádzajte na presný čas príchodu. Integrácia by mala zvládnuť aj upravené alebo zrušené odhady bez ponechania neaktuálneho prísľubu na stránke sledovania. Ak odhad neexistuje, zobrazte, že nie je k dispozícii, namiesto jeho výpočtu na základe nepodloženej domnienky.

9. Dôvod výnimky a požadované opatrenie

Informácie o výnimke by mali vysvetľovať problém a, ak to zdroj podporuje, identifikovať opatrenie, zodpovednú stranu alebo termín. Všeobecné oznámenie o meškaní sa z prevádzkového hľadiska líši od požiadavky na informácie o príjemcovi.

Nahlásené fakty uchovávajte oddelene od vlastných rozhodnutí v pracovnom postupe. Vaša firma môže napríklad po nastavenom čase bez aktualizácie vytvoriť úlohu pre podporu. Ide o interné pravidlo eskalácie, nie o dôkaz, že dopravca vyhlásil balík za stratený. Z nejednoznačného textu sledovania nevytvárajte pokyny na platbu ani žiadosti o citlivé informácie.

10. Odovzdanie medzi dopravcami a súvisiace sledovacie čísla

Ak zásielka prechádza medzi prevádzkovateľmi, užitočné údaje zahŕňajú ďalšieho dopravcu, súvisiace sledovacie číslo a vzťah medzi pôvodným a následným záznamom. To môže pomôcť zachovať kontinuitu, keď sa pri doručovaní používa iný identifikátor.

Nahlásené odovzdanie považujte za vzťah a pôvodného dopravcu neprepíšte. Záznamy nespájajte iba preto, že ich cieľové miesta alebo sledovacie čísla vyzerajú podobne. Ak vzťah nie je poskytnutý ani inak potvrdený, ponechajte ho nevyriešený namiesto vymýšľania súvislej cesty.

11. Výsledok doručenia a odkazy na dôkazy

Ak je doručenie nahlásené, odpoveď by mala poskytnúť zaznamenaný čas doručenia a všetky dostupné podrobnosti, napríklad opis bezpečného miesta alebo kategóriu príjemcu. Odkaz na potvrdenie o doručení môže byť užitočný, ak ho dopravca a služba poskytujú.

Stav doručené by sa nemal považovať za dôkaz, že balík osobne prevzal zamýšľaný príjemca. Podpisy, fotografie, mená a presné lokality môžu obsahovať osobné údaje. Obmedzte prístup, tieto podrobnosti nezverejňujte na verejných stránkach sledovania a overte požiadavky na oprávnenie alebo platnosť odkazov na dôkazy.

12. Aktuálnosť, stav načítania a metadáta odpovede

Vyžiadajte si dostatok metadát na rozlíšenie najnovšej udalosti zásielky od posledného úspešného načítania údajov. Užitočné hodnoty zahŕňajú poslednú úspešnú kontrolu, posledný neúspešný pokus, čas vytvorenia odpovede a informáciu, či sú vrátené údaje z vyrovnávacej pamäte alebo čiastočné.

Úspešná požiadavka API sama osebe nepotvrdzuje, že dopravca zverejnil nový sken. Sémantika HTTP odpovede opisuje výsledok požiadavky; priebeh zásielky patrí do aplikačných údajov. Chyby načítania uchovávajte oddelene od výnimiek zásielky, aby sa dočasný problém s pripojením nezmenil na falošné upozornenie o doručení.

Chýbajúce údaje musia mať definovaný význam

Prítomnosť poľa je iba časťou zmluvy. Váš tím musí rozumieť aj tomu, čo znamená chýbajúca hodnota. Odhad doručenia môže byť nedostupný v zdroji, ešte nebol načítaný alebo po doručení nie je relevantný. Tieto situácie by nemali automaticky viesť k rovnakej správe pre zákazníka.

  • Neznáme: Hodnota ešte nebola určená.
  • Neposkytnuté: Zdroj túto hodnotu v načítaných údajoch neposkytol.
  • Neuplatňuje sa: Pole sa na tento záznam alebo stav nevzťahuje.
  • Načítanie zlyhalo: Systém nemohol dokončiť príslušné vyhľadanie.

Ide o odporúčané rozlíšenia, nie o povinné doslovné hodnoty. Bez ohľadu na zvolenú reprezentáciu ju zdokumentujte. Vyhnite sa zástupným dátumom, prázdnym objektom pripomínajúcim platné záznamy a predvoleným súradniciam, ktoré by mohli byť považované za skutočné lokality.

Ako otestovať odpoveď pred integráciou

Vyhodnoťte skutočné dátové výstupy od dopravcov, služieb a prepravných trás, ktoré vaša firma používa. Schéma môže uvádzať voliteľné pole bez záruky, že ho každý podkladový zdroj naplní. Pri integrácii so 17TRACK použite oficiálnu dokumentáciu Tracking API na kontrolu zmluvy odpovede namiesto toho, aby ste koncepčné názvy polí v tejto príručke považovali za parametre pripravené na kopírovanie.

  1. Vytvorte reprezentatívnu vzorku. Zahrňte novoregistrované zásielky, aktívne zásielky, pokusy o doručenie, dokončené doručenia a dostupné prípady odovzdania.
  2. Vystopujte polia späť k udalostiam. Overte, že zobrazený stav, najnovšia udalosť a podrobnosti o doručení opisujú konzistentný záznam. Nezhody skúmajte namiesto ich skrývania.
  3. Testujte oneskorené a opakované aktualizácie. Znova spracujte rovnaký dátový výstup a prijmite staršiu udalosť po novšej. Overte, že ani jeden prípad nevytvorí duplicitné upozornenia ani nesprávne nevráti zobrazený stav.
  4. Testujte chýbajúce a nesprávne formátované hodnoty. Zahrňte chýbajúce odhady, neznáme lokality, neznáme kódy stavov a neúplné časové pečiatky. Aplikácia musí zostať použiteľná bez vymýšľania náhrad.
  5. Oddeľte zlyhania prenosu od výsledkov sledovania. Zlyhanie autentifikácie, vypršanie časového limitu alebo nesprávne formátovaná odpoveď má patriť do chybovej vetvy integrácie, nie do pracovného postupu výnimky zásielky.
  6. Overte zobrazenie pre zákazníka. Skontrolujte, že interné referencie, nespracované diagnostické podrobnosti a osobné údaje neuniknú na verejné stránky ani do upozornení.

Pri aktualizáciách založených na webhookoch skontrolujte v dokumentácii poskytovateľa aj identifikátory doručenia, autentifikáciu, správanie pri opakovaní a spracovanie prehratia. Ide o požiadavky integrácie, nie o fakty o zásielke. Prijímač musí bezpečne spracovať opakované doručenia a nemal by predpokladať, že poradie prijatia sa rovná poradiu udalostí.

Kritérium prijatia by malo byť praktické: dokáže vaša aplikácia vysvetliť zásielku bez nepodložených tvrdení a dokáže váš prevádzkový tím určiť ďalšie opodstatnené opatrenie? Menší, dobre definovaný dátový výstup môže byť užitočnejší než väčšia odpoveď plná nevysvetlených voliteľných hodnôt.

Často kladené otázky

Musí mať každá zásielka vyplnených všetkých 12 skupín údajov?

Nie. Dôkazy o doručení, následné sledovacie čísla a odhadované dátumy doručenia nemusia byť dostupné alebo relevantné. Vyžadujte jasné definície polí a predvídateľné správanie pri chýbajúcich hodnotách, nie univerzálne vyplnenie. Najdôležitejšie polia overte voči skutočnej skladbe vašich prepráv.

Máme ukladať nespracovanú odpoveď alebo iba normalizované polia?

Pre aplikačnú logiku ukladajte normalizované polia. Uchovanie relevantných zdrojových dátových výstupov môže pomôcť aj pri ladení a zmenách mapovania, v súlade s požiadavkami na ochranu súkromia, bezpečnosť, zmluvy a uchovávanie údajov. Obmedzte prístup a neuchovávajte citlivý obsah iba preto, že sa objavil v odpovedi.

Ktorá časová pečiatka má určovať najnovšiu udalosť?

Použite zdokumentovanú chronológiu udalostí a pravidlá poradia poskytovateľa s prihliadnutím na časové pásma a opravy. Čas prijatia vám hovorí, kedy sa váš systém o udalosti dozvedel, nie nevyhnutne kedy nastala. Ak sú časové pečiatky neúplné alebo si odporujú, zachovajte nejednoznačnosť namiesto tvrdenia o presnom poradí.

Môže API na sledovanie potvrdiť, že sa balík stratil?

Stratu považujte za nahlásenú dopravcom iba vtedy, keď zdroj takúto interpretáciu výslovne podporuje. Dlhé obdobie bez skenov môže podľa vašich prevádzkových pravidiel odôvodniť preverenie, samotné ticho však stratu nepotvrdzuje. „Neaktuálne sledovanie“ a „nahlásená strata“ uchovávajte ako oddelené pojmy.

Stačí stav doručené na uzavretie sťažnosti zákazníka?

Nie automaticky. Potvrdzuje nahlásený výsledok sledovania, nemusí však vyriešiť spor príjemcu. Preskúmajte dostupné podrobnosti o doručení, účet zákazníka a svoj proces podpory. Označenie stavu nepovažujte za náhradu skúmania protichodných informácií.

Zdroje