Skip to main content
CasaBlogGuideCome inviare più numeri di tracciamento in un'unica richiesta API (limiti dei batch e fallimenti parziali)

Come inviare più numeri di tracciamento in un'unica richiesta API (limiti dei batch e fallimenti parziali)

17TRACK

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.

Come inviare più numeri di tracciamento in un’unica richiesta API

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.

VincoloCosa confermareConseguenza per l'implementazione
Elementi per richiestaNumero massimo di record per l'operazione specificaSuddividere l'elenco di input prima dell'invio
Dimensione del corpo della richiestaEventuale limite di byte documentatoTenere conto dei campi facoltativi e delle dimensioni della serializzazione
Frequenza delle richiesteRichieste consentite in un intervallo definitoRegolare le richieste tramite un limiter condiviso
ConcorrenzaEventuali restrizioni sulle richieste simultaneeLimitare il numero di worker attivi
Contabilizzazione dell'utilizzoSe 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.

  1. Conserva i numeri di tracciamento come stringhe. Convertirli in numeri può rimuovere gli zeri iniziali o alterare identificativi lunghi.
  2. 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.
  3. 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.
  4. Scegli un ambito esplicito per la deduplicazione. Un numero di tracciamento ripetuto non è automaticamente un duplicato per ogni corriere, commerciante o spedizione storica.
  5. 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.

EsitoAzione consigliata
Campo non valido o valore non supportatoCorreggere l'input; non ripetere il tentativo senza modificarlo
Errore di autenticazione o autorizzazioneSospendere il lavoro interessato e correggere le credenziali o l'accesso
Risposta di limitazione della frequenzaAttendere secondo le indicazioni documentate e gli eventuali header della risposta
Errore temporaneo a livello di elementoRipetere il tentativo per quell'elemento con un numero limitato di tentativi e backoff
Timeout dopo l'invioContrassegnare come incerto; riconciliare o utilizzare le garanzie documentate sulla sicurezza dei nuovi tentativi
Risultato non riconosciuto o incompletoConservare 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.

  1. Invia un batch valido al limite documentato degli elementi, quindi verifica come il client impedisce l'invio di un batch troppo grande.
  2. Verifica che i numeri di tracciamento con zeri iniziali sopravvivano alla serializzazione e alla memorizzazione.
  3. Testa elementi accettati e rifiutati nello stesso batch senza ripetere i tentativi per i record riusciti.
  4. Simula la limitazione della frequenza e conferma che più worker rispettino lo stesso limite.
  5. Simula un timeout dopo l'invio e verifica il percorso di riconciliazione.
  6. Riavvia un worker tra la ricezione della risposta e la persistenza locale.
  7. Testa risultati degli elementi mancanti, non familiari o non associabili.
  8. 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