Skip to main content
CasaBlogGuideCome utilizzare le API di tracciamento delle spedizioni per inviare notifiche proattive sulla consegna

Come utilizzare le API di tracciamento delle spedizioni per inviare notifiche proattive sulla consegna

17TRACK

Per inviare notifiche proattive sulla consegna con un'API di tracciamento delle spedizioni, collega ogni pacco al relativo ordine, acquisisci gli aggiornamenti di tracciamento, trasformali in eventi rilevanti per il cliente e attiva i messaggi tramite il tuo servizio di notifiche email, SMS o app. Inserisci una coda persistente e controlli dei duplicati tra i dati di tracciamento in arrivo e i messaggi in uscita, così gli aggiornamenti ripetuti o ritardati non genereranno avvisi confusi.

Come utilizzare le API di tracciamento delle spedizioni per inviare notifiche proattive sulla consegna

Questa guida è destinata agli sviluppatori e ai team operativi ecommerce che stanno realizzando questo flusso di lavoro. L'obiettivo non è inoltrare ogni scansione del corriere, ma informare i clienti quando cambia qualcosa di significativo, spiegare cosa comporta il cambiamento e indicare se devono intervenire.

Progetta il flusso di lavoro delle notifiche prima di collegare l'API

Un'API di tracciamento delle spedizioni fornisce informazioni sul tracking; è la tua applicazione a decidere come utilizzarle. Considera la visibilità della spedizione e la comunicazione con il cliente come responsabilità separate, anche se il servizio scelto offre entrambe.

Un'architettura pratica prevede sei fasi:

  1. Associazione dell'ordine: collega un numero di tracciamento e, se necessario, l'identificativo del corriere a un record interno della spedizione.
  2. Registrazione del tracciamento: invia o registra la spedizione secondo i requisiti di integrazione del provider.
  3. Acquisizione degli aggiornamenti: ricevi callback webhook, recupera gli aggiornamenti tramite richieste API oppure combina entrambi gli approcci.
  4. Elaborazione degli eventi: convalida, normalizza, deduplica e valuta gli eventi in arrivo.
  5. Decisione sulla notifica: scegli se inviare una notifica, chi contattare e quale canale e modello utilizzare.
  6. Invio del messaggio: invia la notifica e registra la risposta del servizio di messaggistica.

Conserva i dati di contatto dei clienti nel tuo sistema degli ordini o di messaggistica, a meno che l'integrazione non richieda realmente di condividerli. In genere un servizio di tracciamento non ha bisogno dell'indirizzo email del cliente solo per consentire alla tua applicazione di associare un evento di tracking a un ordine.

1. Conferma il contratto di integrazione

Prima di scrivere il ricevitore, consulta la documentazione del provider per autenticazione, registrazione delle spedizioni, identificazione del corriere, metodi di aggiornamento supportati, formati delle risposte, limiti delle richieste e gestione degli errori. Per le integrazioni webhook, verifica anche come vengono autenticati i callback, quale risposta conferma la ricezione e come vengono gestite le consegne non riuscite.

Per un'implementazione 17TRACK, inizia dalla pagina dell'API di tracciamento 17TRACK e dalla relativa documentazione ufficiale dell'API. Utilizza il contratto documentato per l'integrazione, invece di considerare i nomi dei campi illustrativi di questa guida come campi di richiesta o risposta di 17TRACK. Conferma la configurazione dei callback, i requisiti di sicurezza e i limiti specifici dell'account prima dell'implementazione.

Scegli il metodo di aggiornamento in base al contratto di integrazione:

  • Webhook: utilizza i callback quando sono supportati e adatti alla tua infrastruttura. Consentono all'applicazione di elaborare gli aggiornamenti quando il provider li invia, senza richiedere ripetutamente le stesse informazioni sulla spedizione.
  • Polling: recupera le informazioni di tracking secondo una pianificazione quando i callback non sono disponibili o non sono adatti. Mantieni la frequenza entro i limiti documentati per le richieste.
  • Approccio combinato: usa i callback per l'elaborazione normale e recuperi API selettivi per riconciliare le spedizioni i cui aggiornamenti risultano obsoleti, se il provider supporta questo flusso.

Non promettere ai clienti notifiche istantanee solo perché utilizzi i webhook. La tua applicazione non può segnalare un evento del corriere prima che i dati di tracking upstream lo rendano disponibile.

2. Crea un record della spedizione in grado di gestire gli ordini reali

Utilizza un ID interno della spedizione come riferimento principale, non il solo numero di tracking. Un ordine può contenere più pacchi e non si deve presumere che i numeri di tracking siano sempre univoci a livello globale.

Un record interno utile comprende:

  • ID interno dell'ordine e ID della spedizione.
  • Numero di tracking e identificativo del corriere, quando noti.
  • Riferimento della spedizione del provider, se fornito.
  • Stato normalizzato corrente e ultimo evento significativo.
  • Orario dell'evento del corriere, incluso il fuso orario o l'offset quando disponibile.
  • Orario in cui il sistema ha ricevuto l'aggiornamento.
  • Riferimento alle preferenze di comunicazione del cliente.
  • Cronologia delle notifiche e qualsiasi flusso attivo per le eccezioni.

Conserva separatamente l'orario dell'evento e quello della ricezione. Una scansione avvenuta in precedenza può arrivare dopo una scansione più recente. Se l'applicazione ordina solo in base all'ordine di arrivo, può erroneamente riportare una spedizione consegnata allo stato “in transito”.

Per gli ordini suddivisi, collega le notifiche al pacco interessato. “Un pacco del tuo ordine è arrivato” è più accurato di “Il tuo ordine è arrivato” quando un altro pacco è ancora in movimento.

3. Associa gli eventi di tracking alle decisioni del cliente

Le descrizioni dei corrieri sono dati operativi, non messaggi per i clienti già pronti. Crea un livello di normalizzazione che conservi l'evento originale assegnandogli al contempo una categoria interna comprensibile dalle regole di notifica.

Le categorie seguenti sono concetti applicativi suggeriti, non un vocabolario universale degli stati API:

Categoria internaDecisione sulla notificaLimite della comunicazione
Informazioni sulla spedizione ricevuteInvia un aggiornamento sulla preparazione solo se utile.Non suggerire che il corriere abbia preso fisicamente in carico il pacco basandosi solo sulla creazione dell'etichetta.
In transitoValuta una notifica al primo movimento significativo.Nascondi le scansioni di routine presso le strutture, a meno che non cambino il passaggio successivo per il cliente.
In consegnaInvia una notifica quando un evento supportato indica questo stato.Non trasformare lo stato in un orario di arrivo garantito.
Tentata consegna o ritiro richiestoInvia una notifica che richieda un'azione.Includi scadenze o istruzioni per il ritiro solo quando sono verificate.
Eccezione di consegnaValuta la causa e se il cliente deve intervenire.Non descrivere ogni eccezione come un pacco smarrito.
ConsegnatoInvia una conferma a livello di pacco.Non inventare il destinatario, il luogo di consegna o una prova di consegna.

Preserva l'incertezza. Un evento non riconosciuto deve entrare in un percorso di revisione o fallback invece di essere forzato nella categoria familiare più vicina. Mantieni disponibile la descrizione originale per il personale di supporto incaricato della risoluzione dei problemi.

4. Ricevi gli aggiornamenti senza perdere o duplicare il lavoro

L'endpoint webhook deve convalidare la richiesta, salvare in modo persistente l'aggiornamento accettato e restituire la conferma richiesta dal provider. Genera i messaggi in modo asincrono invece di attendere un servizio email o SMS durante la richiesta di callback.

Implementa il metodo documentato dal provider per la verifica dei callback. Non inventare un header di firma e non presumere che ogni provider utilizzi lo stesso schema di autenticazione. Applica inoltre HTTPS, limiti alle dimensioni delle richieste, convalida del payload e controlli di accesso adeguati.

Un flusso di elaborazione semplificato è il seguente. Si tratta di operazioni a livello applicativo, non di un esempio funzionante di SDK:

ricevi callback
  verifica la richiesta utilizzando il meccanismo documentato dal provider
  convalida il payload
  salva il payload accettato e accoda atomicamente l'elaborazione
  restituisci la conferma documentata

elabora l'aggiornamento accodato
  individua la spedizione interna
  normalizza gli eventi rilevanti
  ignora gli eventi già elaborati
  valuta la cronologia e la transizione di stato
  crea un'attività di notifica se consentito dalla policy
  conferma insieme lo stato e l'attività

invia l'attività di notifica
  controlla le preferenze del destinatario e le regole di soppressione
  invia il messaggio al servizio di messaggistica
  registra il risultato e riprova solo quando appropriato

I passaggi atomici sono importanti. Se l'applicazione salva una modifica di stato ma si arresta prima di creare l'attività di notifica, il cliente potrebbe non ricevere mai l'avviso. Un outbox transazionale è una possibile soluzione: salva la modifica di stato e l'attività in sospeso nella stessa transazione del database, quindi lascia che un worker invii l'attività.

Gestisci esplicitamente i riferimenti a spedizioni sconosciuti. Mettili in quarantena per esaminarli o riconciliarli invece di indovinare quale cliente debba ricevere una notifica.

5. Aggiungi protezione dai duplicati e controlli cronologici

Progetta il ricevitore in modo che tolleri callback ripetuti e nuovi tentativi dei worker. Preferisci un identificativo stabile dell'evento del provider quando è documentato. In caso contrario, crea un'impronta deterministica dell'evento a partire da campi appropriati, come ID interno della spedizione, codice dell'evento, orario dell'evento e località. Verifica questa impronta con payload reali prima di basarti su di essa.

La deduplicazione degli eventi e la soppressione delle notifiche risolvono problemi diversi. La deduplicazione impedisce che lo stesso evento venga elaborato due volte. La soppressione evita che diverse scansioni distinte generino messaggi sostanzialmente identici per il cliente.

Definisci un'identità della notifica basata sull'evento aziendale. Una conferma di consegna potrebbe utilizzare l'ID della spedizione e la milestone di consegna. Un tentativo di consegna potrebbe richiedere un'identità specifica del tentativo, perché un tentativo successivo può essere un evento realmente nuovo.

Per gli aggiornamenti fuori ordine, confronta i timestamp degli eventi e valuta le transizioni di stato consentite. Non presumere che un callback contenga solo una nuova scansione; verifica se la sua struttura documentata rappresenta un singolo evento, uno snapshot o una cronologia. Invia gli aggiornamenti contraddittori alla riconciliazione invece di eliminare silenziosamente tutte le correzioni.

6. Scrivi messaggi che spieghino cosa succede dopo

Ogni notifica deve indicare il pacco pertinente, il cambiamento confermato e il passaggio successivo per il cliente. Includi un link sicuro per il tracking e un riferimento riconoscibile all'ordine. Evita di esporre indirizzi completi o informazioni personali non necessarie nei messaggi SMS e nelle anteprime sulla schermata di blocco.

Ad esempio:

  • In consegna: “Il tuo pacco relativo all'ordine {order_reference} è in consegna. Segui i suoi progressi qui: {tracking_link}.”
  • Tentata consegna: “Il corriere ha segnalato un tentativo di consegna per il tuo pacco. Consulta la pagina di tracking per conoscere i prossimi passaggi disponibili: {tracking_link}.”
  • Consegnato: “Il corriere ha contrassegnato come consegnato il tuo pacco relativo all'ordine {order_reference}. Visualizza i dettagli disponibili sulla consegna: {tracking_link}.”

Inserisci i segnaposto solo a partire da dati convalidati. Se è disponibile e adatta alla visualizzazione una stima della consegna, indicane chiaramente la natura stimata. Se manca, omettila invece di inventare una data.

Per le eccezioni, distingui un problema della spedizione da un'attività richiesta al cliente. Un'interruzione può richiedere solo una spiegazione; un problema verificato dell'indirizzo può richiedere un'azione. Non indirizzare i clienti a una pagina per pagamenti o caricamento di documenti basandoti esclusivamente su contenuti di tracking in testo libero non attendibili.

Scegli i canali in base alle preferenze del cliente, alle autorizzazioni del canale, all'urgenza e alle norme applicabili. Verifica i requisiti relativi al consenso, alla rinuncia e agli orari di silenzio per le giurisdizioni e i canali di messaggistica utilizzati. Mantieni separate le notifiche del servizio di consegna dalle campagne promozionali, invece di presumere che le stesse autorizzazioni valgano per entrambe.

7. Definisci cosa succede quando il tracking rimane fermo

La comunicazione proattiva dovrebbe coprire la mancanza di progressi oltre ai nuovi eventi, ma il solo silenzio non dimostra che una spedizione sia in ritardo o smarrita.

Crea una regola per il tracking obsoleto utilizzando il livello di servizio, il percorso, l'ultimo evento significativo e qualsiasi stima di consegna supportata. Imposta le soglie sulla base dei tuoi dati operativi e del processo di assistenza, invece di applicare un unico periodo di attesa universale a tutte le spedizioni.

Quando la regola si attiva, verifica eventuali problemi di elaborazione, riconcilia con la fonte di tracking quando supportato e decidi se aprire un'attività interna per l'assistenza. Se informi il cliente, utilizza una formulazione che rifletta ciò che sai: “Non abbiamo ricevuto un nuovo aggiornamento di tracking” è diverso da “Il tuo pacco è smarrito”.

Assegna un responsabile alle eccezioni irrisolte. Un sistema di notifiche che annuncia ripetutamente un problema senza creare un percorso di risoluzione può aumentare la frustrazione del cliente.

8. Testa l'intero percorso prima di abilitare gli invii automatici

Esegui prima il flusso in modalità shadow: acquisisci eventi reali o di test approvati, genera notifiche proposte e controlla i risultati senza contattare i clienti.

  • Riproduci un callback identico e conferma che non crei un altro messaggio.
  • Elabora un evento di transito più vecchio dopo un evento di consegna e controlla lo stato risultante.
  • Testa timestamp mancanti, stati sconosciuti e payload non validi.
  • Simula un errore del database prima della conferma e un errore del worker dopo la persistenza.
  • Testa i timeout del servizio di messaggistica, inclusa una risposta incerta nel caso in cui il servizio abbia già accettato il messaggio.
  • Conferma che le spedizioni suddivise producano una formulazione specifica per ciascun pacco.
  • Verifica i destinatari che hanno revocato il consenso, i dati di contatto non validi e la gestione degli orari di silenzio.
  • Verifica che i link di tracking non espongano le informazioni sull'ordine di un altro cliente.

Monitora i callback accettati, gli errori di elaborazione, l'età della coda, le attività di notifica, la soppressione dei duplicati e gli esiti della messaggistica. Misura separatamente la latenza di elaborazione a partire dall'orario di ricezione del tuo sistema e l'età dell'evento del corriere. Questa distinzione aiuta a identificare se una notifica lenta è dovuta alla disponibilità dei dati upstream o alla tua pipeline.

Inizia con un piccolo insieme di milestone ben comprese. Amplia le regole solo dopo che i team di assistenza e operativi hanno concordato che i messaggi sono accurati, utili e degni di essere ricevuti.

Domande frequenti

Un'API di tracciamento delle spedizioni invia automaticamente email o SMS?

Non necessariamente. L'accesso ai dati di tracking e la messaggistica al cliente sono funzionalità separate. Verifica l'ambito documentato del servizio. In un'integrazione personalizzata, l'applicazione può elaborare gli aggiornamenti di tracking e inviare notifiche tramite un servizio di messaggistica separato.

Devo informare i clienti di ogni scansione di tracking?

Di solito no. Dai priorità alle milestone significative e agli eventi che richiedono un'azione. Diverse scansioni presso le strutture possono rappresentare un normale transito senza modificare ciò che il cliente deve sapere. Mantieni la cronologia dettagliata nella pagina di tracking.

Posso garantire notifiche di consegna in tempo reale?

Puoi impostare e monitorare un obiettivo di elaborazione dopo che il sistema riceve un aggiornamento. Non puoi garantire quando un corriere registrerà o pubblicherà una scansione. Descrivi il servizio in termini che riflettano questa dipendenza.

Come posso evitare messaggi di consegna duplicati?

Utilizza la deduplicazione persistente degli eventi, un'identità separata della notifica per ogni milestone aziendale e la creazione transazionale delle attività. Quando il servizio di messaggistica supporta l'idempotenza, usala come ulteriore salvaguardia. Un semplice controllo dei duplicati in memoria non sopravvive ai riavvii o a più worker.

Cosa deve succedere se il corriere corregge uno stato di consegna?

Conserva entrambi gli eventi e riconcilia lo stato della spedizione. Se la correzione influisce sostanzialmente sul cliente, invia una correzione chiara oppure inoltrala all'assistenza secondo la tua policy. Non rendere lo stato “consegnato” permanentemente irreversibile solo per semplificare il codice.

Fonti

Le seguenti risorse ufficiali costituiscono i riferimenti di implementazione per l'integrazione 17TRACK descritta sopra. Lo schema interno, le regole di notifica e il flusso di elaborazione di questa guida sono raccomandazioni architetturali, non contratti API riportati testualmente.