Skip to main content
DomůBlogPrůvodciJak ověřit sledovací čísla před odesláním do API: 7 pravidel, která je třeba dodržovat

Jak ověřit sledovací čísla před odesláním do API: 7 pravidel, která je třeba dodržovat

17TRACK

Trackingové číslo před odesláním do API pro sledování zásilky ověřujte ve vrstvách: normalizujte vstup, zkontrolujte jeho základní strukturu, potvrďte kontext přepravce, kontrolní součet použijte pouze tehdy, pokud jej přepravce dokumentuje, a odmítněte hodnoty, které jsou zjevně nebezpečné nebo neúplné. Nespoléhejte na jeden univerzální regulární výraz. Formáty trackingových čísel se liší podle přepravce, služby, země a typu zásilky, takže účinný validátor by měl bránit chybným požadavkům, aniž by blokoval legitimní čísla s neznámým formátem.

7 pravidel pro ověření trackingových čísel před odesláním do API

Tato příručka je určena vývojářům a provozním týmům, kteří integrují sledování zásilek do systému pro správu objednávek, skladového pracovního postupu, zákaznického portálu nebo e-commerce aplikace. Cílem není před odesláním prokázat, že zásilka existuje. Syntaktické ověření a ověření stavu zásilky jsou oddělené kroky.

Co může ověření potvrdit — a co ne

Validátor před odesláním může odhalit běžné problémy se vstupem, například prázdnou hodnotu, náhodné mezery, zalomení řádků, pevné mezery, nepodporované znaky, nadměrnou délku nebo trackingové číslo vložené do nesprávného pole. Může také určit pravděpodobného přepravce, pokud je přepravce známý a formát je zdokumentovaný.

Obvykle však nemůže potvrdit, že číslo patří skutečné zásilce, že přepravce zásilku převzal nebo že je číslo aktuálně možné sledovat. Tyto otázky vyžadují vyhledání u přepravce nebo na sledovací platformě. Číslo může projít kontrolou formátu a přesto být nepoužité, nenápadně chybně zadané, prošlé nebo spojené s jinou službou.

Pravidla

1. Normalizujte hodnotu, aniž byste změnili její význam

Uživatelé a nadřazené systémy často přidávají mezery na začátku nebo na konci, zalomení řádků, pevné mezery nebo formátovací znaky. Před ověřením je bezpečně normalizujte. Běžným prvním krokem je odstranění okolních bílých znaků a převod netisknutelných bílých znaků na běžné mezery. Pokud zdokumentovaný formát přepravce povoluje vnitřní mezery nebo spojovníky, rozhodněte, zda je pro požadavek API odstraníte, nebo zda původní hodnotu zachováte pro zobrazení a audit.

Pokud je to praktické, uchovávejte dvě hodnoty: původní vstup a kanonickou hodnotu. Původní hodnota pomáhá týmům podpory při vyšetřování problémů s kvalitou dat; kanonická hodnota se používá pro ověření a odeslání. Vyhněte se transformacím, které mohou změnit identifikátory. Automaticky nepřevádějte písmena na číslice, nenahrazujte nejednoznačné znaky ani neodstraňujte veškerou interpunkci, pokud takové chování výslovně nepodporuje příslušná dokumentace přepravce nebo API.

Zpracování Unicode vyžaduje pozornost. Vizuálně podobný znak z jiné abecedy nemusí být API přijat, přestože vypadá jako písmeno nebo číslice ASCII. Omezení kanonické hodnoty na znakovou sadu povolenou vybranou integrací může zabránit matoucím následným chybám.

2. Odmítněte hodnoty, které neprojdou základními strukturálními kontrolami

Před použitím logiky specifické pro přepravce zkontrolujte, zda je hodnota přítomná a věrohodná. Užitečné kontroly zahrnují minimální a maximální délku, povolené třídy znaků a ověření, zda hodnota neobsahuje pouze bílé znaky nebo zástupný text jako „N/A“, „TBD“ či „test“. Přesné limity by měly vycházet ze smlouvy API nebo dokumentace přepravce. Nevymýšlejte univerzální maximum jen proto, že většina příkladů je krátká.

Strukturální kontrola by měla být záměrně konzervativní. Pravidlo povolující pouze číslice například odmítne platné alfanumerické identifikátory. Pravidlo vyžadující jednu pevnou délku může odmítnout varianty služeb nebo mezinárodní formáty. Obecnými kontrolami zachyťte zjevné chyby a specifičtější kontroly použijte pouze tehdy, když znáte přepravce a službu.

Ověřujte také datový typ na hranici aplikace. Trackingové číslo by se obvykle mělo zpracovávat jako řetězec, nikoli jako celé číslo. Převod na číslo může odstranit úvodní nuly a v systémech s číselnými typy pevné šířky způsobit problémy s přesností. Po schválené normalizaci hodnotu zachovávejte přesně jako řetězec.

3. Používejte kontext přepravce místo odhadování pouze z čísla

Trackingové číslo bez přepravce je nejednoznačný vstup. Různí přepravci mohou používat překrývající se délky, prefixy nebo znakové sady a formát, který vypadá věrohodně u jednoho přepravce, může být u jiného neplatný. Pokud objednávka, štítek, skladový systém nebo účet obchodníka již přepravce identifikuje, předávejte tento kontext spolu s trackingovým číslem, kdykoli to API podporuje.

Kontext přepravce zlepšuje ověřování i směrování. Umožňuje aplikaci vybrat relevantní pravidla formátu, omezuje falešné shody a činí chybová hlášení užitečnějšími. Zároveň brání tomu, aby byl výsledek automatické detekce považován za skutečnost, když by podobně vypadající hodnotu mohlo přijmout několik přepravců.

Pokud přepravce není znám, použijte dvoufázový přístup. Nejprve proveďte obecné bezpečnostní kontroly. Poté hodnotu odešlete pouze prostřednictvím toku API, který výslovně podporuje detekci přepravce, nebo ji zařaďte do fronty k posouzení, pokud obchodní proces vyžaduje potvrzeného přepravce. Nepřiřazujte přepravce potichu pouze na základě prefixu, pokud toto mapování není udržováno a zdokumentováno.

4. Kontrolní součty používejte pouze tehdy, pokud je pravidlo zdokumentováno

Některé identifikační systémy používají kontrolní číslice, trackingová čísla však nepodléhají jednomu univerzálnímu standardu kontrolních součtů. Kontrolní součet může odhalit určité chyby při přepisu, neprokazuje však existenci zásilky. Ještě důležitější je, že použití nesprávného algoritmu může odmítnout platná čísla.

Kontrolní součet implementujte pouze tehdy, když příslušný přepravce, služba, specifikace štítku nebo dokumentace API definuje algoritmus a část vstupu, na kterou se vztahuje. Zaznamenejte verzi pravidla a otestujte je proti oficiálním příkladům. Pokud není k dispozici autoritativní pravidlo, kontrolní součet vynechte, místo abyste hádali podle vzorců pozorovaných na malém vzorku.

Výsledek kontrolního součtu považujte za jeden signál, nikoli za úplné rozhodnutí o ověření. Neúspěšná kontrola může odůvodnit zablokování odeslání, pokud je pravidlo autoritativní. Úspěšná kontrola by měla hodnotu posunout do další fáze, nikoli ji označit jako aktivní zásilku.

5. Oddělte ověření formátu od způsobilosti pro API

Hodnota může být správně vytvořená, ale přesto nevhodná pro endpoint, který voláte. Před odesláním zkontrolujte v dokumentaci API povinná pole, přijímané identifikátory přepravců, požadavky na autentizaci, limity požadavků, chování při duplicitách a případná omezení typů služeb nebo destinací. Jde o integrační pravidla, nikoli pravidla trackingových čísel, ale určují, zda lze platný identifikátor úspěšně zpracovat.

Dokumentace 17TRACK Tracking API ukazuje, proč je toto rozlišení důležité: vývojáři musí dodržovat model požadavků platformy a podporované integrační chování, nikoli vytvářet požadavek podle vzhledu trackingového čísla. Aktuální požadavky endpointů a zpracování odpovědí najdete v dokumentaci 17TRACK API.

Chyby ověření udržujte odděleně od chyb přenosu a autentizace. „Neplatný formát trackingového čísla“, „neznámý přepravce“, „dosažen limit požadavků“ a „autorizace selhala“ vyžadují odlišné akce. Jediné obecné hlášení „odeslání selhalo“ činí opakování a provozní reporting méně spolehlivými.

6. Chraňte API omezenými vstupy, deduplikací a bezpečným opakováním

Ověřování je také provozní pojistkou. Před analýzou nebo protokolováním vynucujte omezenou délku vstupu. Odmítejte řídicí znaky a neočekávané struktury dat. Na vlastní aplikační hranici používejte limity požadavků, aby chybný import nemohl vytvořit nekontrolovaný náraz požadavků.

Před odesláním provádějte deduplikaci, pokud obchodní proces nevyžaduje opakovanou registraci. Užitečný deduplikační klíč může zahrnovat kanonické trackingové číslo, přepravce, účet a kontext zásilky. Správný klíč závisí na vašem pracovním postupu; stejný identifikátor může být někdy znovu použit u různých služeb nebo obchodních záznamů, proto nepředpokládejte, že samotné číslo je vždy globálně jedinečné.

U dočasných selhání používejte omezený počet opakování s prodlevou a trvalé chyby ověření neopakujte. Pokud to API a vaše architektura podporují, ukládejte idempotency záznam nebo záznam o odeslání. Pro řešení problémů protokolujte dostatek informací, ale chraňte přihlašovací údaje, zákaznická data a citlivé údaje o zásilkách. Validátor má omezovat opakovaná selhání, nikoli vytvářet další bezpečnostní problém nadměrným protokolováním.

7. Po odeslání potvrďte výsledek a sledujte falešně pozitivní výsledky

Posledním pravidlem je považovat ověření před odesláním za bránu, nikoli za verdikt. Po přijetí požadavku zkontrolujte odpověď API a uložte její stav, identifikátor požadavku, přiřazení přepravce a případný zdokumentovaný chybový kód. Pokud platforma požadavek přijme, ale zatím nemůže vrátit události pohybu, může to znamenat zpoždění zpracování, nikoli neplatné číslo.

Definujte následný postup pro čísla, která zůstávají nevyřešená. Časové okno by mělo zohledňovat přepravce, službu, původ zásilky a vaši politiku zákaznického servisu; neexistuje univerzální lhůta, která by prokázala neplatnost čísla. Eskalujte záznamy s chybějícím přepravcem, opakovanými chybami poskytovatele, konfliktními výsledky přepravců nebo stavem, který neodpovídá záznamu objednávky.

Měřte počet falešných odmítnutí a falešných přijetí. Přísný regulární výraz může omezit chybně vytvořené požadavky a současně nesprávně blokovat legitimní zásilky. Příliš benevolentní validátor může zvýšit počet přijatých požadavků, ale vytvořit následný šum. Kontrolujte neúspěšné vzorky podle přepravce a služby, aktualizujte zdokumentovaná pravidla prostřednictvím správy verzí a testujte změny na reprezentativní sadě přípravků chránící soukromí.

Praktická posloupnost ověřování

Udržovatelná implementace může používat následující postup:

  1. Zkontrolujte, že požadavek obsahuje řetězcovou hodnotu a platný obchodní záznam.
  2. Uložte původní vstup a poté vytvořte zdokumentovanou kanonickou formu.
  3. Odmítněte prázdné hodnoty, zástupné texty, nebezpečné znaky a hodnoty mimo zdokumentovaný rozsah délky.
  4. Přepravce určete z důvěryhodných údajů objednávky nebo použijte výslovně podporovaný tok detekce.
  5. Pravidla syntaxe a kontrolního součtu specifická pro přepravce použijte pouze tehdy, pokud je podporuje autoritativní dokumentace.
  6. Zkontrolujte požadavky endpointu, stav duplicity a způsobilost k opakování.
  7. Požadavek odešlete, klasifikujte odpověď, uložte výsledek a naplánujte následné řešení nevyřešených záznamů.

Díky této posloupnosti se validátor snadněji testuje, protože každé rozhodnutí má jiný důvod. Provozním týmům také poskytuje použitelné kategorie selhání namísto jedné neprůhledné chyby.

Kontrolní seznam implementace

  • Trackingová čísla ukládejte jako řetězce, aby zůstaly zachovány úvodní nuly.
  • Pokud záleží na auditovatelnosti, uchovávejte původní a kanonické hodnoty odděleně.
  • Pravidla přepravců udržujte jako verzovanou konfiguraci, nikoli jako rozptýlené podmínky pevně zapsané v kódu.
  • Testujte písmena, číslice, spojovníky, bílé znaky, vizuálně podobné znaky Unicode, zástupné texty a hraniční délky.
  • Kdykoli je k dispozici, používejte důvěryhodný kontext přepravce.
  • Na základě úspěšné shody regulárního výrazu neodvozujte existenci zásilky.
  • Trvalé chyby ověření klasifikujte odděleně od dočasných chyb API nebo sítě.
  • Před změnou pravidel formátu nebo logiky požadavků si projděte dokumentaci poskytovatele.

Časté dotazy

Může regulární výraz ověřit trackingové číslo?

Může ověřit omezený vzor, pokud je znám formát přepravce a služby. Nemůže prokázat, že číslo existuje, patří konkrétní zásilce nebo je aktuálně aktivní. Univerzální výraz pravděpodobně vytvoří falešná odmítnutí nebo falešné shody.

Mělo by být číslo vypadající jako neplatné odesláno do API?

Zjevně prázdné, nebezpečné nebo strukturálně nemožné hodnoty by se obvykle měly zastavit před odesláním. Neznámý, ale jinak bezpečný formát by neměl být odmítnut pouze proto, že neodpovídá internímu odhadu. Nejprve ověřte dokumentaci přepravce nebo použijte podporovaný proces detekce.

Stačí kontrolní součet k potvrzení zásilky?

Ne. Kontrolní součet, pokud je použitelný, pouze ověřuje, zda hodnota splňuje matematické pravidlo. Nepotvrzuje, že číslo vydal přepravce ani že zásilka vstoupila do sítě.

Co se má stát, když je přepravce neznámý?

Proveďte obecné bezpečnostní kontroly a použijte tok API, který výslovně podporuje detekci přepravce, pokud je k dispozici. V opačném případě záznam ponechte k doplnění údajů nebo ruční kontrole, místo abyste přepravce potichu odhadovali.

Jak se mají zpracovávat chyby API?

Klasifikujte je podle příčiny. Opravte chybně vytvořený vstup a nepodporované hodnoty přepravce; dočasná selhání sítě nebo poskytovatele opakujte s omezením a prodlevou; chyby autentizace nebo kvóty předávejte vlastníkovi integrace. Ukládejte podrobnosti odpovědi potřebné k diagnostice, aniž byste odhalili tajné údaje.

Zdroje

  • Dokumentace 17TRACK API — pokyny k požadavkům a integraci pro vývojáře trackingových API.
  • 17TRACK Tracking API — oficiální informace o produktu a případy použití API.
  • USPS Tracking — oficiální vstupní bod pro sledování zásilek tohoto přepravce a pokyny pro zákazníky.
  • UPS Tracking — oficiální vstupní bod pro sledování zásilek tohoto přepravce.