Quali campi della risposta dell’API di tracciamento consentono di creare una cronologia completa del tracciamento della spedizione?
Una timeline completa del tracciamento della spedizione richiede più di uno stato corrente. Per ogni evento di tracciamento, conserva un identificativo della spedizione, un timestamp dell’evento, la descrizione o il codice dell’evento del corriere, uno stato normalizzato quando disponibile e la posizione dell’evento quando fornita. Aggiungi il contesto del corriere e del numero di tracciamento, i dettagli della consegna o dell’eccezione e un modo per preservare l’ordine degli eventi e gli aggiornamenti. I nomi esatti dei campi variano a seconda dell’API; l’obiettivo è ricostruire cosa è successo, quando, dove e a quale pacco.
Per uno sviluppatore che sta realizzando una pagina dell’ordine, una dashboard di assistenza o un flusso di lavoro logistico, la distinzione più utile è tra il riepilogo della spedizione e la cronologia degli eventi. Un riepilogo risponde a “Qual è l’ultimo stato noto?”. Una timeline risponde a “Come ha raggiunto la spedizione quello stato?”. Entrambi sono necessari, ma non devono essere considerati intercambiabili.
Inizia dall’identità della spedizione, non dallo stato
Ogni evento deve essere associato alla spedizione corretta. Un numero di tracciamento è spesso il punto di partenza, ma non dovrebbe essere l’unico identificativo nel modello dati interno. Conserva l’identificativo della spedizione o del record di tracciamento dell’API, se fornito, insieme agli identificativi dell’ordine e del pacco utilizzati internamente. Registra l’identificativo o il nome del corriere e, quando pertinente, il contesto della destinazione o dell’origine utilizzato per identificare la spedizione.
Questo è importante quando un ordine contiene più pacchi, quando un numero di tracciamento viene corretto oppure quando un passaggio di consegna introduce un altro corriere o numero di riferimento. Se un’API espone numeri di tracciamento correlati o dettagli del passaggio tra corrieri, conserva la relazione invece di unire due cronologie solo perché appartengono allo stesso ordine. Un ordine può avere diverse timeline di spedizione valide.
A livello di evento, un insieme pratico di identificativi include il riferimento della spedizione, il corriere responsabile dell’evento, se noto, e un ID evento stabile fornito dall’API oppure dati sorgente sufficienti a identificare un evento ripetuto. Non presumere che due scansioni con lo stesso stato siano duplicati: un pacco può ricevere lo stesso tipo di scansione in strutture o momenti diversi.
I campi della risposta che rendono utile ogni evento
I nomi dei campi come event_time e status riportati di seguito descrivono i ruoli dei dati, non uno schema universale per le API di tracciamento. Mappali sulla risposta effettiva documentata dal tuo fornitore.
- Ora dell’evento: l’ora in cui il corriere dichiara che l’evento si è verificato. Conserva il valore originale e le informazioni sul fuso orario quando fornite. Normalmente questo è il timestamp principale per una timeline destinata ai clienti.
- Descrizione dell’evento o codice del corriere: il testo originale della scansione o il codice dell’evento leggibile dalla macchina. Conservare il valore sorgente rende verificabile un’etichetta normalizzata e aiuta i team di assistenza a esaminare scansioni non familiari.
- Stato normalizzato: una categoria a livello del fornitore o dell’applicazione, come in transito, in consegna, consegnato o eccezione. Usalo per raggruppare gli eventi, ma non lasciare che sostituisca i dettagli originali della scansione.
- Posizione: la struttura, la città, la regione, il Paese o altri campi di posizione effettivamente forniti dal corriere. Mostra solo il livello di precisione presente nella risposta; non trasformare una scansione a livello nazionale in una posizione implicita a livello stradale.
- Contesto del corriere e del tracciamento: l’identificativo del corriere, il numero di tracciamento e qualsiasi numero correlato necessario per spiegare un passaggio di consegna o distinguere i pacchi.
- Metadati dell’evento: un ID evento sorgente, un numero di sequenza o un altro riferimento del fornitore, se disponibile. Questi campi possono aiutare con la deduplicazione, le correzioni e l’ordinamento stabile.
È comunque possibile creare una timeline utile anche quando mancano alcuni campi facoltativi. Ad esempio, un evento “consegnato” valido potrebbe non avere una posizione di consegna pubblica. L’applicazione deve mostrare l’evento confermato senza inventare una posizione o un destinatario.
Mantieni separata l’ora dell’evento dall’ora di elaborazione
I sistemi di tracciamento possono esporre diversi timestamp: quando è avvenuta una scansione, quando il corriere l’ha pubblicata, quando un fornitore API l’ha registrata e quando l’ha ricevuta la tua applicazione. Questi dati rispondono a domande diverse. Ordina il viaggio visualizzato principalmente in base all’ora di occorrenza dell’evento quando è affidabile; usa l’ora di acquisizione per spiegare quando il tuo sistema ha appreso dell’evento e per rilevare gli aggiornamenti arrivati in ritardo.
I dati ricevuti in ritardo sono abbastanza comuni da dover essere considerati nella progettazione. Un corriere può pubblicare una scansione precedente dopo che una successiva è già visibile. Se l’applicazione aggiunge semplicemente ogni nuova risposta API in fondo alla pagina, la timeline risultante potrebbe essere cronologicamente errata. Riconcilia gli eventi con la cronologia memorizzata e poi ordinali secondo una regola documentata. Se due eventi hanno la stessa ora di occorrenza, una sequenza sorgente o un ID evento può fungere da criterio di spareggio. In caso contrario, mantieni un ordine interno deterministico senza affermare che sia stato stabilito dalla fonte.
La gestione dei fusi orari richiede particolare attenzione. Un timestamp con offset può essere normalizzato per la memorizzazione, mantenendo disponibile il timestamp originale per la visualizzazione o l’analisi. Un timestamp senza offset indicato non deve essere interpretato silenziosamente come UTC. Per le integrazioni che accettano o emettono timestamp Internet, RFC 3339 è un riferimento utile per la rappresentazione dei timestamp; da solo, però, non indica quale fuso orario intendesse il corriere quando i dati ne omettono uno.
Separa lo stato più recente dalla cronologia completa
Molte risposte di tracciamento includono sia lo stato corrente della spedizione sia un elenco degli eventi storici. Lo stato corrente è utile per una scheda compatta dell’ordine, per i filtri e per le notifiche. La cronologia è la fonte della sequenza delle scansioni. Non creare un nuovo evento storico ogni volta che interroghi uno stato corrente invariato e non eliminare gli eventi precedenti solo perché l’oggetto dello stato più recente è completo.
Evita inoltre di presumere che l’ultimo elemento di un array sia la scansione più recente. Verifica le regole di ordinamento del fornitore, quindi ordina o riconcilia di conseguenza. Una risposta può contenere solo un sottoinsieme della cronologia oppure un’integrazione potrebbe dover recuperare pagine aggiuntive. Se l’API documenta la paginazione o un limite della cronologia, segui quel meccanismo prima di descrivere il viaggio visualizzato come completo. Quando la cronologia non è disponibile, indica che la vista mostra gli eventi ricevuti invece di suggerire che non si siano verificate scansioni precedenti.
Per una rappresentazione interna solida, memorizza la risposta grezza o i campi sorgente necessari a riprodurre la tua interpretazione, insieme a un record di evento normalizzato. Conservare i valori sorgente è particolarmente utile quando cambia una mappatura: puoi rielaborare gli eventi precedenti senza chiedere a un corriere di ricreare dati che potrebbero non essere più recuperabili.
Modella con attenzione traguardi, eccezioni e prove di consegna
Un’etichetta di stato non è sempre un traguardo. “In transito” può riassumere diverse scansioni, mentre “in consegna” e “consegnato” rappresentano solitamente fasi distinte. Crea i traguardi a partire dai significati documentati degli eventi invece di presumere che ogni corriere utilizzi una terminologia identica. Se uno stato è ambiguo, mostra la descrizione originale ed evita di aggiungere un’affermazione più forte.
Gli eventi di eccezione richiedono sia una categoria sia i dettagli del corriere, quando disponibili. “Consegna tentata” racconta una storia diversa da “Sdoganamento in attesa”, anche se un’applicazione raggruppa entrambi in uno stato che richiede attenzione. Conserva il testo della motivazione, il codice della motivazione e le informazioni sulla prossima azione come campi separati, se la risposta li fornisce. In questo modo un operatore di assistenza può distinguere un ritardo temporaneo da un evento che potrebbe richiedere un’azione da parte del destinatario.
La conferma della consegna deve essere trattata con la stessa attenzione. Se la risposta include un evento di consegna, registra il timestamp e i dettagli disponibili sulla posizione o sul destinatario. Se include informazioni sulla prova di consegna, conserva il tipo di prova e le eventuali restrizioni di accesso definite dal fornitore. Non dedurre una firma, una fotografia o un destinatario nominativo dal solo stato “consegnato”. Allo stesso modo, una data di consegna stimata è una previsione, non un evento completato; visualizzala separatamente dalla timeline storica.
Un flusso di mappatura pratico per gli sviluppatori
- Esamina una risposta reale e la relativa documentazione. Identifica l’oggetto a livello di spedizione, l’array degli eventi, i formati dei timestamp, il vocabolario degli stati e gli eventuali limiti o la paginazione documentati. Non presumere che i nomi dei campi illustrativi di un articolo corrispondano a uno schema di produzione.
- Definisci un unico modello interno degli eventi. Includi l’identità della spedizione, il corriere sorgente, l’ora di occorrenza, il testo o codice di stato originale, la categoria normalizzata, la posizione facoltativa, l’identificativo dell’evento sorgente e l’ora di ricezione. Rendi nullabili i campi facoltativi invece di completarli con supposizioni.
- Scrivi regole di mappatura esplicite. Registra come ogni campo sorgente diventa un campo interno e quale valore sorgente supporta ogni stato normalizzato. Mantieni visibili i codici sconosciuti per la revisione invece di forzarli in un traguardo inesatto.
- Riconcilia le risposte ripetute. Usa un ID evento documentato quando disponibile. In caso contrario, definisci una regola prudente di corrispondenza basata su valori sorgente stabili e testala con più scansioni che condividono legittimamente lo stesso stato.
- Testa i percorsi complessi. Includi più pacchi, scansioni tardive, timestamp uguali, passaggi tra corrieri, tentativi di consegna, posizioni mancanti, stime modificate e un evento di consegna con dettagli di conferma limitati.
- Verifica ciò che promette l’interfaccia. La timeline deve distinguere gli eventi osservati dalle previsioni, preservare l’incertezza ed evitare di presentare una cronologia incompleta come un resoconto completo della spedizione.
Per un’integrazione con la Tracking API di 17TRACK, utilizza la documentazione ufficiale dell’API per confermare la struttura effettiva della risposta e il significato dei campi prima di implementare questa mappatura. I ruoli dei campi in questa guida sono una checklist di implementazione, non un’affermazione secondo cui 17TRACK restituisca campi con questi nomi esatti o che ogni corriere fornisca ogni dettaglio.
Che cosa si considera una timeline completa?
Una timeline è completa per la tua applicazione quando collega ogni evento visualizzato al pacco corretto, conserva l’evento sorgente e il relativo orario, ordina gli eventi noti in modo coerente e rappresenta stato, posizione, eccezioni e conferma della consegna solo nella misura supportata dalla risposta. La completezza operativa richiede inoltre di conoscere i limiti dei dati: se l’API ha restituito l’intera cronologia disponibile, una finestra limitata oppure solo eventi relativi a un determinato corriere o record di tracciamento.
Il miglior test di accettazione non è il numero di campi compilati. È capire se un cliente o un operatore di assistenza può leggere il percorso senza essere indotto in errore. Se l’applicazione può rispondere a cosa è successo, quando è successo, a quale spedizione si riferisce e cosa rimane incerto, i campi della risposta stanno svolgendo il loro compito.
FAQ
Un campo con lo stato corrente è sufficiente per creare una timeline della spedizione?
No. Uno stato corrente fornisce un’istantanea. Una timeline richiede record di eventi storici con timestamp e il contesto necessario per associare ogni record alla spedizione corretta.
Devo mostrare il testo delle scansioni del corriere o solo gli stati normalizzati?
Conserva entrambi quando l’API li fornisce. Gli stati normalizzati rendono il percorso più facile da consultare; le descrizioni originali mantengono i dettagli e aiutano a spiegare eventi insoliti o specifici del corriere.
Quale timestamp deve determinare l’ordine degli eventi?
Usa l’ora di occorrenza dell’evento quando il suo significato e il fuso orario sono sufficientemente chiari. Conserva separatamente l’ora di ricezione dell’API e definisci un criterio di spareggio stabile per gli eventi con tempi di occorrenza identici o incerti.
Cosa devo fare se un evento di tracciamento non ha una posizione?
Mostra l’evento senza posizione. L’assenza dei dati di posizione non rende l’evento non valido, ma non giustifica l’inferenza di una struttura, una città o un indirizzo di consegna.
Come posso capire se l’API ha restituito l’intero percorso?
Controlla nella documentazione del fornitore l’ambito della cronologia, la paginazione e i limiti della risposta, quindi verifica come la tua integrazione recupera gli eventi aggiuntivi. Se l’ambito non può essere confermato, descrivi la timeline come l’insieme degli eventi disponibili per la tua applicazione.
Fonti
- Panoramica della Tracking API di 17TRACK — contesto del prodotto per l’esempio di integrazione.
- Documentazione dell’API di 17TRACK — riferimento per verificare i campi e il comportamento della risposta specifici dell’implementazione.
- RFC 3339: data e ora su Internet — riferimento per la rappresentazione dei timestamp.


