Ako odoslať viacero sledovacích čísel v jednej požiadavke API (limity dávok a čiastočné zlyhania)
Ak chcete odoslať viacero sledovacích čísel v jednej požiadavke API, použite koncový bod Tracking API, ktorý výslovne prijíma dávku, naformátujte každú zásielku podľa jeho schémy požiadavky a väčšie zoznamy rozdeľte na dávky v rámci zdokumentovaných limitov. Potom skontrolujte HTTP odpoveď aj výsledok každej zásielky: úspešná HTTP požiadavka nemusí znamenať, že každé sledovacie číslo bolo prijaté. Opakujte iba oprávnené zlyhania a pred opätovným odoslaním celej dávky zosúlaďte nejednoznačné výsledky.

Táto príručka je určená vývojárom, ktorí pripájajú sledovanie zásielok k systému na správu objednávok, skladovej platforme, e-commerce aplikácii alebo internému dashboardu. Cieľom nie je iba odosielať menej požiadaviek. Ide o zaevidovanie každej zásielky bez vytvárania duplicitnej práce alebo straty neúspešných záznamov.
Najprv zistite, čo dávkový koncový bod skutočne robí
Integrácia sledovania môže zahŕňať niekoľko odlišných operácií. Registrácia zásielok, získavanie ich najnovších informácií o sledovaní a prijímanie následných aktualizácií nie sú vzájomne zameniteľné.
- Registrácia: Odoslanie zásielok, aby pre ne služba mohla začať alebo naďalej poskytovať sledovanie.
- Vyhľadanie: Vyžiadanie informácií o sledovaní zásielok v súlade s pravidlami získavania údajov daného koncového bodu.
- Aktualizácia doručenia: Prijímanie neskorších zmien prostredníctvom podporovaného mechanizmu, napríklad webhookov, alebo ich získavanie prostredníctvom plánovaných požiadaviek.
V dokumentácii si overte presnú operáciu, ktorú potrebujete. Registračný koncový bod prijímajúci viacero záznamov neznamená, že vyhľadávací koncový bod prijíma rovnaký počet záznamov, používa rovnakú schému alebo má rovnaký limit požiadaviek.
Pri integrácii 17TRACK začnite na stránke produktu Tracking API a pomocou oficiálnej dokumentácie API potvrďte operáciu, metódu autentifikácie, formát požiadavky a polia odpovede. Príklady uvedené nižšie považujte za implementačné vzory, nie za náhradu tejto zmluvy API.
Dávkové limity nie sú iba maximálnym počtom zásielok
Pre Tracking API neexistuje univerzálny dávkový limit. Limity sa môžu líšiť podľa poskytovateľa, koncového bodu, verzie API a konfigurácie účtu. Pred implementáciou dávkového spracovania si tieto obmedzenia zaznamenajte samostatne.
| Obmedzenie | Čo potvrdiť | Dôsledok pre implementáciu |
|---|---|---|
| Položky na požiadavku | Maximálny počet záznamov pre konkrétnu operáciu | Pred odoslaním rozdeliť vstupný zoznam |
| Veľkosť tela požiadavky | Akýkoľvek zdokumentovaný limit v bajtoch | Zohľadniť voliteľné polia a veľkosť serializácie |
| Frekvencia požiadaviek | Počet povolených požiadaviek za definovaný interval | Regulovať požiadavky prostredníctvom spoločného obmedzovača |
| Súbežnosť | Akékoľvek obmedzenie súčasných požiadaviek | Obmedziť počet aktívnych pracovníkov |
| Evidencia používania | Či sa používanie počíta podľa požiadavky, zásielky alebo inej jednotky | Odhadnúť spotrebu oddelene od objemu požiadaviek |
Ak napríklad hypotetický koncový bod povoľuje 25 záznamov na požiadavku, 63 záznamov si vyžaduje tri požiadavky obsahujúce 25, 25 a 13 záznamov. Tieto čísla ilustrujú iba rozdelenie na časti; nejde o uvedené limity 17TRACK.
Nepredpokladajte, že dávkové spracovanie znižuje účtovanú spotrebu. Môže znížiť režijné náklady HTTP požiadaviek, ale vplyv na poplatky závisí od skutočných pravidiel evidencie poskytovateľa. Rovnako platná veľkosť dávky nepovoľuje neobmedzený počet paralelných požiadaviek.
Pripravte záznamy pred vytvorením požiadavky
Väčšina chýb dávkového spracovania, ktorým sa dá predísť, začína pri príprave vstupu. Pred pridaním zásielky do dávky ju overte, ale vyhnite sa pravidlám, ktoré by mohli omylom odmietnuť platné sledovacie čísla od rôznych dopravcov.
- Sledovacie čísla uchovávajte ako reťazce. Ich konverzia na čísla môže odstrániť úvodné nuly alebo zmeniť dlhé identifikátory.
- Odstráňte náhodné okolité medzery. Neodstraňujte vnútorné znaky ani nemeňte veľkosť písmen, pokiaľ príslušná špecifikácia takúto normalizáciu nepovoľuje.
- Overte povinné polia. Niektoré pracovné postupy môžu vyžadovať identifikátor dopravcu alebo ďalšie informácie o zásielke. Používajte iba zdokumentované názvy a hodnoty polí.
- Zvoľte explicitný rozsah odstraňovania duplicít. Opakované sledovacie číslo nie je automaticky duplikátom naprieč každým dopravcom, obchodníkom alebo historickou zásielkou.
- Uchovávajte lokálny identifikátor zásielky. Uchovávajte vzťah medzi odosielanou položkou a záznamom objednávky alebo zásielky, aj keď API neprijíma vlastné referenčné polia.
Pri Carrier Tracking naprieč viacerými sieťami neurčujte dopravcu iba podľa dĺžky alebo prefixu sledovacieho čísla, pokiaľ je takýto odhad spoľahlivý pre váš konkrétny pracovný postup. Ak API podporuje identifikáciu dopravcu, riaďte sa jeho zdokumentovaným správaním pri nejednoznačnosti.
Ilustračná štruktúra požiadavky
Nasledujúci JSON zobrazuje koncept dávkového payloadu. Obal, názvy vlastností a identifikátory sú ilustračné, nejde o schému požiadavky 17TRACK. Niektoré API očakávajú namiesto objektu obsahujúceho pole pole na najvyššej úrovni.
{
"shipments": [
{
"tracking_number": "EXAMPLE000001",
"carrier_id": "DOCUMENTED_CARRIER_ID"
},
{
"tracking_number": "EXAMPLE000002",
"carrier_id": "DOCUMENTED_CARRIER_ID"
}
]
}Payload vytvárajte pomocou JSON serializéra, nie spájaním reťazcov. Autentifikačné údaje odosielajte prostredníctvom zdokumentovaného mechanizmu a uchovávajte ich mimo správy zdrojového kódu, kódu doručovaného prehliadaču a bežných logov.
Spracujte odpoveď na dvoch úrovniach
Dávková požiadavka má výsledok na transportnej úrovni a výsledok na aplikačnej úrovni. Vaša integrácia musí vyhodnotiť oba.
Úroveň 1: Dostala požiadavka použiteľnú odpoveď?
Začnite stavom HTTP, hlavičkami odpovede a telom odpovede. Chyby autentifikácie, nesprávne požiadavky, obmedzenie frekvencie a zlyhania servera môžu zabrániť bežnému spracovaniu položiek. Sieťový timeout je odlišný: klient nemusí vedieť, či server požiadavku prijal alebo spracoval.
Sémantiku HTTP definuje RFC 9110. Dokumentácia poskytovateľa však určuje, ako sa jeho polia výsledkov na aplikačnej úrovni mapujú na skutočné výsledky zásielok.
Úroveň 2: Čo sa stalo s každou zásielkou?
Ak odpoveď podporuje výsledky na úrovni položiek, klasifikujte každý odoslaný záznam. Nepredpokladajte, že HTTP 200 znamená úspech každého záznamu alebo že zoznam výsledkov zachováva poradie požiadavky, pokiaľ to zmluva výslovne nezaručuje.
- Prijaté: Operácia bola úspešná podľa zdokumentovanej definície koncového bodu.
- Trvalé zlyhanie vstupu: Pred ďalším pokusom záznam opravte alebo preskúmajte.
- Opakovateľné zlyhanie: Naplánujte ďalší pokus podľa pokynov poskytovateľa na opakovanie.
- Neznámy výsledok: Odpoveď chýba, je neúplná alebo ju nemožno bezpečne priradiť k odoslanému záznamu.
Odpovede typu „už zaregistrované“ alebo podobné odpovede súvisiace s duplicitami ponechajte oddelené, kým nepochopíte ich zdokumentovaný význam. Môžu znamenať, že požadovaný stav už existuje, ale nemali by sa automaticky považovať za potvrdenie vlastníctva, konfigurácie alebo predplatného.
Po spracovaní odpovede by mal mať každý vstupný záznam presne jeden lokálny výsledok. Užitočná kontrola zosúladenia je: odoslané záznamy sa rovnajú prijatým záznamom plus trvalým zlyhaniam plus opakovateľným zlyhaniam plus neznámym výsledkom. Ide o lokálne účtovné pravidlo, nie o povinný formát odpovede API.
Spracujte čiastočné zlyhania bez opätovného odosielania úspešných záznamov
Predstavte si ilustračnú dávku s desiatimi zásielkami: sedem je prijatých, dve majú neplatné povinné polia a pri jednej sa vyskytne zdokumentovaná dočasná chyba. Uložte sedem úspešných výsledkov, dve neplatné zásielky odošlite na opravu a opakujte iba dočasne neúspešnú zásielku.
Opätovné odoslanie všetkých desiatich záznamov vytvára zbytočnú prevádzku a môže skomplikovať spracovanie duplicít. Zároveň sťažuje rozlíšenie pôvodného odmietnutia od neskoršej odpovede súvisiacej s duplicitou.
| Výsledok | Odporúčaná akcia |
|---|---|
| Neplatné pole alebo nepodporovaná hodnota | Opravte vstup; nezopakujte ho bez zmien |
| Zlyhanie autentifikácie alebo oprávnení | Pozastavte ovplyvnenú prácu a opravte prihlasovacie údaje alebo prístup |
| Odpoveď o obmedzení frekvencie | Odložte požiadavku podľa zdokumentovaných pokynov a príslušných hlavičiek odpovede |
| Dočasná chyba na úrovni položky | Opakujte danú položku s obmedzeným počtom pokusov a oneskorením |
| Timeout po odoslaní | Označte výsledok ako neistý; vykonajte zosúladenie alebo použite zdokumentované záruky bezpečnosti opakovania |
| Nerozpoznaný alebo neúplný výsledok | Uchovajte dôkazy a skúmajte situáciu namiesto predpokladania úspechu |
HTTP 429 označuje príliš veľa požiadaviek a jeho odpoveď môže obsahovať hlavičku Retry-After, ako je opísané v RFC 6585. Nepredpokladajte, že táto hlavička je vždy prítomná. Ak nie je uvedené explicitné oneskorenie opakovania, použite obmedzenú politiku oneskorenia v súlade s dokumentáciou API.
Pridajte náhodnú zložku, aby ste rozložili opakovania z viacerých pracovníkov, nastavte maximálny počet pokusov alebo maximálny vek opakovania a vyčerpané záznamy odošlite do kontrolného frontu. Nekonečné opakovanie môže skryť pretrvávajúci problém s konfiguráciou.
Prečo si timeouty vyžadujú osobitné zaobchádzanie
Timeout nedokazuje odmietnutie. Server mohol dávku prijať ešte pred zlyhaním spojenia. Automatické opätovné odoslanie požiadavky meniacej stav preto môže zopakovať prácu.
Ak koncový bod podporuje zdokumentované idempotency keys, riaďte sa jeho pravidlami vrátane rozsahu a doby uchovávania kľúča. Nevymýšľajte vlastnú hlavičku idempotency a nepredpokladajte, že ju server rešpektuje. V opačnom prípade použite podporovaný pracovný postup vyhľadania alebo zosúladenia na zistenie, či požadovaný stav existuje, pred opätovným odoslaním. Lokálne odstraňovanie duplicít pomáha koordinovať vašich vlastných pracovníkov, ale nezaručuje idempotenciu na strane servera.
Praktický pracovný postup dávkového spracovania
Podrobnosti špecifické pre poskytovateľa uchovávajte v adaptéri, aby front, plánovač opakovaní a logika monitorovania nezáviseli od nespracovaných názvov polí odpovede.
validate records and retain local shipment IDs
resolve duplicates within the intended business scope
split records using documented item and payload limits
for each batch through a bounded worker pool:
persist an attempt record before sending
wait for the shared rate limiter
send using the provider-specific adapter
if the outcome is uncertain:
enqueue reconciliation
continue
classify request-level and item-level outcomes
persist one outcome for every submitted record
schedule only eligible failures for retry
route invalid or exhausted records for review
Ukladanie výsledkov a plánovanie opakovaní musí byť obnoviteľné. Napríklad trvalý záznam úlohy alebo transakčný vzor radenia do frontu môže zabrániť tomu, aby pád procesu spôsobil stratu rozhodnutia o opakovaní. Po reštarte by pracovníci mali vedieť rozlíšiť neodoslanú prácu od práce, ktorej vzdialený výsledok je stále neistý.
Veľkosť dávky nastavte ako konfigurovateľné nastavenie viazané na príslušný koncový bod, nie ako konštantu rozptýlenú v celej kódovej základni. Menšia dávka môže byť užitočná pri riešení problémov alebo izolovaní problematických záznamov; najväčšia povolená dávka nie je automaticky najvhodnejšia prevádzková veľkosť.
Monitorujte výsledky zásielok, nielen dostupnosť HTTP
API Monitoring by mal zobrazovať, či zásielky dosahujú požadovaný stav. Dashboard zobrazujúci iba mieru úspešnosti HTTP môže prehliadnuť čiastočné zlyhania v inak úspešných odpovediach.
- Miera prijatia položiek: Prijaté záznamy vydelené odoslanými záznamami s jasne definovaným zaobchádzaním s opakovaniami.
- Rozdelenie zlyhaní: Počty podľa koncového bodu, zdokumentovaného kódu chyby a relevantného kontextu dopravcu.
- Neznáme výsledky: Nezosúladené záznamy a čas, počas ktorého zostali nevyriešené.
- Front opakovaní: Čakajúce opakovania, vek najstaršieho opakovania a vyčerpané pokusy.
- Stav požiadaviek: Latencia, timeouty, obmedzenie frekvencie a chyby servera.
- Aktuálnosť sledovania: Či prijaté zásielky následne dostávajú použiteľné informácie o sledovaní.
Prijatie registrácie nie je dôkazom nového skenu dopravcu. Stav spracovania API udržiavajte oddelene od pohybu zásielky a aktuálnosti údajov, aby sa incident integrácie nezamieňal s oneskorením doručenia.
Zaznamenávajte lokálne ID dávok, referencie zásielok, počty pokusov, zdokumentované kódy chýb a ID požiadaviek poskytovateľa, ak sú k dispozícii. Maskujte prihlasovacie údaje a nepotrebné osobné informácie. Identifikátory sledovania používajte iba tam, kde sú prevádzkovo potrebné, a nevkladajte nespracované identifikátory zásielok do menoviek metrík s vysokou kardinalitou.
Pred produkciou otestujte tieto prípady
Ak je k dispozícii, použite zdokumentovaný sandbox alebo kontrolované testovacie prostredie. Nepredpokladajte, že vymyslené sledovacie čísla vytvoria v produkcii predvídateľné odpovede.
- Odošlite platnú dávku na zdokumentovanom limite položiek a potom otestujte, ako klient zabráni prekročeniu veľkosti dávky.
- Overte, že sledovacie čísla s úvodnými nulami prežijú serializáciu a uloženie.
- Otestujte kombináciu prijatých a odmietnutých položiek bez opakovania úspešných záznamov.
- Simulujte obmedzenie frekvencie a potvrďte, že viacerí pracovníci rešpektujú rovnaký limit.
- Simulujte timeout po odoslaní a overte cestu zosúladenia.
- Reštartujte pracovníka medzi prijatím odpovede a lokálnym uložením.
- Otestujte chýbajúce, neznáme alebo nepriraditeľné výsledky položiek.
- Potvrďte, že neplatné záznamy sa dostanú do viditeľného frontu opráv namiesto nekonečného opakovania.
Integrácia pripravená na produkciu dokáže vysvetliť stav každej odoslanej zásielky vrátane tých, ktorých výsledok je dočasne neznámy. Zníženie počtu požiadaviek je užitočné; zachovanie tejto zodpovednosti je dôležitejším cieľom návrhu.
Často kladené otázky
Koľko sledovacích čísel môžem odoslať v jednej požiadavke?
Použite limit zdokumentovaný pre presný koncový bod a verziu API. Skontrolujte tiež veľkosť požiadavky, limity frekvencie a prípadné obmedzenia špecifické pre účet. Neexistuje bezpečné univerzálne číslo použiteľné naprieč API na sledovanie alebo rôznymi operáciami v rámci jedného API.
Môže jedno neplatné sledovacie číslo spôsobiť zlyhanie celej dávky?
Áno, v závislosti od pravidiel overovania daného koncového bodu. Niektoré API vracajú individuálne odmietnutia, zatiaľ čo iné môžu požiadavku odmietnuť ešte pred spracovaním položiek. Skontrolujte chyby na úrovni požiadavky aj výsledky na úrovni položiek; nepredpokladajte, že každý dávkový koncový bod podporuje čiastočné prijatie.
Mám zopakovať dávku, keď je HTTP odpoveď úspešná?
Nie automaticky. Najprv analyzujte zdokumentovaný stav na aplikačnej úrovni a výsledky položiek. Úspešné záznamy uložte a opakujte iba oprávnené zlyhania. Ak výsledok nemožno bezpečne interpretovať, klasifikujte ho ako neistý a preskúmajte ho.
Môžem v rovnakej dávke kombinovať dopravcov?
Iba vtedy, keď koncový bod podporuje takúto štruktúru požiadavky. Potvrďte, či sa informácie o dopravcovi zadávajú pre každú zásielku, či je podporovaná automatická identifikácia a čo sa stane pri nejednoznačnej identifikácii. Služba pre viacerých dopravcov sama osebe nepotvrdzuje pravidlá dávkovania každého koncového bodu.
Spôsobuje dávkové spracovanie rýchlejší príchod aktualizácií sledovania?
Dávkové spracovanie môže znížiť počet požiadaviek odosielaných vašou aplikáciou, samo osebe však nespôsobí skoršie zobrazenie udalostí dopravcu. Registrácia, získavanie údajov, dostupnosť skenov dopravcu a doručovanie aktualizácií sú samostatné časti pracovného postupu.
Zdroje
- 17TRACK Tracking API — oficiálny vstupný bod produktu pre vývojárov posudzujúcich integráciu sledovania.
- Dokumentácia 17TRACK API — referencia pre zmluvu koncového bodu špecifickú pre poskytovateľa, limity, autentifikáciu a spracovanie odpovedí.
- RFC 9110: Sémantika HTTP — sémantika stavov HTTP, idempotencia, automatické opakovania a Retry-After.
- RFC 6585: Ďalšie stavové kódy HTTP — definícia HTTP 429 Too Many Requests a jeho voliteľnej hlavičky Retry-After.


