Skip to main content
DomovBlogPríručkyAko zaregistrovať sledovacie číslo prostredníctvom API: polia požiadavky, kódy prepravcov a odpovede

Ako zaregistrovať sledovacie číslo prostredníctvom API: polia požiadavky, kódy prepravcov a odpovede

17TRACK

Ak chcete zaregistrovať číslo zásielky prostredníctvom API, odošlite overenú registračnú požiadavku obsahujúcu sledovacie číslo zásielky a v prípade potreby identifikátor prepravcu. Potom skontrolujte odpoveď pre každú odoslanú zásielku — nielen stav HTTP — a uložte, či bola registrácia úspešná, neúspešná alebo zostáva neistá. Registráciou sa spustí proces sledovania; nepotvrdzuje však, že prepravca zásielku naskenoval alebo že sú už dostupné udalosti sledovania.

Ako zaregistrovať číslo zásielky prostredníctvom polí požiadavky API

Táto príručka je určená vývojárom, ktorí pripájajú systém správy objednávok, skladovú aplikáciu alebo platformu elektronického obchodu k API na sledovanie zásielok. Ako konkrétny príklad integrácie používa 17TRACK a vysvetľuje, ktoré údaje je potrebné overiť v dokumentácii pre vybranú verziu API.

Čo registrácia robí — a čo nerobí

Registračná požiadavka informuje službu sledovania, ktorú zásielku chcete sledovať. Líši sa od zakúpenia prepravného štítku, objednania vyzdvihnutia alebo požiadavky na prepravcu, aby vytvoril zásielku. V typickej integrácii prepravný proces najprv vytvorí číslo zásielky a vaša aplikácia ho následne zaregistruje.

Vo svojej aplikácii oddeľte tieto tri udalosti:

  • Zásielka vytvorená: váš prepravný systém priradil číslo zásielky.
  • Registrácia prijatá: služba sledovania prijala zásielku na sledovanie.
  • Informácie o sledovaní prijaté: udalosti prepravcu sa stali dostupnými prostredníctvom služby sledovania.

Neaktualizujte objednávku na stav „v preprave“ len preto, že registrácia bola úspešná. Novo vytvorený štítok ešte nemusí mať fyzický sken pri prevzatí. Stav zásielky zobrazený zákazníkovi by mal vychádzať z udalostí sledovania interpretovaných podľa vašich pravidiel mapovania stavov, nie z registračnej odpovede.

Pri integráciách 17TRACK začnite na stránke prehľad Tracking API a ako autoritatívny zdroj pre koncové body, definície polí, autentifikáciu a kódy odpovedí používajte oficiálnu dokumentáciu API. Nasledujúce príklady sa zameriavajú na registráciu, nie na samostatné úlohy získavania výsledkov alebo prijímania aktualizácií.

Pred vytvorením volania API pripravte polia požiadavky

Najužitočnejšou prípravou je malá zmluva o poliach medzi vaším prepravným systémom a integráciou sledovania. Určite, odkiaľ každá hodnota pochádza, či môže chýbať a ako sa bude overovať.

Pole alebo hodnotaÚčelImplementačné pravidlo
Číslo zásielkyIdentifikuje zásielku, ktorá sa má sledovať.Uložte a prenášajte ho ako reťazec; zachovajte úvodné nuly.
Identifikátor prepravcuIdentifikuje prepravcu v systéme poskytovateľa sledovania.Použite identifikátor uvedený poskytovateľom, nie interný kód skladu.
Interný odkazPrepája registráciu so záznamom zásielky.Ak je k dispozícii podporované referenčné pole, použite ho; bez ohľadu na to si ponechajte vlastné mapovanie v databáze.
Ďalšie identifikačné údajeMôžu pomôcť identifikovať zásielku, ak prepravca vyžaduje viac než len číslo zásielky.Odosielajte iba polia zdokumentované pre danú integráciu a prepravcu.
Prihlasovací údaj APIOveruje volajúci účet.Uchovávajte ho na serveri a vylúčte ho z aplikačných protokolov.

S číslom zásielky zaobchádzajte ako s identifikátorom

Číslo zásielky nikdy nekonvertujte na celé číslo. Numerická konverzia môže odstrániť úvodné nuly a veľké hodnoty môžu v niektorých programovacích prostrediach stratiť presnosť. Odstráňte náhodné okolité medzery, ale neodstraňujte interpunkciu ani nemeňte veľkosť písmen, pokiaľ to nepodporuje príslušná dokumentácia alebo formát prepravcu.

Pred volaním API overte zjavné vstupné chyby: prázdne reťazce, neočakávané zalomenia riadkov a číslo objednávky skopírované do poľa čísla zásielky. Nevnucujte všetkým prepravcom jednu univerzálnu dĺžku alebo pravidlo pre znaky. Pravidlo vhodné pre jedného prepravcu môže odmietnuť platné čísla iného prepravcu.

Referencie objednávok uchovávajte oddelene od identít zásielok

Objednávka môže obsahovať viacero balíkov a náhradná zásielka môže vytvoriť ďalšie číslo zásielky. Registráciu modelujte na úrovni zásielky alebo balíka, nie s predpokladom jedného čísla zásielky na objednávku.

Ak používate značku alebo referenčné pole podporované poskytovateľom, uprednostnite nepriehľadnú referenciu zásielky pred e-mailovou alebo poštovou adresou zákazníka. Vaša vlastná databáza by mala zostať autoritatívnym prepojením medzi objednávkami, zásielkami, číslami zásielok a mapovaniami prepravcov.

Vyberte správny kód prepravcu

Kód prepravcu nemusí byť univerzálnym priemyselným identifikátorom. Hodnota rozpoznávaná platformou na sledovanie sa môže líšiť od názvu prepravcu uloženého vo vašom prepravnom softvéri. Aj dva systémy, ktoré používajú číselné kódy, môžu rovnakému prepravcovi priradiť odlišné čísla.

Udržiavajte explicitné mapovanie medzi vašou prepravnou službou a identifikátorom prepravcu poskytovateľa sledovania. V prípade potreby rozlišujte regionálnu prevádzku alebo službu prepravcu od jeho širšej značky. Mapovanie založené iba na zobrazovanom názve môže byť nejednoznačné, keď prepravné systémy používajú aliasy.

  • Keď je prepravca známy: použite zdokumentovaný identifikátor prepravcu, ak je podporovaný, najmä ak sa formáty čísel zásielok prekrývajú.
  • Keď prepravca nie je známy: automatickú detekciu používajte iba prostredníctvom zdokumentovaného mechanizmu. Nepredpokladajte, že vynechanie, prázdny reťazec, nula a null znamenajú to isté.
  • Keď výsledok vyzerá nesprávne: pred opakovanou registráciou toho istého čísla overte pôvodný štítok, prepravnú službu a mapovanie.

Automatická detekcia je užitočná, ale nie je dôkazom, že konkrétny prepravca zásielku fyzicky drží. Rovnako platný kód prepravcu nezaručuje, že zadané číslo zásielky patrí tomuto prepravcovi.

Mapovania prepravcov udržiavajte konfigurovateľné namiesto ich rozptýlenia v kóde aplikácie. Zaznamenávajte, kedy bolo mapovanie naposledy overené, a pri každej jeho zmene zahrňte do regresných testov známu zásielku.

Príklad: odoslanie registračnej požiadavky 17TRACK

Nasledujúci príklad ilustruje registračný koncový bod 17TRACK v2.2, autentifikačnú hlavičku 17token a pole obsahujúce jeden objekt s číslom zásielky. Pred nasadením potvrďte, že táto verzia a jej požiadavky na požiadavku zodpovedajú vášmu účtu a oficiálnej dokumentácii. Číslo zásielky je zástupný údaj a musí byť nahradené skutočným identifikátorom zásielky.

curl --request POST \
  --url 'https://api.17track.net/track/v2.2/register' \
  --header "17token: ${TRACKING_API_TOKEN}" \
  --header 'Content-Type: application/json' \
  --data '[
    {
      "number": "YOUR_TRACKING_NUMBER"
    }
  ]'

Tento minimálny príklad neukazuje výber prepravcu ani doplnkové polia špecifické pre prepravcu. V registračnej dokumentácii overte, ako funguje detekcia prepravcu, keď je pole prepravcu vynechané, a či vaša zásielka potrebuje ďalšie informácie. Ak zadávate prepravcu, použite zdokumentované pole carrier a identifikátor očakávaný danou verziou API.

Táto požiadavka by mala byť spustená v serverovom prostredí. Token nevkladajte do verejného obchodu, skriptu prehliadača ani mobilnej aplikácie distribuovanej zákazníkom. Premenná prostredia je vhodná pre lokálny príklad; produkčné nasadenia by mali používať kontroly správy tajomstiev vašej organizácie.

Pred zvýšením objemu otestujte jednu známu zásielku a skontrolujte úplnú odpoveď. Potom otestujte neplatný vstup a dávku obsahujúcu platné aj neplatné položky. Tieto kontroly odhalia, či integrácia skutočne spracúva výsledky na úrovni položiek, a nie iba rozpoznáva úspešnú odpoveď HTTP.

Odpoveď čítajte na troch úrovniach

Spolehlivý spracovateľ odpovede odpovedá na tri samostatné otázky: dostala sa požiadavka k službe, prijala služba operáciu a čo sa stalo s každou zásielkou?

1. Výsledok HTTP a prenosu

Časový limit pripojenia, zlyhanie TLS alebo prerušená odpoveď nemusia nevyhnutne povedať, či server požiadavku spracoval. Tento výsledok označte ako neistý, kým ho nebudete môcť zosúladiť. Úspešný stav HTTP potvrdzuje úspešnú výmenu HTTP, stále však musíte skontrolovať aplikačnú odpoveď.

2. Výsledok na úrovni požiadavky

Skontrolujte zdokumentovaný výsledok najvyššej úrovne API a polia chýb. Chyby autentifikácie, nesprávne formátovaný JSON a obmedzenia účtu si vyžadujú odlišné kroky. Uložte pôvodný kód chyby a správu poskytovateľa namiesto zredukovania každého zlyhania na „sledovanie nie je dostupné“.

Nepredpokladajte, že číselný aplikačný kód má rovnaký význam ako stavový kód HTTP. Ich významy pochádzajú z rôznych vrstiev a musia sa interpretovať oddelene.

3. Výsledok na úrovni zásielky

Pri dávkovej registrácii zohľadnite každú odoslanú položku. Odpoveď môže rozlišovať prijaté a odmietnuté zásielky; syntaktický analyzátor by mal nasledovať presnú schému zdokumentovanú pre vybranú verziu. Neoznačujte celú dávku ako zaregistrovanú len preto, že jedna položka bola úspešná.

Odpovede poskytovateľa normalizujte do vlastných stabilných stavov aplikácie. Vaša databáza môže napríklad používať accepted, rejected a uncertain. Ide o navrhované interné stavy, nie o doslovné hodnoty odpovede 17TRACK. Pôvodnú odpoveď poskytovateľa uchovávajte podľa vhodných pravidiel uchovávania a prístupu, aby mohli vývojári skúmať nezrovnalosti.

Užitočný registračný záznam obsahuje interné ID zásielky, odoslané číslo, výber prepravcu, čas pokusu, verziu API, výsledok a podrobnosti chyby poskytovateľa. Stav registrácie uchovávajte oddelene od stavu doručenia.

Spracúvajte opakovania bez vytvorenia nekonečnej slučky

Pravidlá opakovania by mali závisieť od zlyhania, nie iba od toho, či sa vyskytla výnimka.

  • Neplatný vstup: pred opakovaním opravte pole. Opakovanie nezmenenej nesprávne formátovanej požiadavky pravdepodobne nepomôže.
  • Zlyhanie autentifikácie: overte prihlasovacie údaje a konfiguráciu účtu. Vyhnite sa opakovanému odosielaniu rovnakej zlyhávajúcej dávky.
  • Obmedzenie rýchlosti: dodržiavajte zdokumentované limity a prípadné pokyny na opakovanie. Použite obmedzený exponenciálny odstup namiesto okamžitých paralelných opakovaní.
  • Dočasné zlyhanie služby: opakujte v rámci definovaného rozpočtu pokusov a času.
  • Časový limit po odoslaní: pred predpokladaním, že prvý pokus zlyhal, zosúlaďte stav registrácie zásielky pomocou zdokumentovaného správania API.
  • Odpoveď súvisiaca s duplicitou: overte, či už zásielka nie je zaregistrovaná a správne priradená k záznamu vašej aplikácie.

Nepredpokladajte, že registrácia je idempotentná, pokiaľ dokumentácia toto správanie nedefinuje. Deduplicácia na strane aplikácie znižuje náhodné opakované odoslania, ale neurčuje pravidlá poskytovateľa pre spracovanie duplicít.

Použite interné pravidlo jedinečnosti vhodné pre váš model zásielok. Samotné číslo zásielky nemusí byť dostatočným trvalým kľúčom naprieč prepravcami a dlhými obdobiami uchovávania. Zachovajte kontext prepravcu a vlastný identifikátor zásielky a zdokumentujte spracovanie náhrad a opravených čísel.

Registráciu monitorujte oddelene od aktualizácií sledovania

Monitorovanie API by malo rozlišovať zlyhanie integrácie od zásielky, pri ktorej jednoducho nedošlo k novej udalosti prepravcu. Tieto podmienky si vyžadujú rôznych zodpovedných pracovníkov a odlišné opravy.

Pri registrácii monitorujte počty prijatí a odmietnutí, kategórie chýb, neisté výsledky, nevybavené opakovania a latenciu odpovedí. Pri následnom sledovaní monitorujte prijímanie aktualizácií alebo zlyhania získavania samostatne. Číselné prahové hodnoty upozornení stanovte až po pochopení bežnej prevádzky a zdokumentovaných prevádzkových limitov poskytovateľa.

Praktická produkčná kontrola by mala zodpovedať:

  1. Má každá zásielka čakajúca na sledovanie registračný záznam?
  2. Dá sa každá prijatá registrácia spätne vysledovať k správnemu balíku?
  3. Sú odmietnuté položky smerované k osobe, ktorá môže opraviť základné údaje?
  4. Sú neisté požiadavky zosúlaďované namiesto opustenia alebo nekonečného opakovania?
  5. Vychádzajú stavy zobrazené zákazníkom z udalostí zásielky, nie z prijatia registrácie?
  6. Sú prihlasovacie údaje a nepotrebné osobné údaje vylúčené z protokolov?

Pri prevádzke elektronického obchodu je operačné odovzdanie rovnako dôležité ako samotné volanie API. Vývojári by mali zodpovedať za zlyhania prenosu a analýzy; prepravné alebo realizačné tímy by mali vedieť preskúmať nesprávne štítky, mapovania prepravcov a chýbajúce informácie o zásielkach.

Často kladené otázky

Môžem zaregistrovať číslo zásielky pred prvým skenom prepravcu?

Registrácia a skeny prepravcu sú samostatné udalosti. Služba môže prijať číslo ešte pred sprístupnením udalostí sledovania, v závislosti od svojich validačných pravidiel. Prijatie neinterpretujte ako dôkaz, že prepravca zásielku prevzal.

Musím vždy poskytnúť kód prepravcu?

Závisí to od zdokumentovaného správania detekcie API a príslušnej zásielky. Ak je prepravca známy, explicitný a správne namapovaný identifikátor môže znížiť nejednoznačnosť. Ak nie je známy, použite zdokumentovanú metódu automatickej detekcie namiesto vymýšľania hodnoty prepravcu.

Prečo API vrátilo úspech HTTP, keď zásielka zlyhala?

Požiadavka HTTP môže byť úspešná, zatiaľ čo aplikácia odmietne jednotlivú položku. Prečítajte výsledok aplikácie na najvyššej úrovni aj výsledky na úrovni zásielky. Toto rozlíšenie je obzvlášť dôležité pri dávkových požiadavkách.

Čo mám urobiť, keď registračnej požiadavke vyprší časový limit?

Výsledok považujte za neistý. Server mohol požiadavku spracovať ešte pred zlyhaním pripojenia. Skontrolujte zdokumentované správanie poskytovateľa pri duplicitách a dostupné metódy vyhľadávania registrácie alebo sledovania, potom vykonajte zosúladenie alebo opakovanie v rámci obmedzenej politiky.

Konfiguruje registrácia automaticky upozornenia na sledovanie?

Nepredpokladajte, že áno. Registrácia, získavanie údajov o sledovaní a konfigurácia webhookov sú samostatné aspekty integrácie. Overte príslušnú dokumentáciu a pred spoliehaním sa na túto funkciu pri upozorneniach zákazníkov otestujte celú cestu aktualizácie.

Zdroje

  • Dokumentácia API 17TRACK — referencia pre registračné koncové body, autentifikáciu, polia požiadaviek, identifikátory prepravcov, schémy odpovedí a spracovanie chýb. Podrobnosti implementácie prispôsobte verzii API, ktorú nasadzujete.
  • Prehľad Tracking API 17TRACK — oficiálny východiskový bod pre produkt tracking API a zdroje pre integráciu vývojárov.