Skip to main content
DomovBlogPríručkyAko odoslať viacero sledovacích čísel v jednej požiadavke API (limity dávok a čiastočné zlyhania)

Ako odoslať viacero sledovacích čísel v jednej požiadavke API (limity dávok a čiastočné zlyhania)

17TRACK

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.

Ako odoslať viacero sledovacích čísel v jednej požiadavke API

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žiadavkuMaximálny počet záznamov pre konkrétnu operáciuPred odoslaním rozdeliť vstupný zoznam
Veľkosť tela požiadavkyAkýkoľvek zdokumentovaný limit v bajtochZohľadniť voliteľné polia a veľkosť serializácie
Frekvencia požiadaviekPočet povolených požiadaviek za definovaný intervalRegulovať požiadavky prostredníctvom spoločného obmedzovača
SúbežnosťAkékoľvek obmedzenie súčasných požiadaviekObmedziť počet aktívnych pracovníkov
Evidencia používaniaČi sa používanie počíta podľa požiadavky, zásielky alebo inej jednotkyOdhadnúť 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.

  1. Sledovacie čísla uchovávajte ako reťazce. Ich konverzia na čísla môže odstrániť úvodné nuly alebo zmeniť dlhé identifikátory.
  2. 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.
  3. 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í.
  4. 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.
  5. 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ýsledokOdporúčaná akcia
Neplatné pole alebo nepodporovaná hodnotaOpravte 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í frekvencieOdložte požiadavku podľa zdokumentovaných pokynov a príslušných hlavičiek odpovede
Dočasná chyba na úrovni položkyOpakujte 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ýsledokUchovajte 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.

  1. Odošlite platnú dávku na zdokumentovanom limite položiek a potom otestujte, ako klient zabráni prekročeniu veľkosti dávky.
  2. Overte, že sledovacie čísla s úvodnými nulami prežijú serializáciu a uloženie.
  3. Otestujte kombináciu prijatých a odmietnutých položiek bez opakovania úspešných záznamov.
  4. Simulujte obmedzenie frekvencie a potvrďte, že viacerí pracovníci rešpektujú rovnaký limit.
  5. Simulujte timeout po odoslaní a overte cestu zosúladenia.
  6. Reštartujte pracovníka medzi prijatím odpovede a lokálnym uložením.
  7. Otestujte chýbajúce, neznáme alebo nepriraditeľné výsledky položiek.
  8. 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