Come utilizzare l'API di tracciamento UPS: guida alla configurazione passo dopo passo

Per utilizzare l'API di monitoraggio UPS, crea un account UPS Developer, registra un'applicazione, ottieni le credenziali OAuth 2.0, richiedi un token di accesso e invia richieste di monitoraggio autenticate con un numero di tracking UPS valido. Le etichette esatte del portale, le fasi di approvazione e i requisiti dell'API possono cambiare; pertanto, verifica le istruzioni aggiornate nel portale ufficiale UPS Developer prima di attivare un'integrazione in produzione.

Questa guida è destinata agli sviluppatori e ai team operativi di ecommerce che devono visualizzare lo stato delle spedizioni all'interno di un negozio online, di un sistema di gestione degli ordini, di un flusso di lavoro di magazzino, di uno strumento per il servizio clienti o di una dashboard interna. Si concentra sulla sequenza di integrazione, sulle decisioni che influiscono sull'affidabilità e sui controlli che prevengono i comuni errori di monitoraggio.

Cosa fa l'API di monitoraggio UPS

Un'integrazione API consente al software di richiedere informazioni sulla spedizione a UPS, invece di richiedere a un dipendente o a un cliente di aprire manualmente la pagina di tracking del corriere. La tua applicazione può utilizzare la risposta per visualizzare l'ultimo stato noto, identificare gli eventi di consegna, supportare le verifiche del servizio clienti o attivare un flusso di lavoro interno.

L'API non è uguale a una pagina di tracking. Una pagina di tracking è progettata per essere letta da una persona. Una risposta API è costituita da dati strutturati che il software deve analizzare, memorizzare e presentare. Il tuo sistema rimane responsabile dell'autenticazione, della gestione degli errori, del polling o della raccolta degli eventi, della conservazione dei dati, della progettazione dell'interfaccia utente e delle eventuali regole aziendali basate sugli eventi di consegna.

Prima di iniziare

Prepara i seguenti elementi prima di aprire il portale per sviluppatori:

• Un account UPS Developer o il tipo di account richiesto dall'attuale processo di onboarding UPS.
• Un'applicazione registrata e le credenziali rilasciate per tale applicazione.
• Un numero di tracking di test o un altro metodo di test approvato. Non iniziare con dati reali dei clienti se la documentazione UPS prevede un ambiente o una procedura di test separati.
• Una decisione chiara su quale sistema gestisce i record delle spedizioni, gli eventi di tracking e i messaggi di stato rivolti ai clienti.
• Un luogo sicuro in cui conservare le credenziali client e i token di accesso. Non inserire mai segreti nel codice del browser, in repository pubblici, screenshot o applicazioni mobili che gli utenti possano ispezionare.

Dovresti inoltre decidere se la tua applicazione necessita solo del tracking o di un'integrazione UPS più ampia. Tracking, quotazione, spedizione, convalida degli indirizzi e servizi documentali possono avere prodotti, autorizzazioni, formati delle richieste e requisiti operativi diversi.

Passaggio 1: apri il portale UPS Developer

Inizia dal portale ufficiale UPS Developer. Esamina il catalogo API aggiornato, le indicazioni sull'autenticazione, i requisiti di onboarding, i termini e le informazioni sugli ambienti. Cerca in modo specifico la documentazione dell'API di monitoraggio invece di presumere che le istruzioni relative a un altro servizio UPS siano applicabili anche al tracking.

Il portale è la fonte appropriata per i campi delle richieste aggiornati, gli ambiti di autorizzazione, le definizioni delle risposte, i limiti di frequenza, i codici di errore e i dettagli degli ambienti. Questi dettagli possono cambiare e un esempio di codice di terze parti potrebbe utilizzare un'interfaccia UPS precedente o un metodo di autenticazione obsoleto.

Passaggio 2: registra un'applicazione

Crea un'applicazione nel portale per sviluppatori e seleziona le API UPS di cui l'applicazione ha effettivamente bisogno. Per un progetto dedicato esclusivamente al tracking, richiedi solo la funzionalità di monitoraggio, a meno che il tuo flusso di lavoro non richieda servizi aggiuntivi. Limitare le autorizzazioni riduce la complessità della configurazione e semplifica la risoluzione dei problemi in seguito.

Registra l'identificativo e il segreto dell'applicazione in un gestore di segreti lato server o in un sistema protetto di variabili d'ambiente. Tratta il segreto come una password. Se viene esposto, sostituiscilo tramite la procedura fornita da UPS e controlla i log per individuare eventuali utilizzi non autorizzati.

Se il portale richiede informazioni sull'account, sulla fatturazione, sull'azienda o sull'applicazione, fornisci dati accurati. Evita di inventare un caso d'uso di produzione o di utilizzare le informazioni dell'account di qualcun altro solo per completare un test. L'accesso a un servizio può dipendere dalla configurazione dell'account e dall'attuale processo di approvazione UPS.

Passaggio 3: implementa l'autenticazione OAuth 2.0

La documentazione attuale per sviluppatori UPS utilizza l'autenticazione basata su OAuth per le proprie API. Normalmente il server scambia le credenziali dell'applicazione tramite il flusso di token documentato e riceve un token di accesso. In seguito include tale token nell'intestazione di autorizzazione di una richiesta API.

Mantieni separata l'autenticazione dalla logica di tracking. Una progettazione pratica prevede un componente che ottiene e memorizza nella cache un token valido e un altro che chiama l'endpoint di monitoraggio. Il componente del token dovrebbe:

• Inviare le credenziali solo all'endpoint di autorizzazione UPS documentato.
• Utilizzare il tipo di contenuto e i parametri grant specificati nella documentazione UPS aggiornata.
• Memorizzare temporaneamente il token e riutilizzarlo fino alla scadenza, invece di richiedere un nuovo token per ogni numero di tracking.
• Aggiornare o riottenere il token quando si verifica la condizione di scadenza documentata.
• Oscurare credenziali e token nei log dell'applicazione, nei report degli errori e nei ticket di assistenza.

Non copiare un token da una sessione del browser in un'integrazione permanente. Un servizio backend è generalmente un luogo più sicuro per gestire le credenziali, poiché mantiene i segreti lontani dal codice client pubblico.

Passaggio 4: crea la richiesta di tracking

Utilizza il formato della richiesta indicato nel riferimento ufficiale dell'API di monitoraggio. Una richiesta tipica include un numero di tracking nel percorso o nei parametri della richiesta, un token di accesso nell'intestazione di autorizzazione e le intestazioni richieste dall'API UPS. Non presumere che il numero di tracking sia l'unico valore richiesto: il riferimento aggiornato potrebbe specificare intestazioni per versione, transazione, content-type o correlazione.

Un modello semplificato della richiesta è il seguente:

GET [UPS tracking endpoint]/[tracking-number]
Authorization: Bearer [access-token]
Accept: application/json

Questo è un esempio strutturale, non un endpoint da copiare e incollare. Utilizza l'endpoint, la versione, le intestazioni e i nomi dei parametri pubblicati nella documentazione UPS per la tua applicazione. Mantieni il numero di tracking normalizzato secondo le regole dei tuoi dati degli ordini, ma non rimuovere caratteri a meno che la documentazione del corriere non confermi che sia sicuro farlo.

Passaggio 5: inserisci gli eventi nel tuo modello dati

Le risposte dei corrieri contengono spesso più informazioni di una singola etichetta di stato. Prima di programmare la pagina rivolta ai clienti, associa la risposta a un modello interno che includa, ad esempio, identificativo della spedizione, corriere, ultimo stato, codice evento, descrizione dell'evento, data e ora dell'evento, località, informazioni sulla consegna stimata e data e ora della consegna, quando disponibili.

Conserva la risposta originale del corriere quando le tue policy di conservazione e privacy lo consentono. Una risposta grezza può aiutare a diagnosticare un errore di mappatura o a spiegare perché il tuo stato normalizzato differisce dalla formulazione del corriere. Allo stesso tempo, evita di mostrare ai clienti codici tecnici degli eventi senza una spiegazione comprensibile.

Non considerare ogni stato come un esito finale della consegna. Ad esempio, un evento di transito, un'eccezione, un tentativo di consegna e un evento di consegna completata non dovrebbero essere ridotti allo stesso messaggio per il cliente. Crea mappature esplicite e definisci cosa accade quando UPS aggiunge un valore di evento che il tuo codice non riconosce.

Passaggio 6: aggiungi retry, convalida e monitoraggio

Un'integrazione di produzione richiede più di una richiesta riuscita in una console di sviluppo. Aggiungi convalide e misure di sicurezza operative:

• Convalida degli input: rifiuta i numeri di tracking vuoti, malformati o palesemente incompleti prima di inviare le richieste.
• Timeout: impedisci che una risposta lenta del corriere blocchi un intero flusso di checkout, assistenza o magazzino.
• Regole di retry: riprova con cautela in caso di errori temporanei di rete o del servizio, utilizzando un backoff. Non ripetere continuamente i tentativi in caso di errori di autenticazione o numeri di tracking non validi.
• Rispetto dei limiti: segui i limiti e le regole d'uso indicati nella documentazione UPS. Memorizza nella cache i risultati recenti quando il processo aziendale lo consente.
• Stati sconosciuti: conserva per la revisione un evento non riconosciuto invece di etichettarlo erroneamente come consegnato o smarrito.
• Osservabilità: registra i tempi delle richieste, la categoria della risposta e le informazioni di correlazione senza salvare segreti o dati personali non necessari.

Un sistema di tracking dovrebbe inoltre definire con quale frequenza aggiornare una spedizione. Un polling eccessivamente frequente può creare un carico evitabile e potrebbe non produrre nuove informazioni. Un polling troppo raro può far apparire obsoleta una pagina rivolta ai clienti. Scegli un intervallo in base al volume delle spedizioni, all'urgenza operativa, alle regole del corriere e al livello di aggiornamento di cui gli utenti hanno realmente bisogno.

Passaggio 7: esegui test con scenari realistici

Testa più di una spedizione consegnata correttamente. Includi un numero di tracking sconosciuto, una spedizione in transito, un'eccezione, una spedizione con più eventi, un token scaduto, un timeout, un errore di autorizzazione e una risposta contenente campi imprevisti per il parser. Se UPS offre un ambiente o credenziali di test separati, segui prima quella procedura.

Controlla l'intero percorso dalla richiesta all'interfaccia utente. Verifica che l'ordine corretto riceva la spedizione corretta, che le date e gli orari siano visualizzati nel fuso orario previsto, che gli eventi duplicati non creino messaggi duplicati per i clienti e che un'interruzione del servizio del corriere non sovrascriva uno stato precedentemente valido con un testo fuorviante.

Quando è più adatta un'API di tracking multi-corriere

Un'integrazione diretta con UPS può essere appropriata quando la tua attività spedisce principalmente con UPS e richiede un controllo approfondito sul flusso di lavoro del corriere. Diventa meno conveniente quando gli ordini possono passare attraverso diversi corrieri, marketplace, operatori postali o aziende di consegna regionali. In questo caso, credenziali, formati delle risposte, vocabolari degli stati e regole di retry separati possono aumentare il lavoro di manutenzione.

Un servizio multi-corriere come 17TRACK Tracking API può offrire un modello di integrazione alternativo per le applicazioni che necessitano del tracking su più corrieri. La relativa documentazione per sviluppatori deve essere consultata direttamente per verificare i corrieri supportati, i formati delle richieste, l'autenticazione, i termini d'uso e le funzionalità disponibili. Questo non significa che sia automaticamente migliore di una connessione diretta a UPS: la scelta corretta dipende dal mix di corrieri, dai requisiti dei dati, dal controllo sull'integrazione e dai vincoli commerciali o di conformità.

Per una ricerca rivolta ai consumatori, anziché per un'integrazione per sviluppatori, la pagina di tracking di 17TRACK potrebbe essere più adatta rispetto alla creazione di una connessione API. Per un negozio online che necessita di aggiornamenti post-acquisto con il proprio brand, esamina separatamente l'integrazione della piattaforma pertinente invece di aggiungere lavoro API non necessario per il negozio.

Errori comuni di implementazione

• Utilizzare esempi obsoleti: un esempio di codice potrebbe fare riferimento a una versione ritirata, a un vecchio metodo di autenticazione o a un servizio UPS diverso.
• Inserire i segreti nel codice frontend: tutto ciò che viene inviato a un browser deve essere considerato ispezionabile.
• Presumere che un risultato vuoto significhi nessuna spedizione: verifica il numero di tracking, le autorizzazioni dell'account, l'ambiente e il messaggio della risposta prima di trarre una conclusione aziendale.
• Mappare solo il testo: le descrizioni degli stati possono variare. Utilizza i codici documentati e conserva i valori sconosciuti per la revisione.
• Ignorare i requisiti dell'account e di utilizzo: il codice tecnico può essere corretto mentre l'applicazione non è configurata per il servizio richiesto.
• Aggiornare senza una regola aziendale: un polling non necessario può aumentare costi, carico e rumore operativo senza migliorare l'esperienza del cliente.

Checklist pratica per il go-live

1. Conferma che l'applicazione utilizzi la documentazione UPS aggiornata e l'ambiente approvato.
2. Verifica che le credenziali siano memorizzate lato server e possano essere sostituite.
3. Testa errori di autenticazione, errori del corriere, input malformati e timeout.
4. Confronta gli stati normalizzati con la risposta originale per spedizioni rappresentative.
5. Imposta una policy di aggiornamento e monitora il volume delle richieste.
6. Definisci la responsabilità per eventi non identificati, aggiornamenti ritardati ed escalation dei clienti.
7. Documenta l'integrazione in modo che un altro sviluppatore possa aggiornare in sicurezza credenziali, versioni degli endpoint e mappature degli stati.

FAQ

Ho bisogno di un account UPS per utilizzare l'API di monitoraggio?

Dovresti verificare gli attuali requisiti di onboarding e accesso UPS nel portale Developer. L'accesso all'API può dipendere dalla registrazione dell'applicazione, dalle credenziali, dalla configurazione dell'account e dal servizio specifico richiesto. Non presumere che un accesso alla pagina pubblica di tracking sia intercambiabile con l'accesso all'API per sviluppatori.

L'API di monitoraggio UPS è gratuita?

Non presumere che l'accesso all'API non comporti condizioni commerciali o di utilizzo. UPS pubblica le informazioni aggiornate sui servizi e sugli account attraverso i propri canali ufficiali e alcuni requisiti possono dipendere dal prodotto, dall'account o dall'accordo. Conferma direttamente i termini applicabili prima di pianificare un budget di produzione.

Posso chiamare direttamente l'API UPS da JavaScript in un browser?

Una chiamata basata sul browser può esporre le credenziali dell'applicazione e creare problemi di cross-origin, sicurezza e controllo dell'utilizzo. Un'integrazione lato server è generalmente il modello più sicuro per conservare i segreti, ottenere token, applicare regole di retry e limitare l'accesso ai dati delle spedizioni.

Con quale frequenza la mia applicazione dovrebbe richiedere gli aggiornamenti del tracking?

Utilizza una policy di aggiornamento basata sui limiti documentati dal corriere, sul volume delle spedizioni, sull'urgenza operativa e sul livello di aggiornamento richiesto dagli utenti. Memorizza nella cache i risultati recenti quando appropriato, utilizza il backoff dopo errori temporanei ed evita di considerare il polling ripetuto un sostituto di una funzionalità documentata per eventi o notifiche.

Dovrei utilizzare un'integrazione diretta con UPS o un'API multi-corriere?

Un'integrazione diretta con UPS può essere adatta a un flusso di lavoro incentrato su UPS che richiede un controllo specifico sul corriere. Un'API multi-corriere può ridurre il numero di integrazioni quando le spedizioni utilizzano diversi corrieri. Confronta corrieri supportati, autenticazione, campi dei dati, requisiti di affidabilità, termini d'uso e impegno di implementazione prima di scegliere.

Fonti

• UPS Developer Portal — catalogo API ufficiale, accesso alle applicazioni, autenticazione e documentazione per sviluppatori.
• UPS Technology Integration — informazioni ufficiali sull'integrazione della tecnologia UPS con i sistemi aziendali.
• 17TRACK Tracking API — punto di accesso ufficiale al prodotto e agli strumenti per sviluppatori per il tracking multi-corriere.
• 17TRACK API Documentation — documentazione API ufficiale per autenticazione, richieste e gestione delle risposte.