Skip to main content
DomůBlogPrůvodciJak zaregistrovat sledovací číslo prostřednictvím API: pole požadavku, kódy dopravců a odpovědi

Jak zaregistrovat sledovací číslo prostřednictvím API: pole požadavku, kódy dopravců a odpovědi

17TRACK

Chcete-li zaregistrovat sledovací číslo prostřednictvím API, odešlete ověřený registrační požadavek obsahující sledovací číslo zásilky a v případě potřeby také identifikátor přepravce. Poté zkontrolujte odpověď u každé odeslané zásilky — nejen stav HTTP — a uložte, zda registrace proběhla úspěšně, selhala nebo zůstává nejistá. Registrace zahajuje proces sledování; nedokazuje však, že přepravce zásilku naskenoval nebo že jsou již k dispozici události sledování.

Jak zaregistrovat sledovací číslo prostřednictvím polí požadavku API

Tato příručka je určena vývojářům, kteří propojují systém správy objednávek, skladovou aplikaci nebo platformu elektronického obchodu s API pro sledování. Jako konkrétní příklad integrace používá 17TRACK a vysvětluje, které údaje je nutné ověřit v dokumentaci pro vámi zvolenou verzi API.

Co registrace dělá — a co nedělá

Registrační požadavek informuje službu sledování, kterou zásilku chcete sledovat. Liší se od nákupu přepravního štítku, objednání vyzvednutí nebo požadavku, aby přepravce vytvořil zásilku. V typické integraci přepravní proces nejprve vytvoří sledovací číslo a vaše aplikace toto číslo následně zaregistruje.

Ve své aplikaci uchovávejte tyto tři události odděleně:

  • Zásilka vytvořena: váš přepravní systém přiřadil sledovací číslo.
  • Registrace přijata: služba sledování přijala zásilku ke sledování.
  • Obdrženy informace o sledování: události přepravce se staly dostupnými prostřednictvím služby sledování.

Neměňte stav objednávky na „na cestě“ jen proto, že registrace proběhla úspěšně. Nově vytvořený štítek ještě nemusí mít fyzický sken potvrzující převzetí. Stav zásilky zobrazovaný zákazníkům by měl vycházet z událostí sledování interpretovaných podle vašich pravidel mapování stavů, nikoli z odpovědi registrace.

U integrací 17TRACK začněte na stránce Přehled Tracking API a jako autoritativní zdroj pro koncové body, definice polí, ověřování a kódy odpovědí používejte oficiální dokumentaci API. Níže uvedené příklady se zaměřují na registraci, nikoli na samostatné úlohy načítání výsledků nebo přijímání aktualizací.

Před vytvořením volání API připravte pole požadavku

Nejužitečnější přípravou je malá specifikace polí mezi vaším přepravním systémem a integrací sledování. Rozhodněte, odkud každá hodnota pochází, zda může chybět a jak bude ověřována.

Pole nebo hodnotaÚčelPravidlo implementace
Sledovací čísloIdentifikuje zásilku, která má být sledována.Ukládejte je a přenášejte jako řetězec; zachovejte počáteční nuly.
Identifikátor přepravceIdentifikuje přepravce v systému poskytovatele sledování.Použijte identifikátor uvedený v dokumentaci poskytovatele, nikoli interní kód skladu.
Interní referencePropojuje registraci se záznamem vaší zásilky.Je-li k dispozici, použijte podporované referenční pole; vlastní mapování v databázi však uchovávejte vždy.
Další identifikační údajeMohou pomoci identifikovat zásilku, pokud přepravce vyžaduje více než její sledovací číslo.Odesílejte pouze pole zdokumentovaná pro danou integraci a přepravce.
Přihlašovací údaje APIOvěřují účet, který volání provádí.Uchovávejte je na serveru a vylučte je z aplikačních protokolů.

Se sledovacím číslem zacházejte jako s identifikátorem

Sledovací číslo nikdy nepřevádějte na celé číslo. Numerická konverze může odstranit počáteční nuly a velké hodnoty mohou v některých programovacích prostředích ztratit přesnost. Odstraňte náhodné mezery na začátku a na konci, ale neodstraňujte interpunkci ani neměňte velikost písmen, pokud takovou normalizaci nepodporuje příslušná dokumentace nebo formát přepravce.

Před voláním API ověřte zjevné vstupní chyby: prázdné řetězce, neočekávané konce řádků a číslo objednávky vložené do pole sledovacího čísla. Nepoužívejte jedno univerzální pravidlo délky nebo znaků pro všechny přepravce. Pravidlo vhodné pro jednoho přepravce může odmítnout platná čísla jiného přepravce.

Udržujte reference objednávek oddělené od identit zásilek

Objednávka může obsahovat více balíků a náhradní zásilka může mít jiné sledovací číslo. Registraci modelujte na úrovni zásilky nebo balíku, nikoli za předpokladu, že každá objednávka má jedno sledovací číslo.

Pokud používáte značku nebo referenční pole podporované poskytovatelem, upřednostněte neprůhlednou referenci zásilky před e-mailovou nebo poštovní adresou zákazníka. Vaše vlastní databáze by měla zůstat autoritativním propojením mezi objednávkami, zásilkami, sledovacími čísly a mapováním přepravců.

Vyberte správný kód přepravce

Kód přepravce nemusí být univerzálním průmyslovým identifikátorem. Hodnota rozpoznávaná platformou pro sledování se může lišit od názvu přepravce uloženého ve vašem přepravním softwaru. Dokonce i dva systémy používající číselné kódy mohou stejnému přepravci přiřadit různá čísla.

Udržujte explicitní mapování mezi svou přepravní službou a identifikátorem přepravce u poskytovatele sledování. V případě potřeby rozlišujte regionální provoz nebo službu přepravce od jeho širší značky. Mapování založené pouze na zobrazovaném názvu může být nejednoznačné, pokud přepravní systémy používají aliasy.

  • Když je přepravce znám: pokud je podporován, použijte identifikátor přepravce uvedený v dokumentaci, zejména pokud se formáty sledovacích čísel překrývají.
  • Když přepravce není znám: automatickou detekci používejte pouze prostřednictvím zdokumentovaného mechanismu. Nepředpokládejte, že vynechání, prázdný řetězec, nula a null znamenají totéž.
  • Když výsledek vypadá nesprávně: před opakovanou registrací stejného čísla ověřte původní štítek, přepravní službu a mapování.

Automatická detekce je užitečná, ale není důkazem, že konkrétní přepravce zásilku fyzicky drží. Stejně tak platný kód přepravce nezaručuje, že zadané sledovací číslo tomuto přepravci patří.

Mapování přepravců udržujte konfigurovatelné, místo abyste je rozptýlili v kódu aplikace. Zaznamenávejte, kdy bylo mapování naposledy ověřeno, a při každé jeho změně zahrňte do regresních testů známou zásilku.

Příklad: odeslání registračního požadavku 17TRACK

Následující příklad ilustruje registrační koncový bod 17TRACK v2.2, ověřovací hlavičku 17token a pole obsahující jeden objekt sledovacího čísla. Před nasazením ověřte, že tato verze a její požadavky odpovídají vašemu účtu a oficiální dokumentaci. Sledovací číslo je zástupný údaj a musí být nahrazeno skutečným identifikátorem zásilky.

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ální příklad neukazuje výběr přepravce ani doplňková pole specifická pro přepravce. V dokumentaci registrace ověřte, jak funguje detekce přepravce při vynechání pole přepravce a zda vaše zásilka potřebuje další údaje. Pokud přepravce zadáváte, použijte zdokumentované pole carrier a identifikátor očekávaný danou verzí API.

Tento požadavek spouštějte v prostředí na straně serveru. Token nevkládejte do veřejného obchodu, skriptu v prohlížeči ani mobilní aplikace distribuované zákazníkům. Proměnná prostředí je vhodná pro místní příklad; produkční nasazení by měla používat mechanismy vaší organizace pro správu tajných údajů.

Před zvýšením objemu otestujte jednu známou zásilku a zkontrolujte úplnou odpověď. Poté otestujte neplatný vstup a dávku obsahující platné i neplatné položky. Tyto kontroly odhalí, zda vaše integrace skutečně zpracovává výsledky na úrovni položek, a ne pouze rozpoznává úspěšnou odpověď HTTP.

Čtěte odpověď na třech úrovních

Spolehlivý obslužný program odpovědi odpovídá na tři samostatné otázky: dorazil požadavek ke službě, přijala služba operaci a co se stalo s každou zásilkou?

1. Výsledek HTTP a přenosu

Časový limit připojení, selhání TLS nebo přerušená odpověď nemusí nutně říkat, zda server požadavek zpracoval. Dokud jej nedokážete sladit, označte výsledek jako nejistý. Úspěšný stav HTTP potvrzuje úspěšnou výměnu HTTP, stále však musíte zkontrolovat odpověď aplikace.

2. Výsledek na úrovni požadavku

Zkontrolujte zdokumentovaný výsledek na nejvyšší úrovni API a pole chyb. Chyby ověření, neplatný JSON a omezení účtu vyžadují odlišné kroky. Ukládejte původní kód chyby a zprávu poskytovatele, místo abyste každé selhání redukovali na „sledování není k dispozici“.

Nepředpokládejte, že číselný kód aplikace má stejný význam jako stavový kód HTTP. Jejich významy pocházejí z různých vrstev a musí být interpretovány odděleně.

3. Výsledek na úrovni zásilky

Při dávkové registraci zohledněte každou odeslanou položku. Odpověď může rozlišovat přijaté a odmítnuté zásilky; analyzátor by měl přesně dodržovat schéma zdokumentované pro vybranou verzi. Neoznačujte celou dávku jako zaregistrovanou jen proto, že jedna položka uspěla.

Normalizujte odpovědi poskytovatele do vlastních stabilních stavů aplikace. Databáze může například používat accepted, rejected a uncertain. Jde o navrhované interní stavy, nikoli o doslovné hodnoty odpovědí 17TRACK. Původní odpověď poskytovatele uchovávejte podle odpovídajících pravidel uchovávání a přístupu, aby vývojáři mohli zkoumat nesrovnalosti.

Užitečný záznam registrace obsahuje interní ID zásilky, odeslané číslo, výběr přepravce, čas pokusu, verzi API, výsledek a podrobnosti chyby poskytovatele. Stav registrace udržujte odděleně od stavu doručení.

Řiďte opakované pokusy, aniž by vznikla nekonečná smyčka

Pravidla opakování by měla záviset na selhání, nikoli pouze na tom, zda došlo k výjimce.

  • Neplatný vstup: před opakováním opravte pole. Opakované odesílání nezměněného chybného požadavku pravděpodobně nepomůže.
  • Selhání ověření: ověřte přihlašovací údaje a konfiguraci účtu. Vyhněte se opakovanému odesílání stejné neúspěšné dávky.
  • Omezení rychlosti: dodržujte zdokumentované limity a případné pokyny k opakování. Používejte omezený backoff místo okamžitých paralelních pokusů.
  • Dočasné selhání služby: opakujte pokus v rámci definovaného limitu počtu pokusů a času.
  • Časový limit po odeslání: předpokladem selhání prvního pokusu nebuďte, dokud stav registrace zásilky nesladíte podle zdokumentovaného chování API.
  • Odpověď související s duplicitou: ověřte, zda zásilka již není zaregistrována a správně propojena se záznamem vaší aplikace.

Nepředpokládejte, že registrace je idempotentní, pokud to dokumentace výslovně nedefinuje. Deduplicace na straně aplikace omezuje náhodné opakované odesílání, nestanovuje však zásady poskytovatele pro zpracování duplicit.

Používejte pravidlo interní jedinečnosti vhodné pro váš model zásilek. Samotné sledovací číslo nemusí být dostatečným trvalým klíčem napříč přepravci a dlouhými dobami uchovávání. Zachovejte kontext přepravce a vlastní identifikátor zásilky a zdokumentujte, jak se zpracovávají náhradní a opravená čísla.

Monitorujte registraci odděleně od aktualizací sledování

Monitorování API by mělo rozlišovat selhání integrace od zásilky, u které jednoduše není k dispozici nová událost přepravce. Tyto podmínky vyžadují různé vlastníky i různá řešení.

U registrace sledujte počty přijetí a odmítnutí, kategorie chyb, nejisté výsledky, nevyřízené opakované pokusy a latenci odpovědí. U následného sledování sledujte příjem aktualizací nebo selhání načítání odděleně. Číselné prahové hodnoty upozornění nepřiřazujte, dokud neporozumíte běžnému provozu a zdokumentovaným provozním limitům poskytovatele.

Praktická produkční kontrola by měla zodpovědět:

  1. Má každá zásilka čekající na sledování záznam registrace?
  2. Lze každou přijatou registraci dohledat ke správnému balíku?
  3. Jsou odmítnuté položky předávány někomu, kdo může opravit zdrojová data?
  4. Jsou nejisté požadavky sladěny, nikoli opuštěny nebo opakovány bez omezení?
  5. Vycházejí stavy zobrazované zákazníkům z událostí zásilky, nikoli z přijetí registrace?
  6. Jsou přihlašovací údaje a nepotřebné osobní údaje vyloučeny z protokolů?

U provozu elektronického obchodu je předání do provozu stejně důležité jako samotné volání API. Vývojáři by měli vlastnit selhání přenosu a analýzy; přepravní nebo expediční týmy by měly být schopny řešit nesprávné štítky, mapování přepravců a chybějící informace o zásilkách.

Časté dotazy

Mohu zaregistrovat sledovací číslo před prvním skenem přepravce?

Registrace a skeny přepravce jsou oddělené události. Služba může přijmout číslo ještě před zpřístupněním událostí sledování, v závislosti na svých pravidlech ověřování. Přijetí nevykládejte jako důkaz, že přepravce zásilku převzal.

Musím vždy zadat kód přepravce?

Záleží na zdokumentovaném chování detekce API a na konkrétní zásilce. Pokud je přepravce znám, explicitní a správně namapovaný identifikátor může snížit nejednoznačnost. Pokud znám není, použijte zdokumentovanou metodu automatické detekce, místo abyste hodnotu přepravce vymýšleli.

Proč API vrátilo úspěch HTTP, když zásilka selhala?

Požadavek HTTP může uspět, zatímco aplikace odmítne jednotlivou položku. Přečtěte výsledek aplikace na nejvyšší úrovni i výsledky na úrovni zásilky. Toto rozlišení je obzvláště důležité u dávkových požadavků.

Co mám dělat, když registrační požadavek vyprší?

Výsledek považujte za nejistý. Server mohl požadavek zpracovat ještě před selháním připojení. Ověřte zdokumentované chování poskytovatele při duplicitách a dostupné metody vyhledání registrace nebo sledování a poté výsledek slaďte nebo opakujte v rámci omezených pravidel.

Nastavuje registrace automaticky upozornění na sledování?

Nepředpokládejte, že ano. Registrace, načítání sledování a konfigurace webhooků jsou samostatné integrační oblasti. Ověřte příslušnou dokumentaci a před spoléháním se na upozornění zákazníků otestujte celou cestu aktualizace.

Zdroje

  • Dokumentace API 17TRACK — reference pro registrační koncové body, ověřování, pole požadavků, identifikátory přepravců, schémata odpovědí a zpracování chyb. Podrobnosti implementace přizpůsobte verzi API, kterou nasazujete.
  • Přehled Tracking API 17TRACK — oficiální výchozí bod pro produkt tracking API a zdroje pro integraci vývojářů.