Come inviare più numeri di tracciamento in un'unica richiesta API (limiti dei batch e fallimenti parziali)
Per inviare più numeri di tracciamento in un'unica richiesta API, utilizza un endpoint della Tracking API che accetti esplicitamente un batch, formatta ogni spedizione secondo lo schema della richiesta e suddividi gli elenchi più lunghi in batch che rispettino i limiti documentati. Quindi controlla sia la risposta HTTP sia il risultato di ogni spedizione: una richiesta HTTP riuscita non significa necessariamente che ogni numero di tracciamento sia stato accettato. Ripeti il tentativo solo per gli errori idonei e riconcilia gli esiti incerti prima di inviare nuovamente un intero batch.

Questa guida è destinata agli sviluppatori che collegano il tracciamento delle spedizioni a un sistema di gestione degli ordini, a una piattaforma di magazzino, a un'applicazione ecommerce o a un dashboard interno. L'obiettivo non è semplicemente inviare meno richieste, ma tenere conto di ogni spedizione senza creare attività duplicate o perdere i record non riusciti.
Innanzitutto, identifica cosa fa realmente l'endpoint batch
Un'integrazione di tracciamento può coinvolgere diverse operazioni distinte. Registrare le spedizioni, recuperare le informazioni di tracciamento più recenti e ricevere gli aggiornamenti successivi non sono attività intercambiabili.
- Registrazione: Invia le spedizioni affinché il servizio possa iniziare o mantenere il relativo tracciamento.
- Ricerca: Richiedi le informazioni di tracciamento delle spedizioni, in base alle regole di recupero dell'endpoint.
- Aggiornamento della consegna: Ricevi le modifiche successive tramite un meccanismo supportato, come i webhook, oppure recuperale attraverso richieste pianificate.
Controlla la documentazione per l'operazione esatta di cui hai bisogno. Un endpoint di registrazione che accetta più record non dimostra che un endpoint di ricerca accetti lo stesso numero di record, utilizzi lo stesso schema o condivida lo stesso limite di frequenza.
Per un'integrazione 17TRACK, inizia dalla pagina del prodotto Tracking API e utilizza la documentazione API ufficiale per confermare l'operazione, il metodo di autenticazione, il formato della richiesta e i campi della risposta. Considera gli esempi riportati di seguito come modelli di implementazione, non come sostituti del contratto dell'API.
I limiti dei batch sono più di un semplice numero massimo di spedizioni
Non esiste un limite universale per i batch di una Tracking API. I limiti possono variare in base al provider, all'endpoint, alla versione dell'API e alla configurazione dell'account. Prima di implementare l'elaborazione in batch, registra separatamente questi vincoli.
| Vincolo | Cosa confermare | Conseguenza per l'implementazione |
|---|---|---|
| Elementi per richiesta | Numero massimo di record per l'operazione specifica | Suddividere l'elenco di input prima dell'invio |
| Dimensione del corpo della richiesta | Eventuale limite di byte documentato | Tenere conto dei campi facoltativi e delle dimensioni della serializzazione |
| Frequenza delle richieste | Richieste consentite in un intervallo definito | Regolare le richieste tramite un limiter condiviso |
| Concorrenza | Eventuali restrizioni sulle richieste simultanee | Limitare il numero di worker attivi |
| Contabilizzazione dell'utilizzo | Se l'utilizzo viene conteggiato per richiesta, spedizione o altra unità | Stimare il consumo separatamente dal volume delle richieste |
Ad esempio, se un endpoint ipotetico consente 25 record per richiesta, 63 record richiedono tre richieste contenenti rispettivamente 25, 25 e 13 record. Questi numeri illustrano solo il raggruppamento; non rappresentano limiti dichiarati di 17TRACK.
Non dare per scontato che l'elaborazione in batch riduca l'utilizzo fatturabile. Può ridurre l'overhead delle richieste HTTP, ma qualsiasi effetto sui costi dipende dalle effettive regole di contabilizzazione del provider. Allo stesso modo, una dimensione del batch valida non autorizza richieste parallele illimitate.
Prepara i record prima di creare la richiesta
La maggior parte degli errori di batch evitabili nasce dalla preparazione degli input. Convalida ogni spedizione prima di aggiungerla a un batch, ma evita regole che rifiutino accidentalmente numeri di tracciamento legittimi di corrieri diversi.
- Conserva i numeri di tracciamento come stringhe. Convertirli in numeri può rimuovere gli zeri iniziali o alterare identificativi lunghi.
- Rimuovi gli spazi bianchi accidentali circostanti. Non rimuovere i caratteri interni né modificare maiuscole e minuscole, a meno che la specifica pertinente consenta tale normalizzazione.
- Convalida i campi obbligatori. Alcuni flussi di lavoro possono richiedere un identificativo del corriere o ulteriori informazioni sulla spedizione. Utilizza solo nomi e valori dei campi documentati.
- Scegli un ambito esplicito per la deduplicazione. Un numero di tracciamento ripetuto non è automaticamente un duplicato per ogni corriere, commerciante o spedizione storica.
- Conserva un identificativo locale della spedizione. Memorizza la relazione tra l'elemento inviato e il tuo ordine o record della spedizione, anche quando l'API non accetta campi di riferimento personalizzati.
Per il Carrier Tracking su più reti, non dedurre il corriere esclusivamente dalla lunghezza o dal prefisso di un numero di tracciamento, a meno che tale deduzione sia affidabile per il tuo specifico flusso di lavoro. Quando l'API supporta l'identificazione del corriere, segui il comportamento documentato per la gestione delle ambiguità.
Struttura illustrativa della richiesta
Il seguente JSON mostra il concetto di un payload batch. Il wrapper, i nomi delle proprietà e gli identificativi sono illustrativi e non costituiscono uno schema di richiesta 17TRACK. Alcune API richiedono un array al livello principale invece di un oggetto contenente un array.
{
"shipments": [
{
"tracking_number": "EXAMPLE000001",
"carrier_id": "DOCUMENTED_CARRIER_ID"
},
{
"tracking_number": "EXAMPLE000002",
"carrier_id": "DOCUMENTED_CARRIER_ID"
}
]
}Costruisci il payload tramite un serializzatore JSON anziché concatenare stringhe. Invia le credenziali di autenticazione attraverso il meccanismo documentato e tienile fuori dal controllo del codice sorgente, dal codice distribuito al browser e dai log ordinari.
Elabora la risposta a due livelli
Una richiesta batch ha un esito a livello di trasporto e un esito a livello applicativo. La tua integrazione deve valutare entrambi.
Livello 1: la richiesta ha ricevuto una risposta utilizzabile?
Inizia dallo stato HTTP, dagli header della risposta e dal corpo della risposta. Errori di autenticazione, richieste non valide, limitazioni della frequenza ed errori del server possono impedire la normale elaborazione degli elementi. Un timeout di rete è diverso: il client potrebbe non sapere se il server ha ricevuto o elaborato la richiesta.
La semantica HTTP è definita in RFC 9110. Tuttavia, la documentazione del provider determina il modo in cui i campi dei risultati a livello applicativo corrispondono agli esiti effettivi delle spedizioni.
Livello 2: cosa è successo a ogni spedizione?
Se la risposta supporta risultati a livello di elemento, classifica ogni record inviato. Non presumere che HTTP 200 significhi che ogni record sia riuscito o che un elenco di risultati mantenga l'ordine della richiesta, a meno che il contratto non lo garantisca esplicitamente.
- Accettato: L'operazione è riuscita secondo la definizione documentata dell'endpoint.
- Errore permanente di input: Correggi o analizza il record prima di un nuovo tentativo.
- Errore ripetibile: Pianifica un altro tentativo secondo le indicazioni del provider.
- Esito sconosciuto: La risposta è assente, incompleta o non può essere associata in modo sicuro al record inviato.
Mantieni separate le risposte come “già registrato” o altre risposte simili relative ai duplicati finché non ne comprendi il significato documentato. Possono indicare che lo stato desiderato esiste già, ma non devono essere trattate automaticamente come conferma di titolarità, configurazione o sottoscrizione riuscita.
Dopo aver elaborato una risposta, ogni record di input dovrebbe avere esattamente un esito locale. Un controllo di riconciliazione utile è: record inviati uguale record accettati più errori permanenti più errori ripetibili più esiti sconosciuti. Questa è una regola contabile locale, non un formato di risposta API obbligatorio.
Gestisci gli errori parziali senza ripetere i record riusciti
Supponiamo che un batch illustrativo contenga dieci spedizioni: sette vengono accettate, due presentano campi obbligatori non validi e una incontra un errore temporaneo documentato. Salva i sette esiti riusciti, indirizza i due record non validi alla correzione e ripeti il tentativo solo per l'errore temporaneo.
Ripetere tutti e dieci i record crea traffico inutile e può complicare la gestione dei duplicati. Inoltre rende più difficile distinguere un rifiuto originale da una risposta successiva relativa a un duplicato.
| Esito | Azione consigliata |
|---|---|
| Campo non valido o valore non supportato | Correggere l'input; non ripetere il tentativo senza modificarlo |
| Errore di autenticazione o autorizzazione | Sospendere il lavoro interessato e correggere le credenziali o l'accesso |
| Risposta di limitazione della frequenza | Attendere secondo le indicazioni documentate e gli eventuali header della risposta |
| Errore temporaneo a livello di elemento | Ripetere il tentativo per quell'elemento con un numero limitato di tentativi e backoff |
| Timeout dopo l'invio | Contrassegnare come incerto; riconciliare o utilizzare le garanzie documentate sulla sicurezza dei nuovi tentativi |
| Risultato non riconosciuto o incompleto | Conservare le prove e analizzare il caso invece di presumere il successo |
HTTP 429 indica un numero eccessivo di richieste e la risposta può includere un header Retry-After, come descritto in RFC 6585. Non presumere che tale header sia sempre presente. Quando non viene fornito alcun ritardo esplicito, utilizza una politica di backoff limitata e coerente con la documentazione dell'API.
Aggiungi jitter per distribuire i nuovi tentativi provenienti da più worker, imposta un numero massimo di tentativi o un'età massima del retry e invia i record esauriti a una coda di revisione. Ripetere i tentativi indefinitamente può nascondere un problema di configurazione persistente.
Perché i timeout richiedono un trattamento speciale
Un timeout non dimostra un rifiuto. Il server potrebbe aver accettato il batch prima che la connessione fallisse. Ripetere automaticamente una richiesta che modifica lo stato può quindi ripetere il lavoro.
Se l'endpoint supporta chiavi di idempotenza documentate, segui le relative regole, compresi l'ambito e la conservazione della chiave. Non inventare un header di idempotenza presumendo che il server lo rispetti. In caso contrario, utilizza un flusso di ricerca o riconciliazione supportato per determinare se lo stato desiderato esiste prima di inviare nuovamente la richiesta. La deduplicazione locale aiuta a coordinare i tuoi worker, ma non garantisce l'idempotenza lato server.
Un flusso di elaborazione batch pratico
Mantieni i dettagli specifici del provider in un adapter, in modo che la coda, lo scheduler dei retry e la logica di monitoraggio non dipendano dai nomi grezzi dei campi della risposta.
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
Rendi recuperabili la persistenza degli esiti e la pianificazione dei retry. Ad esempio, un record di lavoro durevole o un modello transazionale di accodamento può impedire che un arresto del processo faccia perdere la decisione sul retry. Quando i worker si riavviano, devono poter distinguere il lavoro non inviato da quello il cui esito remoto è ancora incerto.
Utilizza la dimensione del batch come impostazione configurabile collegata all'endpoint pertinente, non come costante distribuita nel codice. Un batch più piccolo può essere utile durante la risoluzione dei problemi o l'isolamento di record problematici; il batch più grande consentito non è automaticamente la dimensione operativa migliore.
Monitora gli esiti delle spedizioni, non solo il tempo di attività HTTP
Il monitoraggio API dovrebbe mostrare se le spedizioni stanno raggiungendo lo stato previsto. Un dashboard che segnala solo i tassi di successo HTTP può non rilevare errori parziali all'interno di risposte altrimenti riuscite.
- Tasso di accettazione degli elementi: Record accettati divisi per record inviati, con un trattamento chiaramente definito dei retry.
- Distribuzione degli errori: Conteggi per endpoint, codice di errore documentato e contesto del corriere pertinente.
- Esiti sconosciuti: Record non riconciliati e durata della loro permanenza senza soluzione.
- Arretrato dei retry: Nuovi tentativi in sospeso, età del retry più vecchio e tentativi esauriti.
- Stato delle richieste: Latenza, timeout, limitazioni della frequenza ed errori del server.
- Freschezza del tracciamento: Verifica che le spedizioni accettate ricevano successivamente informazioni di tracciamento utilizzabili.
L'accettazione della registrazione non dimostra la presenza di una nuova scansione del corriere. Mantieni separati lo stato di elaborazione dell'API, il movimento della spedizione e la freschezza dei dati, affinché un incidente dell'integrazione non venga confuso con un ritardo nella consegna.
Registra gli ID locali dei batch, i riferimenti delle spedizioni, il numero di tentativi, i codici di errore documentati e gli ID delle richieste del provider quando disponibili. Oscura le credenziali e le informazioni personali non necessarie. Utilizza gli identificativi di tracciamento solo quando sono necessari per le operazioni ed evita di inserire identificativi grezzi delle spedizioni nelle etichette delle metriche ad alta cardinalità.
Testa questi casi prima della produzione
Utilizza, quando disponibile, un sandbox documentato o un ambiente di test controllato. Non presumere che numeri di tracciamento inventati producano risposte prevedibili in produzione.
- Invia un batch valido al limite documentato degli elementi, quindi verifica come il client impedisce l'invio di un batch troppo grande.
- Verifica che i numeri di tracciamento con zeri iniziali sopravvivano alla serializzazione e alla memorizzazione.
- Testa elementi accettati e rifiutati nello stesso batch senza ripetere i tentativi per i record riusciti.
- Simula la limitazione della frequenza e conferma che più worker rispettino lo stesso limite.
- Simula un timeout dopo l'invio e verifica il percorso di riconciliazione.
- Riavvia un worker tra la ricezione della risposta e la persistenza locale.
- Testa risultati degli elementi mancanti, non familiari o non associabili.
- Conferma che i record non validi raggiungano una coda di correzione visibile invece di essere ripetuti all'infinito.
Un'integrazione pronta per la produzione può spiegare lo stato di ogni spedizione inviata, comprese quelle il cui esito è temporaneamente sconosciuto. Ridurre il numero di richieste è utile; preservare questa responsabilità è l'obiettivo progettuale più importante.
FAQ
Quanti numeri di tracciamento posso inviare in un'unica richiesta?
Utilizza il limite documentato per l'endpoint e la versione dell'API esatti. Controlla inoltre la dimensione della richiesta, i limiti di frequenza e gli eventuali vincoli specifici dell'account. Non esiste un numero universale sicuro da applicare a tutte le Tracking API o a operazioni diverse all'interno della stessa API.
Un numero di tracciamento non valido può causare il fallimento dell'intero batch?
Sì, a seconda delle regole di convalida dell'endpoint. Alcune API restituiscono rifiuti individuali, mentre altre possono rifiutare una richiesta prima di elaborare gli elementi. Controlla sia gli errori a livello di richiesta sia i risultati a livello di elemento; non presumere che ogni endpoint batch supporti l'accettazione parziale.
Devo ripetere un batch quando la risposta HTTP ha esito positivo?
Non automaticamente. Analizza prima lo stato applicativo documentato e i risultati degli elementi. Salva i record riusciti e ripeti il tentativo solo per gli errori idonei. Se il risultato non può essere interpretato in modo sicuro, classificalo come incerto e analizzalo.
Posso combinare corrieri diversi nello stesso batch?
Solo quando l'endpoint supporta tale struttura della richiesta. Conferma se le informazioni sul corriere vengono fornite per ogni spedizione, se è supportata l'identificazione automatica e cosa accade quando l'identificazione è ambigua. Un servizio multi-corriere non stabilisce di per sé le regole di batch di ogni endpoint.
L'elaborazione in batch fa arrivare più velocemente gli aggiornamenti di tracciamento?
L'elaborazione in batch può ridurre il numero di richieste inviate dall'applicazione, ma da sola non fa comparire prima gli eventi del corriere. Registrazione, recupero dei dati, disponibilità delle scansioni del corriere e consegna degli aggiornamenti sono parti separate del flusso di lavoro.
Fonti
- 17TRACK Tracking API — punto di accesso ufficiale al prodotto per gli sviluppatori che valutano un'integrazione di tracciamento.
- Documentazione API 17TRACK — riferimento per il contratto dell'endpoint specifico del provider, i limiti, l'autenticazione e la gestione delle risposte.
- RFC 9110: HTTP Semantics — semantica degli stati HTTP, idempotenza, retry automatici e Retry-After.
- RFC 6585: Additional HTTP Status Codes — definizione di HTTP 429 Too Many Requests e del relativo header Retry-After facoltativo.


