Skip to main content
CasaBlogGuide6 controlli per verificare gli ultimi eventi di tracciamento del corriere sincronizzati tramite la tua API

6 controlli per verificare gli ultimi eventi di tracciamento del corriere sincronizzati tramite la tua API

17TRACK

Per verificare che la tua API abbia sincronizzato gli eventi di tracciamento più recenti del corriere, confronta l’identità della spedizione, i timestamp degli eventi, i dettagli degli eventi, il percorso di consegna, l’ordine degli eventi e l’aggiornamento dei dati con una visualizzazione di tracciamento indipendente. Una risposta API riuscita o una conferma del webhook conferma solo una parte di questa catena; da sola, non dimostra che la tua applicazione disponga dell’evento più recente del corriere.

6 controlli per verificare la sincronizzazione degli eventi di tracciamento più recenti del corriere

Questa guida è destinata agli sviluppatori e ai team operativi responsabili dell’inserimento dei dati di tracciamento in un sistema di gestione degli ordini, in una pagina rivolta ai clienti, in uno strumento di assistenza o in un flusso di avvisi. L’obiettivo è individuare dove un evento è andato perso o è cambiato, quindi decidere se ritentare l’elaborazione, correggere una mappatura o attendere nuove informazioni dal corriere.

Prima di iniziare: definisci cosa significa “più recente”

Mantieni distinti tre momenti: quando il corriere dichiara che si è verificato un evento, quando il tuo provider di tracciamento lo ha ricevuto o reso disponibile e quando la tua applicazione lo ha memorizzato. Questi momenti possono differire. Un corriere può pubblicare una scansione dopo l’evento fisico, mentre la tua integrazione può elaborarla ancora più tardi. L’evento più recente in base all’orario di accadimento non è quindi necessariamente il record ricevuto più di recente.

Scegli un punto di confronto prima di iniziare l’analisi. Idealmente, usa la pagina di tracciamento del corriere o un altro record autorizzato fornito dal corriere per la stessa spedizione. Se non è disponibile, confronta la tua applicazione con la risposta API corrente del provider di tracciamento. Questo confronto più limitato può stabilire se la tua applicazione corrisponde al provider; non può stabilire che il provider disponga già di tutte le scansioni del corriere. Registra quando hai effettuato il confronto, in modo che un aggiornamento successivo non faccia sembrare incoerente un risultato precedente.

1. Conferma che entrambi i sistemi si riferiscano alla stessa spedizione

Inizia con il numero di tracciamento, il corriere e qualsiasi identificativo dell’account o della spedizione utilizzato dalla tua integrazione. I soli numeri di tracciamento potrebbero non essere sufficienti per la risoluzione dei problemi: un numero può essere inserito con un errore di battitura, associato al corriere sbagliato o riutilizzato in un record interno dopo la modifica di un ordine. Un numero d’ordine e un numero di tracciamento hanno inoltre funzioni diverse. Un ordine può contenere più pacchi, quindi controllare lo stato più recente dell’ordine può nascondere un pacco non aggiornato.

  • Individua il numero di tracciamento e il corriere esatti inviati all’API di tracciamento.
  • Conferma quale record interno della spedizione o del pacco ha ricevuto la risposta.
  • Verifica se la spedizione è stata sostituita, divisa, annullata o riassegnata dopo la registrazione.
  • Confronta il corriere e il numero mostrati nel record sorgente con quelli mostrati nella tua applicazione.

Se gli identificativi non corrispondono, smetti di considerare la differenza come un ritardo di sincronizzazione. Correggi prima l’associazione, quindi ripeti il confronto degli eventi. Archivia nei log diagnostici identificativi sufficienti per tracciare una spedizione senza inserire credenziali sensibili dell’account.

2. Confronta gli orari degli eventi senza perderne il significato

Per ogni candidato evento più recente, acquisisci l’orario di accadimento riportato dal corriere, il relativo fuso orario o offset indicato, se fornito, e gli orari di ricezione e memorizzazione della tua applicazione. Converti i timestamp in una base temporale comune per il confronto, ma conserva il valore originale. RFC 3339 definisce un formato di timestamp Internet con informazioni esplicite sull’offset; è un riferimento utile nella progettazione dei tuoi campi timestamp. Non garantisce che un corriere o un provider fornisca un fuso orario per ogni evento.

Una visualizzazione contenente solo l’ora, un fuso locale presunto o un parser che elimina silenziosamente un offset può spostare un evento a un altro giorno di calendario o collocarlo nella sequenza sbagliata. Quando la fonte fornisce un’ora locale ambigua, contrassegna il confronto come incerto invece di inventare un istante UTC preciso. Distingui inoltre l’orario di accadimento di un evento dall’orario della risposta API: una risposta recuperata ora può legittimamente contenere un evento avvenuto in precedenza.

Annota l’orario in cui hai controllato la visualizzazione del corriere o del provider. Se la fonte ha pubblicato una nuova scansione dopo la tua richiesta API, una differenza tra le due visualizzazioni non dimostra che la richiesta precedente non sia riuscita.

3. Controlla il payload dell’evento, non solo lo stato principale

Confronta la descrizione dell’evento più recente, la posizione, lo stato o il codice del corriere e gli eventuali campi di consegna pertinenti con il record upstream. Uno stato normalizzato come “in transito” può riassumere diverse scansioni distinte. Se la tua applicazione memorizza solo il riepilogo, può sembrare invariata anche se è arrivato un nuovo evento.

Esamina la risposta API grezza o il corpo del webhook conservato, laddove le tue regole di gestione dei dati lo consentano. Segui quindi l’evento attraverso l’analisi, la mappatura dei campi, la persistenza e la presentazione. Cerca campi null sovrascritti da valori predefiniti, codici di stato imprevisti inseriti in una categoria generica, testo troncato o un’interfaccia utente che visualizza solo determinati tipi di evento. Una discrepanza nell’etichetta dello stato è diversa da un evento mancante: indica una logica di trasformazione o visualizzazione, non di consegna.

Non dedurre l’avvenuta consegna solo perché una posizione o uno stato sembrano finali. Conferma l’evento specifico e i campi su cui si basa il tuo flusso di lavoro. Al contrario, uno stato generale invariato non dimostra che la sincronizzazione si sia interrotta; una scansione appena ricevuta potrebbe essere mappata nella stessa categoria. Il tuo record diagnostico dovrebbe conservare sia l’evento upstream sia il valore mostrato agli utenti.

4. Traccia come l’evento ha raggiunto la tua applicazione

Se utilizzi i webhook, controlla il log di ricezione per la spedizione e l’evento pertinenti. Verifica che il tuo endpoint abbia accettato la richiesta, che il messaggio abbia superato la validazione e che l’elaborazione a valle sia stata completata. Una risposta HTTP di successo dal tuo endpoint non dimostra che un worker successivo della coda abbia salvato l’evento. Se l’elaborazione è asincrona, esamina sia la richiesta in entrata sia l’esito del job.

Se interroghi un’API, controlla l’ultima richiesta completata, l’identificativo della spedizione contenuto nella richiesta, la relativa risposta e qualsiasi logica di paginazione o recupero utilizzata dalla tua integrazione. Una richiesta riuscita può essere comunque seguita da una scrittura del database non riuscita o dalla lettura di una cache obsoleta. Utilizza la documentazione applicabile del provider per verificare i campi effettivi della risposta, i requisiti di autenticazione e il comportamento della consegna per la tua integrazione, invece di presumere che ogni API di tracciamento segua lo stesso contratto. Per un’integrazione 17TRACK, i punti di partenza pertinenti sono la sua pagina Tracking API e la documentazione API; conferma il comportamento documentato per l’endpoint e il metodo che utilizzi.

Rendi l’elaborazione degli eventi sicura da ripetere. Un nuovo tentativo non dovrebbe creare scansioni duplicate, inviare ripetutamente la stessa notifica al cliente o sostituire uno stato memorizzato più recente con un payload precedente. La chiave duplicata appropriata dipende dai campi effettivamente forniti dal provider. Testa la chiave scelta su eventi distinti che condividono casualmente uno stato o un timestamp; tali eventi non dovrebbero essere accorpati solo perché sembrano simili.

5. Verifica le regole di ordinamento e transizione dello stato

Ordina gli eventi registrati secondo una regola chiaramente definita, quindi controlla il risultato. Molte applicazioni devono distinguere tra “ultimo evento verificatosi” e “ultimo evento ricevuto”. Una scansione precedente ritardata può arrivare dopo una scansione più recente. Se il database rende semplicemente lo stato corrente della spedizione il messaggio elaborato più di recente, quella scansione ritardata può far retrocedere lo stato visualizzato.

Confronta la cronologia memorizzata con quella upstream, non solo il singolo campo dello stato. Verifica se un record appena ricevuto è stato aggiunto, scartato come duplicato o autorizzato ad aggiornare lo stato corrente. Controlla ogni regola che assegna priorità ad alcuni eventi rispetto ad altri. Tale regola può essere intenzionale, ma non dovrebbe nascondere l’evento sottostante o far pensare che il corriere abbia annullato una tappa quando l’applicazione ha semplicemente ricevuto in ritardo una scansione precedente.

Per un test pratico, prendi una spedizione con più di un evento e riproduci i relativi messaggi in un ordine di arrivo diverso in un ambiente non di produzione. Conferma che la cronologia degli eventi rimanga intatta e che lo stato rivolto al cliente segua la regola documentata. Questo fa emergere difetti di ordinamento che un normale test in sequenza non può rilevare.

6. Misura l’aggiornamento dei dati e riconcilia le eccezioni

Infine, confronta ciò che ogni livello conosceva nello stesso momento di osservazione: visualizzazione del corriere, risposta del provider di tracciamento, risultato del webhook in entrata o del polling, record del database e output rivolto al cliente. Indica il primo livello in cui l’evento previsto scompare. Questo limite è più utile di un rapporto generico secondo cui “il tracciamento è in ritardo”.

Misura sia l’età dell’ultimo evento riportato dal corriere sia il tempo trascorso dall’ultima verifica o ricezione dei dati completata con successo dalla tua integrazione. Rispondono a domande diverse. Un pacco potrebbe non avere una nuova scansione del corriere anche se la tua integrazione funziona correttamente; in alternativa, il corriere potrebbe mostrare una nuova scansione mentre la tua ultima richiesta riuscita è precedente. Utilizza soglie di allerta che riflettano i tuoi requisiti operativi e il comportamento osservato. Non promettere ai clienti un intervallo di aggiornamento fisso a meno che gli accordi con il corriere e il provider non lo supportino.

Crea una piccola coda di riconciliazione per le spedizioni i cui record differiscono dalla fonte di confronto scelta. Includi identificativi, l’evento mancante o non corrispondente, i timestamp pertinenti, il primo livello che ha fallito e l’azione successiva. Ad esempio, un evento presente nella risposta del provider ma assente nel database richiede un’indagine sull’integrazione. Un evento presente nel database ma mancante nella pagina di tracciamento richiede un controllo della visualizzazione o della cache. Se il corriere stesso non mostra nuove scansioni, un’altra richiesta API non può crearne una.

Il test operativo è semplice: riesci a identificare la stessa spedizione, individuare il suo ultimo evento upstream noto e seguire quell’evento fino alla visualizzazione rivolta all’utente senza modificarne il significato? In caso contrario, i sei controlli restringono il problema a un limite specifico e forniscono al tuo team il successivo passo da intraprendere con cognizione di causa.

FAQ

Una risposta webhook riuscita significa che l’ultimo evento è sincronizzato?

No. Mostra che il tuo endpoint ha restituito una risposta riuscita a una richiesta. Conferma inoltre che la validazione, l’elaborazione della coda, la memorizzazione nel database e la visualizzazione siano riuscite. Controlla il payload per stabilire quale evento contenesse la richiesta.

Perché la pagina del corriere mostra una scansione più recente della mia risposta API?

Innanzitutto conferma di visualizzare lo stesso pacco e che entrambe le osservazioni siano state effettuate in momenti comparabili. La pubblicazione da parte del corriere e la ricezione o disponibilità di un evento da parte del provider di tracciamento possono avvenire in momenti diversi. Se la differenza persiste, utilizza la documentazione e il processo di assistenza del provider per analizzare la spedizione specifica, invece di presumere una garanzia di aggiornamento.

Devo usare il timestamp dell’evento o l’orario in cui il mio sistema lo ha ricevuto per scegliere lo stato più recente?

Utilizza una regola documentata appropriata al tuo flusso di lavoro e conserva entrambi i valori. Il timestamp dell’evento descrive quando si è verificata l’attività riportata; l’orario di ricezione descrive quando il tuo sistema ne è venuto a conoscenza. Nessuno dei due campi, da solo, risolve ogni caso, in particolare quando gli orari della fonte sono ambigui o le scansioni precedenti arrivano in ritardo.

Cosa succede se lo stato API non cambia ma l’elenco degli eventi contiene una nuova voce?

Potrebbe essere previsto se più eventi del corriere vengono mappati su un unico stato normalizzato. Confronta i dettagli dell’evento e verifica che la tua applicazione abbia memorizzato e visualizzi la nuova voce dove appropriato. Considera un evento mancante e un’etichetta di riepilogo invariata come problemi diversi.

Fonti