Cum să trimiți mai multe numere de urmărire într-o singură solicitare API (limitele loturilor și eșecurile parțiale)
Pentru a trimite mai multe numere de urmărire într-o singură solicitare API, utilizați un endpoint Tracking API care acceptă explicit loturi, formatați fiecare expediere conform schemei sale de solicitare și împărțiți listele mai mari în loturi care se încadrează în limitele documentate. Apoi verificați atât răspunsul HTTP, cât și rezultatul fiecărei expedieri: o solicitare HTTP reușită nu înseamnă neapărat că toate numerele de urmărire au fost acceptate. Reîncercați doar eșecurile eligibile și reconciliați rezultatele incerte înainte de a retrimite întregul lot.

Acest ghid se adresează dezvoltatorilor care conectează urmărirea expedierilor la un sistem de gestionare a comenzilor, o platformă de depozit, o aplicație de comerț electronic sau un tablou de bord intern. Obiectivul nu este doar să trimiteți mai puține solicitări. Trebuie să țineți evidența fiecărei expedieri fără a crea activități duplicate sau a pierde înregistrările eșuate.
Mai întâi, identificați ce face de fapt endpointul pentru loturi
O integrare de urmărire poate implica mai multe operațiuni distincte. Înregistrarea expedierilor, obținerea celor mai recente informații de urmărire și primirea actualizărilor ulterioare nu sunt operațiuni interschimbabile.
Înregistrare:
Trimiteți expedierile astfel încât serviciul să poată începe sau continua urmărirea acestora.
Căutare:
Solicitați informații de urmărire pentru expedieri, conform regulilor de preluare ale endpointului.
Actualizarea livrării:
Primiți modificările ulterioare printr-un mecanism acceptat, cum ar fi webhookurile, sau preluați-le prin solicitări programate.
Consultați documentația pentru operațiunea exactă de care aveți nevoie. Un endpoint de înregistrare care acceptă mai multe înregistrări nu demonstrează că un endpoint de căutare acceptă același număr, folosește aceeași schemă sau are aceeași limită de frecvență.
Pentru o integrare 17TRACK, începeți cu pagina produsului Tracking API și utilizați documentația oficială API pentru a confirma operațiunea, metoda de autentificare, formatul solicitării și câmpurile răspunsului. Tratați exemplele de mai jos ca modele de implementare, nu ca înlocuitor pentru contractul acelui API.
Limitele loturilor înseamnă mai mult decât un număr maxim de expedieri
Nu există o limită universală pentru loturile unui Tracking API. Limitele pot varia în funcție de furnizor, endpoint, versiunea API și configurația contului. Înainte de a implementa procesarea pe loturi, înregistrați separat aceste constrângeri.
| Constrângere | Ce trebuie confirmat | Consecință pentru implementare |
|---|---|---|
| Elemente per solicitare | Numărul maxim de înregistrări pentru operațiunea specifică | Împărțiți lista de intrare înainte de trimitere |
| Dimensiunea corpului solicitării | Orice limită documentată în octeți | Țineți cont de câmpurile opționale și de dimensiunea serializării |
| Rata solicitărilor | Numărul de solicitări permise într-un interval definit | Distribuiți solicitările printr-un limitator comun |
| Concurență | Orice restricție privind solicitările simultane | Limitați numărul de lucrători activi |
| Contorizarea utilizării | Dacă utilizarea este calculată pe solicitare, expediere sau altă unitate | Estimați consumul separat de volumul solicitărilor |
De exemplu, dacă un endpoint ipotetic permite 25 de înregistrări per solicitare, 63 de înregistrări necesită trei solicitări care conțin 25, 25 și 13 înregistrări. Aceste numere ilustrează doar împărțirea în loturi; nu reprezintă limite 17TRACK.
Nu presupuneți că procesarea pe loturi reduce utilizarea facturabilă. Aceasta poate reduce costurile administrative ale solicitărilor HTTP, însă orice efect asupra taxelor depinde de regulile reale de contabilizare ale furnizorului. În mod similar, o dimensiune validă a lotului nu autorizează un număr nelimitat de solicitări paralele.
Pregătiți înregistrările înainte de a construi solicitarea
Majoritatea erorilor de lot care pot fi evitate încep cu pregătirea datelor de intrare. Validați fiecare expediere înainte de a o adăuga la un lot, dar evitați regulile care resping accidental numere de urmărire valide de la transportatori diferiți.
- Păstrați numerele de urmărire ca șiruri de caractere. Convertirea lor în numere poate elimina zerourile de la început sau poate modifica identificatorii lungi.
- Eliminați spațiile albe accidentale din jur. Nu eliminați caracterele interne și nu modificați literele mari sau mici decât dacă specificația relevantă permite această normalizare.
- Validați câmpurile obligatorii. Unele fluxuri pot necesita un identificator al transportatorului sau informații suplimentare despre expediere. Utilizați numai numele și valorile câmpurilor documentate.
- Alegeți un domeniu explicit pentru eliminarea duplicatelor. Un număr de urmărire repetat nu este automat un duplicat pentru fiecare transportator, comerciant sau expediere istorică.
- Păstrați un identificator local al expedierii. Stocați relația dintre articolul trimis și înregistrarea comenzii sau a expedierii, chiar și atunci când API-ul nu acceptă câmpuri de referință personalizate.
Pentru Carrier Tracking în mai multe rețele, nu deduceți transportatorul numai din lungimea sau prefixul unui număr de urmărire decât dacă această deducție este fiabilă pentru fluxul dvs. specific. Atunci când API-ul acceptă identificarea transportatorului, urmați comportamentul documentat pentru gestionarea ambiguităților.
Structura ilustrativă a solicitării
Următorul JSON prezintă conceptul unui payload pentru loturi. Wrapperul, numele proprietăților și identificatorii sunt ilustrative, nu reprezintă o schemă de solicitare 17TRACK. Unele API-uri așteaptă un tablou de nivel superior în locul unui obiect care conține un tablou.
{
"shipments": [
{
"tracking_number": "EXAMPLE000001",
"carrier_id": "DOCUMENTED_CARRIER_ID"
},
{
"tracking_number": "EXAMPLE000002",
"carrier_id": "DOCUMENTED_CARRIER_ID"
}
]
}Construiți payloadul printr-un serializer JSON, nu prin concatenarea șirurilor. Trimiteți datele de autentificare prin mecanismul documentat și păstrați-le în afara controlului versiunilor, a codului livrat browserului și a jurnalelor obișnuite.
Procesați răspunsul la două niveluri
O solicitare pe lot are un rezultat la nivel de transport și un rezultat la nivel de aplicație. Integrarea dvs. trebuie să le evalueze pe ambele.
Nivelul 1: A primit solicitarea un răspuns utilizabil?
Începeți cu statusul HTTP, anteturile răspunsului și corpul răspunsului. Erorile de autentificare, solicitările malformate, limitarea frecvenței și erorile serverului pot împiedica procesarea normală a elementelor. Un timeout de rețea este diferit: este posibil ca clientul să nu știe dacă serverul a primit sau a procesat solicitarea.
Semantica HTTP este definită în RFC 9110. Totuși, documentația furnizorului stabilește modul în care câmpurile rezultatului la nivel de aplicație corespund rezultatelor reale ale expedierilor.
Nivelul 2: Ce s-a întâmplat cu fiecare expediere?
Dacă răspunsul acceptă rezultate la nivel de element, clasificați fiecare înregistrare trimisă. Nu presupuneți că HTTP 200 înseamnă că fiecare înregistrare a reușit sau că lista rezultatelor păstrează ordinea solicitării, decât dacă acest lucru este garantat explicit de contract.
- Acceptată: Operațiunea a reușit conform definiției documentate a endpointului.
- Eșec permanent al datelor de intrare: Corectați sau investigați înregistrarea înainte de o nouă încercare.
- Eșec reîncercabil: Programați o nouă încercare conform recomandărilor furnizorului.
- Rezultat necunoscut: Răspunsul lipsește, este incomplet sau nu poate fi asociat în siguranță cu înregistrarea trimisă.
Păstrați separat răspunsurile de tip „deja înregistrat” sau răspunsurile similare legate de duplicate până când le înțelegeți semnificația documentată. Acestea pot indica faptul că starea dorită există deja, dar nu trebuie tratate automat ca o confirmare a proprietății, configurației sau abonamentului.
După procesarea unui răspuns, fiecare înregistrare de intrare trebuie să aibă exact un rezultat local. O verificare utilă de reconciliere este: înregistrările trimise sunt egale cu înregistrările acceptate plus eșecurile permanente plus eșecurile reîncercabile plus rezultatele necunoscute. Aceasta este o regulă locală de contabilizare, nu un format obligatoriu al răspunsului API.
Gestionați eșecurile parțiale fără a retrimite înregistrările reușite
Să presupunem că un lot ilustrativ conține zece expedieri: șapte sunt acceptate, două au câmpuri obligatorii invalide, iar una întâmpină o eroare temporară documentată. Salvați rezultatele celor șapte reușite, trimiteți cele două înregistrări invalide pentru corectare și reîncercați doar eroarea temporară.
Retrimiterea tuturor celor zece înregistrări creează trafic inutil și poate complica gestionarea duplicatelor. De asemenea, face mai dificilă deosebirea unei respingeri inițiale de un răspuns ulterior referitor la un duplicat.
| Rezultat | Acțiune recomandată |
|---|---|
| Câmp invalid sau valoare nesuportată | Corectați datele de intrare; nu reîncercați fără modificări |
| Eșec de autentificare sau de permisiune | Opriți activitatea afectată și remediați datele de autentificare sau accesul |
| Răspuns de limitare a frecvenței | Amânați conform recomandărilor documentate și antetelor aplicabile ale răspunsului |
| Eroare temporară la nivel de element | Reîncercați elementul cu un număr limitat de încercări și backoff |
| Timeout după trimitere | Marcați rezultatul ca incert; reconciliați-l sau utilizați garanțiile documentate privind siguranța reîncercării |
| Rezultat nerecunoscut sau incomplet | Păstrați dovezile și investigați în loc să presupuneți succesul |
HTTP 429 indică prea multe solicitări, iar răspunsul poate include un antet Retry-After, conform descrierii din RFC 6585. Nu presupuneți că acest antet este prezent întotdeauna. Când nu este furnizată o întârziere explicită pentru reîncercare, utilizați o politică de backoff limitată, compatibilă cu documentația API-ului.
Adăugați jitter pentru a distribui reîncercările mai multor lucrători, stabiliți un număr maxim de încercări sau o vechime maximă a reîncercării și trimiteți înregistrările epuizate într-o coadă de revizuire. Reîncercarea la nesfârșit poate ascunde o problemă persistentă de configurare.
De ce timeouturile necesită un tratament special
Un timeout nu dovedește respingerea. Serverul poate să fi acceptat lotul înainte ca conexiunea să eșueze. Retrimiterea automată a unei solicitări care modifică starea poate, prin urmare, să repete operațiunea.
Dacă endpointul acceptă chei de idempotență documentate, urmați regulile sale, inclusiv domeniul de aplicare și perioada de păstrare a cheii. Nu inventați un antet de idempotență și nu presupuneți că serverul îl respectă. În caz contrar, utilizați un flux acceptat de căutare sau reconciliere pentru a determina dacă starea dorită există înainte de retrimitere. Eliminarea duplicatelor la nivel local ajută la coordonarea propriilor lucrători, dar nu garantează idempotența pe partea serverului.
Un flux practic de procesare a loturilor
Păstrați detaliile specifice furnizorului într-un adaptor, astfel încât coada, programatorul de reîncercări și logica de monitorizare să nu depindă de numele brute ale câmpurilor din răspuns.
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
Faceți ca stocarea rezultatelor și programarea reîncercărilor să poată fi recuperate. De exemplu, o înregistrare persistentă a unei sarcini sau un model tranzacțional de plasare în coadă poate împiedica pierderea deciziei de reîncercare în cazul unei erori a procesului. La repornire, lucrătorii trebuie să poată distinge activitatea netrimisă de activitatea al cărei rezultat la distanță este încă incert.
Utilizați dimensiunea lotului ca setare configurabilă asociată endpointului relevant, nu ca o constantă împrăștiată în baza de cod. Un lot mai mic poate fi util la depanare sau la izolarea înregistrărilor problematice; cel mai mare lot permis nu este automat și cea mai bună dimensiune operațională.
Monitorizați rezultatele expedierilor, nu doar disponibilitatea HTTP
API Monitoring trebuie să arate dacă expedierile ajung în starea dorită. Un tablou de bord care raportează doar ratele de succes HTTP poate omite eșecurile parțiale din răspunsuri altfel reușite.
- Rata de acceptare a elementelor: Înregistrări acceptate împărțite la înregistrările trimise, cu tratarea clar definită a reîncercărilor.
- Distribuția eșecurilor: Numărări după endpoint, cod de eroare documentat și contextul relevant al transportatorului.
- Rezultate necunoscute: Înregistrări nereconciliate și durata pentru care au rămas nerezolvate.
- Restanța reîncercărilor: Reîncercări în așteptare, vechimea celei mai vechi reîncercări și încercări epuizate.
- Sănătatea solicitărilor: Latență, timeouturi, limitarea frecvenței și erori de server.
- Actualitatea urmăririi: Dacă expedierile acceptate primesc ulterior informații de urmărire utilizabile.
Acceptarea înregistrării nu dovedește apariția unei scanări noi a transportatorului. Păstrați separat starea procesării API de mișcarea expedierii și actualitatea datelor, astfel încât un incident de integrare să nu fie confundat cu o întârziere a livrării.
Înregistrați ID-urile locale ale loturilor, referințele expedierilor, numărul încercărilor, codurile de eroare documentate și ID-urile solicitărilor furnizorului atunci când sunt disponibile. Redactați datele de autentificare și informațiile personale inutile. Utilizați identificatorii de urmărire numai atunci când sunt necesari operațional și evitați plasarea identificatorilor bruti ai expedierilor în etichetele de metrici cu cardinalitate ridicată.
Testați aceste cazuri înainte de producție
Utilizați un sandbox documentat sau un mediu de testare controlat, atunci când este disponibil. Nu presupuneți că numerele de urmărire inventate vor produce răspunsuri previzibile în producție.
- Trimiteți un lot valid la limita documentată de elemente, apoi testați modul în care clientul împiedică un lot prea mare.
- Verificați că numerele de urmărire cu zerouri la început supraviețuiesc serializării și stocării.
- Testați elemente acceptate și respinse în același lot, fără a reîncerca înregistrările reușite.
- Simulați limitarea frecvenței și confirmați că mai mulți lucrători respectă aceeași limită.
- Simulați un timeout după trimitere și verificați fluxul de reconciliere.
- Reporniți un lucrător între primirea răspunsului și stocarea locală.
- Testați rezultate de element lipsă, necunoscute sau imposibil de asociat.
- Confirmați că înregistrările invalide ajung într-o coadă vizibilă de corectare, în loc să fie reîncercate la nesfârșit.
O integrare pregătită pentru producție poate explica starea fiecărei expedieri trimise, inclusiv a celor al căror rezultat este temporar necunoscut. Reducerea numărului de solicitări este utilă; păstrarea acestei responsabilități este obiectivul de proiectare mai important.
Întrebări frecvente
Câte numere de urmărire pot trimite într-o singură solicitare?
Utilizați limita documentată pentru endpointul exact și versiunea API. Verificați, de asemenea, dimensiunea solicitării, limitele de frecvență și orice constrângeri specifice contului. Nu există un număr universal sigur care să poată fi aplicat tuturor API-urilor de urmărire sau tuturor operațiunilor dintr-un singur API.
Poate un singur număr de urmărire invalid să determine eșecul întregului lot?
Da, în funcție de regulile de validare ale endpointului. Unele API-uri returnează respingeri individuale, în timp ce altele pot respinge solicitarea înainte de procesarea elementelor. Verificați atât erorile la nivel de solicitare, cât și rezultatele la nivel de element; nu presupuneți că fiecare endpoint pentru loturi acceptă procesarea parțială.
Ar trebui să reîncerc un lot atunci când răspunsul HTTP este reușit?
Nu automat. Analizați mai întâi starea documentată la nivel de aplicație și rezultatele elementelor. Păstrați înregistrările reușite și reîncercați doar eșecurile eligibile. Dacă rezultatul nu poate fi interpretat în siguranță, clasificați-l ca incert și investigați.
Pot combina transportatori în același lot?
Numai atunci când endpointul acceptă această structură de solicitare. Confirmați dacă informațiile despre transportator sunt furnizate pentru fiecare expediere, dacă identificarea automată este acceptată și ce se întâmplă atunci când identificarea este ambiguă. Un serviciu multi-transportator nu stabilește de unul singur regulile de procesare pe loturi ale fiecărui endpoint.
Procesarea pe loturi face ca actualizările de urmărire să ajungă mai repede?
Procesarea pe loturi poate reduce numărul de solicitări trimise de aplicație, dar nu face de una singură ca evenimentele transportatorului să apară mai devreme. Înregistrarea, preluarea datelor, disponibilitatea scanărilor transportatorului și livrarea actualizărilor sunt părți separate ale fluxului.
Surse
- 17TRACK Tracking API — punctul oficial de intrare al produsului pentru dezvoltatorii care evaluează o integrare de urmărire.
- 17TRACK API documentation — referință pentru contractul endpointului specific furnizorului, limite, autentificare și gestionarea răspunsurilor.
- RFC 9110: HTTP Semantics — semantica statusurilor HTTP, idempotența, reîncercările automate și Retry-After.
- RFC 6585: Additional HTTP Status Codes — definiția HTTP 429 Too Many Requests și a antetului opțional Retry-After.


