Come integrare un'API di tracciamento delle spedizioni nel tuo negozio di e-commerce
Per integrare un'API di tracciamento delle spedizioni nel tuo negozio e-commerce, collega il sistema degli ordini al fornitore di tracciamento, invia i dati della spedizione e del corriere tramite una richiesta sicura lato server, salva gli eventi di tracciamento normalizzati e mostra lo stato risultante nelle interfacce per i clienti e per l'assistenza. Un'implementazione affidabile è più che aggiungere un campo per il numero di tracciamento: deve gestire la selezione del corriere, gli aggiornamenti dello stato, le eccezioni di consegna, i nuovi tentativi, la privacy e il modo in cui i clienti utilizzano effettivamente le informazioni post-acquisto.
Questa guida illustra un approccio pratico all'integrazione per proprietari di negozi, sviluppatori e team operativi. Utilizza la documentazione ufficiale della Tracking API di 17TRACK come riferimento, ma gli stessi principi di pianificazione si applicano anche quando si valuta un altro fornitore multi-corriere.
Decidi cosa deve ottenere l'integrazione
Inizia dal risultato aziendale anziché dall'endpoint dell'API. La maggior parte dei negozi vuole ridurre le richieste del tipo “Dov'è il mio ordine?”, offrire agli acquirenti una visione chiara della consegna e aiutare il team operativo a identificare le spedizioni in ritardo prima che il cliente si lamenti. Questi obiettivi richiedono dati e flussi di lavoro diversi.
- Visibilità per il cliente: mostrare lo stato attuale della spedizione, le informazioni sulla consegna stimata quando disponibili, i dettagli del corriere e l'ultimo evento significativo.
- Visibilità operativa: consentire al personale di trovare le spedizioni in ritardo, bloccate, restituite o con eccezioni tra diversi corrieri.
- Comunicazione automatizzata: attivare e-mail, SMS o altre notifiche approvate quando una spedizione raggiunge uno stato definito.
- Coerenza dei dati: convertire le diverse etichette degli eventi dei corrieri in un insieme più ristretto di stati che il tuo negozio possa utilizzare in modo affidabile.
Definisci questi risultati prima di scegliere un metodo di implementazione. Un'API di tracciamento può fornire i dati della spedizione, ma non decide automaticamente quali eventi meritino una notifica al cliente o come il tuo negozio debba gestire un problema relativo all'indirizzo.
Scegli la giusta architettura di integrazione
Un'architettura tipica presenta quattro livelli: la piattaforma e-commerce, un servizio di integrazione, il fornitore di tracciamento e l'esperienza rivolta al cliente. Il servizio di integrazione può essere un'applicazione backend, un sistema di gestione degli ordini o un flusso di lavoro serverless. Mantenere questa logica sul server è generalmente più sicuro che inserire le credenziali API nel codice del browser.
Il flusso di base è il seguente:
- Un ordine pagato viene evaso e riceve un numero di tracciamento e un corriere.
- Il backend invia i dettagli della spedizione al fornitore di tracciamento.
- Il fornitore restituisce un identificativo di tracciamento o i dati di tracciamento secondo la struttura della sua API.
- Il tuo sistema memorizza il riferimento del fornitore e associa gli eventi della spedizione agli stati interni.
- Un processo di aggiornamento pianificato o una notifica di evento supportata aggiorna la spedizione.
- Il tuo negozio, la pagina dell'ordine, gli strumenti di assistenza e il servizio di notifiche leggono dai tuoi dati normalizzati.
Non fare in modo che ogni visualizzazione di pagina chiami il corriere o l'API di tracciamento. Questo design può causare esperienze lente per i clienti, richieste duplicate, problemi di limitazione del traffico e risultati incoerenti. Memorizza l'ultimo stato di tracciamento accettato nel database e aggiornalo tramite processi in background controllati o tramite il meccanismo di aggiornamento supportato dal fornitore.
Conferma la documentazione del fornitore prima di scrivere il codice
Prima dell'implementazione, consulta la documentazione API ufficiale del fornitore per autenticazione, formati delle richieste, campi delle risposte, corrieri supportati, gestione degli errori, meccanismi di aggiornamento e requisiti dell'account. 17TRACK mette a disposizione una pagina del prodotto Tracking API dedicata e la documentazione per sviluppatori. Considera queste pagine l'autorità per il comportamento attuale dell'API, invece di affidarti a esempi copiati da forum o vecchi tutorial di integrazione.
Crea una breve checklist dei requisiti a partire dalla documentazione:
- Come vengono emesse, memorizzate, ruotate e revocate le credenziali API?
- La richiesta richiede un codice corriere o il servizio può identificare il corriere dal numero di tracciamento?
- Quali campi della risposta identificano la spedizione, lo stato, la posizione, i timestamp e il messaggio di eccezione?
- Come vengono forniti gli aggiornamenti asincroni, se l'account li supporta?
- Quali sono i limiti di richiesta documentati, le regole di fatturazione, le aspettative sui timeout e i codici di errore?
- Come devono essere gestiti i numeri di tracciamento duplicati, i numeri non validi, i corrieri sconosciuti e le spedizioni consegnate?
Non dedurre una funzionalità dal nome di un prodotto. Ad esempio, “in tempo reale” può descrivere il posizionamento di un prodotto anziché garantire che ogni evento del corriere appaia immediatamente. La tua implementazione dovrebbe spiegare che le scansioni del corriere possono subire ritardi e che un'API non può creare una scansione che il corriere non ha segnalato.
Prepara i dati dell'ordine e della spedizione
Il momento più utile per creare il tracciamento è normalmente l'evasione della spedizione, non la creazione dell'ordine. Un ordine può essere pagato ma non ancora imballato e un numero di tracciamento può essere generato prima che il pacco venga accettato dal corriere. Decidi quale evento del flusso di evasione deve creare il record di tracciamento.
Come minimo, il record interno della spedizione dovrebbe distinguere i seguenti valori:
- ID interno dell'ordine e ID dell'evasione
- Numero di tracciamento
- Nome o codice del corriere
- Paese o area geografica di destinazione, quando necessario dal punto di vista operativo
- ID di tracciamento del fornitore o riferimento alla sottoscrizione, se restituito
- Stato normalizzato attuale
- Timestamp dell'ultimo evento e dell'ultima sincronizzazione
- Risposta grezza del fornitore o riferimento di audit controllato
Tieni separati i dati dell'ordine e quelli della spedizione. Un ordine può contenere più pacchi, spedizioni divise o corrieri diversi. L'ipotesi di una corrispondenza uno-a-uno tra ordine e numero di tracciamento spesso non funziona quando un magazzino spedisce gli articoli separatamente.
Utilizza un processo idempotente. Se il sistema di evasione ripete la stessa richiesta, l'integrazione dovrebbe aggiornare la spedizione esistente invece di creare sottoscrizioni duplicate o messaggi duplicati per i clienti. Una chiave di idempotenza pratica può combinare l'ID interno dell'evasione, l'identificativo del corriere e il numero di tracciamento, in base ai requisiti del fornitore.
Normalizza gli stati dei corrieri per i clienti
I corrieri utilizzano etichette e sequenze di eventi diverse. Il tuo negozio dovrebbe mantenere un modello interno di stati ridotto, come Informazioni ricevute, In transito, In consegna, Consegnata, Eccezione e Restituita. Conserva l'evento originale del corriere per il personale dell'assistenza, ma utilizza lo stato normalizzato per la logica del negozio.
Le regole di normalizzazione devono essere esplicite. Un evento “etichetta creata” non dovrebbe essere presentato come prova che il pacco è in movimento. “Consegnata” dovrebbe essere trattato come un evento segnalato dal corriere, non come una garanzia che il cliente abbia fisicamente trovato il pacco. Un'eccezione non dovrebbe essere convertita silenziosamente in “in transito” solo perché la spedizione potrebbe proseguire in seguito.
Definisci anche la precedenza degli stati e la gestione delle regressioni. Un feed del corriere in ritardo può arrivare fuori ordine. Confronta i timestamp degli eventi quando disponibili, registra l'evento grezzo ed evita di sostituire uno stato più recente di consegna con uno stato più vecchio di transito. Se i timestamp mancano o sono ambigui, contrassegna il record per un aggiornamento prudente invece di inventare una sequenza.
Costruisci il flusso delle richieste lato server
Il backend dovrebbe convalidare i dati di evasione in ingresso prima di chiamare il fornitore di tracciamento. Verifica che il numero di tracciamento sia presente, rimuovi gli spazi accidentali, convalida il formato previsto quando appropriato e conferma che il valore del corriere sia accettabile. Non rifiutare numeri di tracciamento insoliti ma validi solo perché non corrispondono a un modello locale troppo restrittivo.
Un flusso di richiesta indipendente dal fornitore può essere rappresentato così:
ricevi l'evento di evasione
convalida i campi dell'ordine e della spedizione
verifica la presenza di una chiave di idempotenza esistente
invia la richiesta di tracciamento documentata dal server
salva la risposta del fornitore e il record interno della spedizione
accoda un aggiornamento o elabora l'evento supportato
pubblica solo i campi approvati nel negozioUtilizza timeout brevi, nuovi tentativi limitati e un backoff esponenziale per gli errori temporanei. Non ripetere ogni errore. Un errore di autenticazione, una richiesta non valida o un corriere non supportato richiedono generalmente una correzione anziché chiamate ripetute. Registra un ID di correlazione, l'esito della richiesta e la categoria dell'errore del fornitore, ma evita di scrivere nei log dell'applicazione le chiavi API, gli indirizzi completi dei clienti o informazioni personali non necessarie.
Mantieni separata la risposta del fornitore dal modello rivolto al cliente. In questo modo è più facile cambiare fornitore, correggere una regola di associazione e limitare le informazioni esposte tramite una pagina pubblica dell'ordine.
Progetta l'esperienza di tracciamento per il cliente
Una pagina di tracciamento dovrebbe rispondere rapidamente a tre domande: qual è lo stato attuale, cosa è successo più recentemente e cosa dovrebbe fare il cliente dopo? Mostra il riferimento dell'ordine, il numero della spedizione in una forma rispettosa della privacy, il nome del corriere, l'ora dell'ultimo evento e una spiegazione chiara delle eccezioni.
Non mostrare una cronologia vuota come se fosse un errore tecnico. Prima della prima scansione del corriere, spiega che le informazioni sulla spedizione sono state ricevute e che il movimento potrebbe non essere ancora visibile. In caso di eccezione, fornisci una spiegazione in linguaggio semplice solo quando i dati di origine la supportano. Se il corriere segnala un problema con l'indirizzo, collega il processo di assistenza o l'azione del servizio clienti che la tua azienda può effettivamente fornire.
Per i negozi basati su Shopify o su un'altra piattaforma e-commerce, verifica come la piattaforma espone gli eventi di evasione, gli account dei clienti, le pagine dello stato dell'ordine e i modelli di notifica. La documentazione ufficiale per sviluppatori di Shopify include risorse per i webhook e i dati di evasione. Le API della piattaforma e la documentazione versionata possono cambiare, quindi conferma la versione utilizzata dalla tua applicazione prima del lavoro in produzione.
Utilizza le notifiche con attenzione
Gli eventi della spedizione sono trigger utili, ma inviare un messaggio per ogni scansione del corriere può creare affaticamento da notifiche. Definisci regole aziendali come l'invio di notifiche alla creazione della spedizione, in caso di avanzamento significativo durante il transito, quando la spedizione è in consegna, alla consegna e per determinate eccezioni. Sopprimi i duplicati e aggiungi un intervallo minimo per i messaggi ripetuti sui ritardi.
Separa gli avvisi operativi dalle notifiche per i clienti. Un team di assistenza potrebbe dover sapere che una spedizione non cambia da diversi giorni, mentre un cliente potrebbe aver bisogno di un messaggio solo quando il corriere segnala un'eccezione concreta. La soglia temporale dovrebbe riflettere il livello di servizio, la destinazione, il corriere e il metodo di spedizione, anziché un numero universale privo di una base operativa.
Testa con scenari di consegna reali
Una risposta corretta per un solo numero di tracciamento non è sufficiente per il lancio in produzione. Crea una matrice di test che includa più corrieri, paesi, tipi di spedizione e stati degli eventi. Testa almeno:
- Una spedizione appena creata senza scansione del corriere
- Una normale spedizione in transito
- Una spedizione in consegna
- Una spedizione consegnata
- Un'eccezione o un evento relativo all'indirizzo
- Una spedizione restituita
- Un numero di tracciamento non valido
- Un evento di evasione duplicato
- Una risposta ritardata del fornitore o un timeout
- Un evento fuori ordine
Misura più della semplice disponibilità dell'API. Verifica che venga aggiornato l'ordine corretto, che il cliente visualizzi un linguaggio comprensibile, che le notifiche duplicate vengano soppresse e che il personale dell'assistenza possa identificare l'evento originale del corriere. Esegui prima un rilascio limitato, mantieni un fallback operativo e monitora le categorie di errore dopo il rilascio.
Sicurezza, privacy e manutenzione
Memorizza le credenziali in un secrets manager o in una variabile d'ambiente protetta, non nel codice del tema, nel codice mobile, nel controllo del codice sorgente o nelle richieste del browser. Limita l'accesso ai dati delle spedizioni in base al ruolo, utilizza HTTPS e verifica per quanto tempo vengono conservate le risposte grezze e i campi relativi ai clienti.
Esamina regolarmente la documentazione del fornitore e la versione dell'API della tua piattaforma e-commerce. Il supporto dei corrieri, i nomi degli eventi, i requisiti di autenticazione e il comportamento dei webhook della piattaforma possono cambiare. Mantieni configurabili le regole di associazione degli stati, documenta le ipotesi alla loro base e consenti di riprodurre o riconciliare una spedizione senza inviare un altro messaggio al cliente.
L'API di 17TRACK è un'opzione rilevante da valutare quando il tuo negozio necessita di un'integrazione di tracciamento dedicata tra più corrieri. La scelta appropriata dipende comunque dai corrieri utilizzati, dai paesi serviti, dal comportamento degli aggiornamenti documentato per il tuo account, dal volume di richieste previsto e dai controlli operativi richiesti dal tuo team. Conferma questi punti nella documentazione ufficiale e in una proof of concept controllata prima di impegnarti in un design di produzione.
FAQ
Il tracciamento dovrebbe essere creato quando viene effettuato un ordine?
Di solito no. Crea o attiva il record della spedizione quando il flusso di evasione dispone di un corriere e di un numero di tracciamento. Crearlo al checkout può generare record per ordini che vengono annullati, non evasi o suddivisi in seguito.
Un'API di tracciamento può garantire informazioni sulla consegna in tempo reale?
No. Nessuna API può garantire che ogni scansione del corriere sia visibile immediatamente. Il fornitore dipende dai dati del corriere e i sistemi dei corrieri possono segnalare gli eventi con ritardi o lacune. Presenta accuratamente timestamp e linguaggio dello stato ed evita di promettere un tempo di aggiornamento esatto, a meno che la documentazione pertinente e l'accordo sul servizio non supportino tale promessa.
Il browser dovrebbe chiamare direttamente l'API di tracciamento?
Nella maggior parte delle implementazioni, no. Utilizza un'integrazione lato server in modo che le credenziali rimangano protette, le risposte possano essere normalizzate, i nuovi tentativi possano essere controllati e i dati rivolti al cliente possano essere filtrati. Il negozio dovrebbe normalmente leggere una vista approvata della spedizione dalla tua applicazione.
Come dovrebbe gestire un negozio più pacchi nello stesso ordine?
Modella ogni evasione o pacco come una spedizione separata mantenendo l'ID dell'ordine principale. La pagina dell'ordine può mostrare un riepilogo generale e cronologie separate per ogni pacco. In questo modo si evita di nascondere un pacco in ritardo dietro lo stato di consegna di un altro pacco.
Qual è la prima metrica di produzione da monitorare?
Monitora l'intero flusso, dalla creazione dell'evasione a un aggiornamento corretto e visibile al cliente. Il solo successo dell'API non è sufficiente. Tieni traccia dei record duplicati, delle spedizioni obsolete, degli eventi non associati, dei fallimenti delle notifiche e della percentuale di spedizioni che richiedono una correzione manuale.
