Fedex Tracking Api: Come tracciare i pacchi passo dopo passo
Per tracciare i pacchi FedEx tramite un'applicazione, crea un account FedEx Developer, ottieni le credenziali API, richiedi un token di accesso OAuth, invia una richiesta di tracciamento e integra la risposta nel flusso di lavoro degli ordini o delle spedizioni. La FedEx Tracking API è destinata ai sistemi software che necessitano dei dati sullo stato delle spedizioni, mentre il sito web FedEx è generalmente più rapido per controllare manualmente un singolo pacco.
Questa guida spiega la sequenza di integrazione, le informazioni da convalidare, gli errori comuni di implementazione e un'alternativa per le aziende che necessitano del tracciamento multi-vettore anziché della connettività esclusiva con FedEx. I campi esatti delle richieste, le regole di autenticazione, gli ambienti e la disponibilità dei servizi devono essere sempre verificati nella documentazione FedEx attuale prima della distribuzione in produzione.
Scegli innanzitutto il metodo di tracciamento corretto
Il metodo migliore dipende da chi deve agire e dal numero di spedizioni da monitorare.
- Ricerca occasionale: usa la pagina di tracciamento FedEx quando un cliente o un addetto all'assistenza deve controllare una sola spedizione.
- Applicazione interna: usa la FedEx Tracking API quando un sistema di gestione degli ordini, un'applicazione di magazzino, un portale clienti o uno strumento di assistenza necessita di dati sullo stato ottenuti programmaticamente.
- Operatività multi-vettore: valuta una piattaforma di tracciamento quando l'azienda riceve spedizioni da FedEx e da altri vettori e desidera un'unica integrazione normalizzata, un unico modello di stato o un'unica esperienza di tracciamento per i clienti.
Un'integrazione API esclusiva con FedEx può offrire un controllo diretto ed essere adatta a un sistema basato sulle spedizioni FedEx. Ciò significa anche che il tuo team dovrà gestire autonomamente l'autenticazione, i limiti delle richieste, le modifiche alle risposte, la logica degli stati specifica del vettore, la gestione degli errori e qualsiasi ulteriore integrazione con altri vettori.
Cosa serve prima di utilizzare la FedEx Tracking API
Prepara i seguenti elementi prima di scrivere l'integrazione:
- Un account FedEx Developer e l'accesso al portale per sviluppatori FedEx.
- Le credenziali API richieste per l'ambiente FedEx selezionato. La documentazione FedEx può fare riferimento a credenziali quali client ID e client secret.
- Un rapporto con un account FedEx o altre informazioni sull'account, se l'operazione API selezionata lo richiede.
- Una posizione sicura lato server per le credenziali. Non esporre il client secret in JavaScript del browser, in un'applicazione mobile o in un repository pubblico.
- Almeno un identificativo di spedizione valido per i test, ad esempio un numero di tracciamento FedEx. I dati di test devono rappresentare i tipi di spedizione e i servizi che l'applicazione elaborerà.
- Un piano per memorizzare l'ultimo stato noto, il timestamp dell'evento, le informazioni sulla posizione e l'ora dell'ultimo controllo completato correttamente.
FedEx separa l'accesso degli sviluppatori, l'autenticazione, gli ambienti API e i requisiti operativi. Un accesso riuscito al portale per sviluppatori non dimostra di per sé che una richiesta di produzione sia pronta. Verifica nella documentazione attuale del prodotto i prerequisiti dell'account, i requisiti di approvazione, gli URL degli ambienti ed eventuali limitazioni d'uso.
Passaggio 1: crea un'applicazione nel portale per sviluppatori FedEx
Inizia dal portale ufficiale FedEx Developer e individua il prodotto Track API. Crea o seleziona un'applicazione, quindi registra le credenziali fornite per l'ambiente che intendi utilizzare. Mantieni separate le credenziali di sviluppo e di produzione.
In questa fase, conferma quattro dettagli:
- Quale prodotto API contiene l'operazione di tracciamento necessaria.
- Quale URL di base appartiene all'ambiente di test o di produzione.
- Quale metodo di autenticazione e quali ambiti, se presenti, sono richiesti.
- Se la richiesta necessita del numero di account FedEx o di un altro campo a livello di account.
Non copiare un URL o il nome di un campo da un vecchio esempio di codice senza verificare la documentazione attuale. Le API dei vettori possono modificare le versioni degli endpoint, gli header obbligatori, le strutture delle risposte o le regole di onboarding.
Passaggio 2: richiedi un token di accesso OAuth
L'autenticazione delle API FedEx utilizza comunemente le credenziali client OAuth 2.0. La tua applicazione invia le credenziali client all'endpoint di autorizzazione FedEx e riceve un token di accesso di breve durata. L'applicazione invia quindi tale token nell'header Authorization della richiesta di tracciamento.
Un esempio semplificato da riga di comando è il seguente:
curl -X POST "<FEDEX_OAUTH_URL>" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=client_credentials" \
-d "client_id=<CLIENT_ID>" \
-d "client_secret=<CLIENT_SECRET>"Consideralo un modello di implementazione, non un sostituto della documentazione di autenticazione FedEx attuale. Il codice di produzione dovrebbe leggere il valore di scadenza del token, memorizzarlo nella cache in modo sicuro e richiederne uno nuovo alla scadenza o quando l'API restituisce un errore di autenticazione. Evita di richiedere un nuovo token per ogni numero di tracciamento, a meno che i limiti ufficiali e il tuo modello di traffico non lo rendano necessario.
Le misure di sicurezza utili per l'autenticazione includono:
- Memorizzare i segreti in un gestore di segreti lato server o in variabili d'ambiente protette.
- Non scrivere mai token di accesso o client secret nei log dell'applicazione.
- Utilizzare credenziali separate per lo sviluppo e la produzione, quando la piattaforma supporta tale separazione.
- Restituire un errore controllato all'utente quando l'autenticazione non riesce; non esporre la risposta grezza del vettore.
- Monitorare separatamente gli errori dei token e gli errori relativi ai numeri di tracciamento non validi.
Passaggio 3: crea la richiesta di tracciamento
Dopo aver ottenuto un token valido, costruisci la richiesta descritta nella documentazione attuale della FedEx Track API. La richiesta generalmente identifica uno o più record di spedizione e può includere opzioni che influiscono sul livello di dettaglio restituito. I nomi esatti delle proprietà JSON e i campi obbligatori devono provenire dalla versione dell'endpoint FedEx che stai utilizzando.
Un modello rappresentativo di richiesta può essere simile al seguente:
curl -X POST "<FEDEX_TRACK_BASE_URL>/track/v1/trackingnumbers" \
-H "Authorization: Bearer <ACCESS_TOKEN>" \
-H "Content-Type: application/json" \
-d '{
"trackingInfo": [
{
"trackingNumberInfo": {
"trackingNumber": "<FEDEX_TRACKING_NUMBER>"
}
}
],
"includeDetailedScans": true
}'Il percorso dell'endpoint e i nomi dei campi indicati sopra devono essere verificati nella documentazione FedEx attiva prima dell'uso. Alcune integrazioni potrebbero richiedere una struttura della richiesta diversa, un numero di account, una ricerca basata su un riferimento o un'opzione differente per le scansioni dettagliate. Non presumere che un numero di tracciamento appartenente a un altro vettore possa essere inviato a un endpoint esclusivo di FedEx.
Passaggio 4: analizza la risposta nei campi aziendali
Non trasferire la risposta completa del vettore direttamente a una pagina rivolta ai clienti. Innanzitutto, mappala in un modello interno stabile. Un record pratico della spedizione può includere:
- Vettore: FedEx.
- Identificativo di tracciamento: l'identificativo inviato all'API.
- Stato attuale: il tuo stato normalizzato, ad esempio etichetta creata, in transito, in consegna, consegnata, eccezione o sconosciuto.
- Stato del vettore: lo stato o il codice FedEx originale, conservato per l'assistenza e il debug.
- Ultimo evento: la descrizione e il timestamp dell'evento più recente restituiti da FedEx.
- Consegna stimata: memorizzala solo quando la risposta la fornisce e visualizzala come stima, non come garanzia.
- Conferma della consegna: usa la risposta del vettore per determinare se la consegna è stata segnalata.
- Ora dell'ultimo controllo: il timestamp registrato dal tuo sistema, diverso dall'ora dell'evento indicata da FedEx.
La normalizzazione degli stati richiede valutazioni editoriali e operative. Ad esempio, un'eccezione non dovrebbe essere visualizzata automaticamente come una consegna fallita e un evento di creazione dell'etichetta non significa necessariamente che il pacco si stia muovendo attraverso la rete. Conserva l'evento originale del vettore insieme allo stato normalizzato, in modo che il personale di assistenza possa analizzare le differenze.
Passaggio 5: gestisci gli errori e le informazioni incomplete
Un'integrazione di tracciamento in produzione deve distinguere tra diversi tipi di errore. Una richiesta malformata, un token scaduto, un numero di tracciamento non valido, un'interruzione temporanea del vettore e una risposta riuscita senza eventi utili non rappresentano la stessa condizione.
| Situazione | Gestione consigliata |
|---|---|
| Errore di autenticazione | Aggiorna le credenziali o la gestione del token, quindi avvisa il responsabile dell'integrazione se il problema continua. |
| Richiesta non valida | Convalida il payload, gli header obbligatori, il formato dell'identificativo e l'ambiente prima di riprovare. |
| Numero di tracciamento non trovato | Mostra uno stato non risolto o non disponibile; non dire al cliente che il pacco è perso senza ulteriori prove. |
| Timeout temporaneo o errore del server | Usa tentativi limitati con backoff e conserva l'ultimo stato noto. |
| Nessuna scansione recente | Visualizza l'ultimo evento confermato e la sua età invece di inventare una posizione attuale. |
La logica dei tentativi deve essere prudente. Le richieste ripetute possono aumentare il carico, generare avvisi superflui o entrare in conflitto con i limiti dell'API. Applica timeout, backoff esponenziale, elaborazione idempotente e monitoraggio dei guasti ripetuti. I limiti esatti di frequenza e gli impegni di servizio devono essere ricavati dal tuo accordo FedEx o dalla documentazione attuale, non presunti sulla base di un'applicazione di esempio.
Passaggio 6: pianifica gli aggiornamenti senza creare una cattiva esperienza per il cliente
La maggior parte dei sistemi di spedizione non deve richiedere un nuovo risultato ogni pochi secondi. Usa una strategia di aggiornamento basata sullo stato della spedizione. Una nuova spedizione può richiedere controlli più frequenti dopo la creazione dell'etichetta, mentre una spedizione consegnata dovrebbe normalmente interrompere il polling. Un'eccezione può richiedere un flusso di assistenza separato anziché un polling automatico più frequente.
Quando presenti i risultati ai clienti, includi l'ora dell'ultimo evento del vettore e chiarisci se la data di consegna è stimata. Se l'API è temporaneamente non disponibile, mantieni l'ultimo risultato verificato e spiega che lo stato non è stato aggiornato. Questo è più utile che sostituire uno stato noto con un errore generico.
Passaggio 7: testa il flusso di lavoro completo
Testa più di una risposta riuscita. Un piano di test realistico dovrebbe includere:
- Un numero di tracciamento valido con più eventi di scansione.
- Una spedizione appena creata con uno storico di tracciamento limitato.
- Una spedizione consegnata.
- Una spedizione con eccezione o in ritardo, se sono disponibili dati di test rappresentativi.
- Un numero di tracciamento non valido o incompleto.
- Una credenziale scaduta o revocata.
- Un timeout, una risposta per superamento del limite di frequenza e un errore temporaneo del server.
- Eventi duplicati ed eventi ricevuti fuori ordine.
- Fusi orari diversi e transizioni all'ora legale.
- Rimozione dai log delle credenziali, dei token, dei dati personali e dei payload completi del vettore.
Prima di entrare in produzione, confronta lo stato normalizzato con la pagina di tracciamento FedEx per un campione controllato. Le due visualizzazioni potrebbero non aggiornarsi esattamente nello stesso momento; l'obiettivo è confermare che il parser interpreti correttamente la risposta e non trasformi dati mancanti in un'affermazione definitiva.
Quando una Tracking API multi-vettore è più adatta
Un'integrazione diretta con FedEx è sensata quando FedEx è il vettore principale e il tuo team vuole possedere tutta la logica dell'applicazione. È meno efficiente quando gli ordini possono passare attraverso diversi vettori, marketplace, operatori postali o servizi di consegna regionali. In questa situazione, l'azienda potrebbe aver bisogno del rilevamento del vettore, di un modello di stato comune, dell'orchestrazione tramite webhook o polling, di pagine di tracciamento brandizzate e di un'unica visualizzazione per l'assistenza.
17TRACK offre una Tracking API separata e pubblica la documentazione per sviluppatori all'indirizzo api.17track.net. Può essere valutata come opzione multi-vettore quando il requisito è più ampio del solo tracciamento FedEx. La scelta corretta dipende dai vettori, dai Paesi, dal livello di dettaglio degli eventi, dal modello di integrazione, dai termini commerciali e dai controlli operativi che il progetto può verificare durante i test. Un servizio multi-vettore non elimina la necessità di testare le eccezioni specifiche dei vettori o di convalidare l'accuratezza e la tempistica degli eventi per il proprio mix di spedizioni.
Checklist pratica di implementazione
- Conferma che il prodotto API FedEx corrisponda al tipo di ricerca necessario.
- Verifica l'endpoint di autenticazione, l'URL di base, lo schema della richiesta e gli header obbligatori attuali.
- Mantieni client secret e token di accesso sul server.
- Memorizza nella cache e aggiorna i token OAuth in modo sicuro.
- Convalida gli identificativi di tracciamento prima di inviare le richieste.
- Conserva sia lo stato originale del vettore sia il tuo stato normalizzato.
- Registra separatamente l'ora dell'evento del vettore e l'ora di recupero del sistema.
- Usa tentativi limitati e monitora separatamente gli errori di autenticazione, convalida, timeout e quelli del vettore.
- Interrompi il polling ordinario dopo uno stato finale, in base alle tue regole operative.
- Testa le variazioni reali delle risposte prima di mostrare i messaggi sullo stato ai clienti.
- Ricontrolla la documentazione FedEx quando cambi versione dell'API o ampli i tipi di spedizione.
Domande frequenti
Posso usare il sito web FedEx invece dell'API?
Sì. Il sito web FedEx è generalmente l'opzione più semplice per una ricerca manuale. Un'API diventa utile quando il software deve recuperare automaticamente i dati di tracciamento, collegare gli eventi di stato agli ordini o presentare le informazioni di tracciamento all'interno di un'altra applicazione.
Ho bisogno di un token OAuth per ogni richiesta di tracciamento?
In genere, l'applicazione ottiene un token di accesso e lo invia con le richieste API successive fino alla sua scadenza. Memorizza il token nella cache in modo sicuro e segui la documentazione di autenticazione FedEx attuale per il comportamento relativo a scadenza e rinnovo. Non esporre il token a un browser o a un cliente.
L'API può dirmi esattamente dove si trova un pacco?
Può restituire gli eventi di tracciamento e le altre informazioni fornite da FedEx per la spedizione. Il risultato può mostrare una posizione di scansione o una struttura, ma non deve essere interpretato come un posizionamento GPS continuo in tempo reale. Visualizza solo la posizione e i dettagli dell'evento effettivamente restituiti.
Perché a volte un numero di tracciamento non presenta aggiornamenti?
Una spedizione potrebbe essere stata creata senza una scansione recente, l'identificativo potrebbe essere errato, l'evento potrebbe non essere ancora disponibile nella risposta oppure il servizio del vettore potrebbe essere temporaneamente non disponibile. Mantieni l'ultimo risultato confermato, mostra quando è stato controllato e analizza gli errori ripetuti invece di dichiarare che la spedizione è persa.
Un'azienda di ecommerce dovrebbe creare API separate per ogni vettore?
Può essere ragionevole per un'operatività concentrata su FedEx e dotata di solide risorse tecniche. Un'azienda che spedisce tramite diversi vettori potrebbe preferire un livello di tracciamento multi-vettore per ridurre il lavoro di integrazione e normalizzare gli eventi. Prima di scegliere, confronta la copertura dei vettori, il livello di dettaglio dei dati, l'affidabilità, la documentazione, i costi e il controllo sulle esperienze rivolte ai clienti.
