API dei corrieri di spedizione spiegate: UPS, FedEx, USPS, DHL e altri
Le API dei vettori di spedizione sono connessioni software che consentono a un negozio, a un sistema di gestione del magazzino, a una piattaforma di gestione degli ordini o a uno strumento di assistenza clienti di scambiare dati sulle spedizioni con vettori come UPS, FedEx, USPS e DHL. Possono supportare attività quali richieste di tariffazione, creazione di etichette, prenotazione delle spedizioni, aggiornamenti di tracciamento, verifiche degli indirizzi e notifiche sugli eventi di consegna. L’approccio API più adatto dipende meno dal nome del vettore e più dal flusso di lavoro da automatizzare, dai Paesi serviti e dai sistemi già in uso.
Un’integrazione con un singolo vettore può funzionare bene quando il volume delle spedizioni e l’area di servizio sono prevedibili. Un’API multi-vettore è generalmente più pratica quando un’operazione confronta i servizi, effettua spedizioni internazionali o necessita di un unico formato di tracciamento per diversi vettori. Questa guida illustra i principali tipi di API, le differenze generali tra i principali vettori e gli aspetti da verificare prima di sviluppare o acquistare un’integrazione.
Cosa fa un’API di un vettore di spedizione
Un’API, ovvero un’interfaccia di programmazione delle applicazioni, definisce il modo in cui due sistemi software scambiano richieste e risposte. Nelle spedizioni, l’applicazione può inviare i dettagli del pacco, gli indirizzi di origine e destinazione, le preferenze sul servizio e le informazioni doganali. Il vettore o la piattaforma di spedizione restituisce quindi una risposta, come una tariffa di spedizione, i dati dell’etichetta, un numero di tracciamento o un messaggio di errore.
Le API dei vettori normalmente svolgono diverse funzioni separate:
- Calcolo delle tariffe: richiede un costo di spedizione stimato o basato sul contratto per un pacco e un servizio.
- Creazione della spedizione: invia i dettagli della spedizione e riceve un numero di tracciamento o una conferma della spedizione.
- Generazione dell’etichetta: produce un’etichetta stampabile, spesso come PDF, immagine o contenuto documentale.
- Tracciamento: recupera eventi, stati, posizioni e informazioni sulla consegna della spedizione, quando disponibili.
- Servizi per gli indirizzi: convalida, standardizza o completa le informazioni sull’indirizzo, a seconda del vettore e della destinazione.
- Ritiro e manifestazione: supporta le richieste di ritiro o la documentazione di fine giornata per le spedizioni, quando il conto e il servizio lo consentono.
- Notifiche: fornisce informazioni sullo stato tramite polling, webhook, funzionalità e-mail o un altro meccanismo basato sugli eventi.
Queste funzionalità non sono incluse automaticamente in ogni account API del vettore. Un vettore può separare i servizi in prodotti diversi, richiedere l’approvazione dell’account o limitare l’accesso in base al Paese, al tipo di servizio, all’accordo con il cliente o all’ambiente tecnico. Considera ogni funzionalità come un elemento da confermare nella documentazione aggiornata del vettore, anziché dedurla semplicemente dall’esistenza di un’API.
API dirette dei vettori e API multi-vettore
Esistono due modelli pratici di integrazione. Un’integrazione diretta collega il software alla piattaforma per sviluppatori di un singolo vettore. Un’integrazione multi-vettore collega il software a un intermediario che uniforma diversi vettori attraverso un’unica interfaccia.
| Modello | Vantaggi | Compromessi | Ideale per |
|---|---|---|---|
| API diretta del vettore | Accesso diretto ai servizi del vettore, alle regole dell’account e ai dati delle spedizioni | Credenziali, formati, test, gestione degli errori e manutenzione separati per ogni vettore | Un’azienda con un vettore principale o un flusso di lavoro specializzato |
| API multi-vettore | Un’unica integrazione può semplificare il tracciamento, la scelta del vettore e la gestione uniforme degli stati | Copertura, profondità delle funzionalità, requisiti dell’account e condizioni commerciali variano in base al fornitore | E-commerce multi-vettore, marketplace, 3PL e operazioni transfrontaliere |
Un’API multi-vettore non sostituisce necessariamente il rapporto diretto con il vettore. Alcune funzioni di spedizione possono comunque richiedere un account del vettore, tariffe negoziate, approvazione o configurazione diretta. È inoltre opportuno verificare se l’intermediario crea le etichette, si limita a tracciare le spedizioni esistenti o supporta entrambe le funzioni.
Confronto tra le API dei principali vettori
API UPS
UPS fornisce risorse per sviluppatori per collegare le applicazioni aziendali ai servizi UPS. A seconda dell’account, della regione e del prodotto, gli sviluppatori possono valutare funzionalità quali calcolo delle tariffe, spedizione, tracciamento, servizi relativi agli indirizzi e flussi di lavoro per i ritiri tramite l’ambiente ufficiale per sviluppatori di UPS.
UPS è spesso preso in considerazione dalle aziende che gestiscono un volume significativo di pacchi, necessitano di servizi specifici UPS o dispongono già di un account e di un contratto UPS. La domanda pratica non è semplicemente se UPS disponga di un’API, ma se lo specifico servizio UPS, l’accordo di fatturazione, la destinazione e il profilo del pacco possano essere utilizzati tramite il prodotto API disponibile per il proprio account.
Prima dell’implementazione, conferma il processo di autenticazione attuale, la disponibilità del sandbox, i formati delle richieste supportati, l’output delle etichette, l’idoneità alle tariffe, il comportamento degli eventi di tracciamento e i requisiti di migrazione. La documentazione e i nomi dei prodotti UPS possono cambiare, quindi utilizza il portale ufficiale per sviluppatori UPS come punto di partenza.
API FedEx
FedEx offre una piattaforma per sviluppatori destinata alle applicazioni che devono operare con i servizi di spedizione e consegna FedEx. La relativa documentazione è la fonte appropriata per verificare le API disponibili, le credenziali, gli ambienti di test, i flussi di lavoro delle spedizioni, il tracciamento e i requisiti specifici dei servizi.
FedEx può essere una scelta efficace quando un’operazione si basa sui servizi FedEx o necessita di un controllo specifico del vettore sui flussi di lavoro di spedizione e tracciamento. L’impegno di integrazione può comprendere molto più dell’invio di un indirizzo e della ricezione di un’etichetta. Dimensioni del pacco, scelta del servizio, dettagli dell’account, informazioni doganali, regole sulle merci pericolose e documentazione internazionale possono influire sulla richiesta e sulla risposta.
I team dovrebbero testare sia le richieste riuscite sia quelle non riuscite. Ad esempio, un’applicazione dovrebbe sapere come gestire un indirizzo non valido, un servizio non supportato, una richiesta di spedizione duplicata, un campo doganale mancante e un’interruzione temporanea del vettore. Consulta il FedEx Developer Portal per la documentazione aggiornata e i requisiti di accesso.
API USPS
USPS fornisce risorse online per aziende e sviluppatori per le applicazioni che utilizzano i servizi USPS. USPS è particolarmente rilevante per i flussi di lavoro relativi a pacchi e posta nazionali negli Stati Uniti, mentre i prodotti API esatti e le condizioni di accesso devono essere verificati nella documentazione ufficiale aggiornata.
Le integrazioni USPS richiedono test accurati perché un’azienda potrebbe dover distinguere tra prodotti postali, servizi per pacchi, eventi di tracciamento, dati sugli indirizzi e flussi di lavoro relativi alle etichette o all’affrancatura. Un requisito limitato al tracciamento è sostanzialmente diverso da un’applicazione che deve acquistare l’affrancatura o generare etichette di spedizione.
Non presumere che un’API USPS abbia la stessa struttura delle richieste, lo stesso vocabolario degli eventi, la stessa disponibilità dei servizi o lo stesso modello di account di UPS o FedEx. Esamina le risorse per sviluppatori USPS e conferma quali prodotti sono disponibili per il tuo caso d’uso, ambito geografico e configurazione dell’account. Se la tua azienda necessita solo di una visualizzazione coerente del tracciamento tra diversi vettori, un’API multi-vettore focalizzata sul tracciamento potrebbe richiedere meno logica personalizzata per i vettori rispetto a diverse integrazioni dirette.
API DHL
DHL è un gruppo di aziende con diversi servizi logistici e di spedizione pacchi, quindi “l’API DHL” non è un unico prodotto universale per ogni spedizione. Le risorse per sviluppatori DHL comprendono API e strumenti associati ai suoi servizi, ma il prodotto pertinente dipende dall’unità aziendale DHL, dalla destinazione, dal tipo di spedizione e dal rapporto con l’account.
DHL è un candidato naturale per le spedizioni internazionali, i servizi express e le operazioni transfrontaliere, ma l’integrazione corretta deve comunque essere abbinata al servizio acquistato. Verifica se la documentazione si applica a DHL Express, ai servizi di spedizione pacchi per l’e-commerce, al trasporto merci o a un’altra offerta DHL prima di progettare il flusso di lavoro.
Controlla i Paesi supportati, i campi doganali e delle fatture commerciali, i codici dei servizi, il comportamento del tracciamento, i formati delle etichette e i requisiti di attivazione dell’account nel DHL Developer Portal. Per le implementazioni internazionali, includi un processo per gestire le eccezioni doganali e la documentazione incompleta, anziché considerare il tracciamento come l’intero ciclo di vita della spedizione.
Altri vettori
Le aziende possono aver bisogno anche di vettori regionali o nazionali come Canada Post, Royal Mail, Australia Post, DPD, GLS o Japan Post. Le loro API differiscono per copertura, attivazione, nomi dei servizi, livello di dettaglio degli eventi di tracciamento, formati delle etichette e supporto alle spedizioni internazionali. “Più vettori” non significa quindi automaticamente meglio. La copertura dovrebbe essere valutata in base alle tratte, ai servizi e ai tipi di spedizione effettivamente utilizzati.
Per un vettore importante per la tua attività, esamina prima la documentazione per sviluppatori del vettore stesso. Se il vettore è supportato tramite una piattaforma di terze parti, conferma se l’integrazione è diretta, se devi fornire le tue credenziali del vettore e quali funzioni sono disponibili. Il supporto al tracciamento non dimostra che siano supportati anche il calcolo delle tariffe, la creazione delle etichette o l’annullamento delle spedizioni.
API di tracciamento o API di spedizione completa?
Molti progetti usano il termine “API di spedizione” quando in realtà necessitano del tracciamento delle spedizioni. Si tratta di ambiti diversi. Un’API di tracciamento generalmente accetta un numero di tracciamento e il vettore, quindi restituisce eventi uniformati o uno stato attuale. Un’API di spedizione completa può includere tariffe, etichette, creazione della spedizione, documenti doganali e tracciamento.
Se l’obiettivo principale è mostrare l’avanzamento della consegna in un sito e-commerce, in un portale clienti o in uno strumento di assistenza, può essere sufficiente un’integrazione focalizzata sul tracciamento. La Tracking API di 17TRACK è un esempio di prodotto di tracciamento multi-vettore; prima dell’adozione, la relativa documentazione deve essere utilizzata per verificare la copertura attuale dei vettori, i formati delle richieste, l’autenticazione e il comportamento degli eventi.
Se devi acquistare l’affrancatura o creare etichette, il solo tracciamento non completerà il flusso di lavoro. Potresti aver bisogno di account diretti dei vettori, di una piattaforma di spedizione o di un’API di spedizione multi-vettore con funzionalità documentate per le etichette. Separare precocemente questi requisiti evita un errore comune di implementazione: scegliere un prodotto di tracciamento e scoprire in seguito che non può creare la spedizione necessaria al magazzino.
Cosa verificare prima di scegliere un’API
1. Definisci il flusso di lavoro aziendale
Annota l’azione esatta che il sistema deve eseguire. Gli esempi includono “mostrare gli eventi di tracciamento dopo la spedizione di un ordine”, “selezionare il servizio idoneo più economico”, “creare un’etichetta in magazzino” o “notificare un cliente quando la consegna è in ritardo”. Ogni azione ha dati, gestione degli errori e requisiti operativi diversi.
2. Associa i vettori alle tratte e ai servizi
Elenca i Paesi di origine, i Paesi di destinazione, i tipi di pacco, i livelli di servizio, i flussi dei resi e gli eventuali prodotti soggetti a restrizioni. Un vettore può essere tecnicamente supportato ma comunque inadatto a una determinata tratta o servizio. Per le spedizioni internazionali, includi nei requisiti i dati doganali, i dazi, le imposte e la documentazione commerciale.
3. Conferma i prerequisiti di accesso e commerciali
Verifica se l’API richiede un account del vettore, una configurazione di fatturazione, un’approvazione, tariffe negoziate, un token applicativo o una verifica per la produzione. Le credenziali di test e quelle di produzione possono essere diverse. Non inserire mai segreti di produzione nel codice del browser o in repository pubblici; utilizza un’integrazione sicura lato server e ruota le credenziali secondo la tua politica di sicurezza.
4. Confronta la qualità dei dati, non solo il numero di endpoint
Chiedi come l’API rappresenta lo stato della spedizione, la consegna stimata, le eccezioni di consegna, la prova di consegna, le scansioni, i resi e le spedizioni con più colli. Un lungo elenco di endpoint non garantisce dettagli utili sugli eventi. Decidi come l’applicazione uniformerà stati quali etichetta creata, in transito, in consegna, consegnato, eccezione e restituito.
5. Testa gli scenari di errore e di cambiamento
Un’integrazione pronta per la produzione deve gestire timeout, limiti di frequenza, richieste duplicate, indirizzi non validi, scansioni mancanti, interruzioni del vettore, numeri di tracciamento modificati ed eventi tardivi o fuori ordine. Utilizza l’idempotenza quando l’API la supporta, registra gli identificativi delle richieste e rendi sicuri i nuovi tentativi. I sistemi di tracciamento devono inoltre tollerare periodi senza nuove scansioni, invece di considerare ogni periodo di inattività un errore.
6. Valuta il costo di manutenzione
Le API dei vettori cambiano. Aggiornamenti delle versioni, modifiche dei certificati, cambiamenti dei codici dei servizi, nuovi campi doganali ed endpoint dismessi possono influire sulle operazioni. Chiedi chi monitora i cambiamenti della documentazione, chi gestisce la risposta agli incidenti e con quale rapidità l’integrazione può essere aggiornata. Un fornitore multi-vettore può ridurre il numero di integrazioni gestite dal team, ma introduce una dipendenza che deve essere valutata in termini di continuità del servizio e qualità dell’assistenza.
Un quadro decisionale pratico
Scegli un’API diretta del vettore quando un vettore prevale sulle tue spedizioni, hai bisogno di funzioni specifiche del vettore e il tuo team può mantenere l’integrazione. Scegli un’API di spedizione multi-vettore quando ti servono tariffe, etichette e creazione di spedizioni per diversi vettori attraverso un unico flusso di lavoro, a condizione che i servizi richiesti siano effettivamente supportati.
Scegli un’API di tracciamento multi-vettore quando il requisito principale è un’esperienza di tracciamento coerente tra vettori, canali o Paesi. Ciò può essere utile per i team e-commerce che desiderano un modello di stato post-acquisto condiviso senza creare parser di tracciamento separati per ogni vettore. Se ti servono sia la creazione delle etichette sia il tracciamento, verifica se un unico fornitore supporta entrambe le funzioni oppure pianifica un’architettura in due parti.
Per un nuovo progetto, inizia con una piccola prova di concetto. Testa una spedizione nazionale, una spedizione internazionale se pertinente, una richiesta non riuscita, un evento di eccezione e uno scenario di reso o annullamento. Confronta i dati restituiti con la pagina di tracciamento visibile ai clienti del vettore e con le tue aspettative operative. Solo in seguito dovresti procedere con un’implementazione più ampia.
Domande frequenti
Un’API di un singolo vettore può fornire tariffe, etichette e tracciamento?
A volte, ma non bisogna darlo per scontato. Queste funzioni possono essere prodotti separati o richiedere autorizzazioni diverse per l’account. Conferma ogni funzionalità, servizio, Paese e requisito relativo alle credenziali nella documentazione aggiornata del vettore.
Un’API multi-vettore è sempre migliore di un’integrazione diretta?
No. Un’API multi-vettore può ridurre il lavoro di sviluppo quando servono flussi di lavoro comuni per diversi vettori, ma un’integrazione diretta può offrire un accesso migliore alle funzionalità specifiche del vettore o ai controlli dell’account. La scelta migliore dipende dalle funzioni necessarie e dal costo di manutenzione che puoi sostenere.
Serve un account del vettore per utilizzare un’API di spedizione?
Spesso sì, soprattutto per la creazione delle etichette, l’affrancatura, la fatturazione o le tariffe negoziate. I requisiti variano in base al vettore, al prodotto, al Paese e al fornitore. Conferma le regole di attivazione commerciali e tecniche prima di sviluppare l’integrazione.
Qual è la differenza tra numeri di tracciamento e ID della spedizione?
Un numero di tracciamento è l’identificativo utilizzato per seguire un pacco attraverso la rete di un vettore. Un ID della spedizione può identificare una transazione, un gruppo di pacchi, una richiesta di etichetta o un record interno. Una spedizione può contenere più pacchi, quindi il modello dei dati non dovrebbe presumere che un ordine corrisponda sempre a un solo numero di tracciamento.
Come dovrebbe un team scegliere tra UPS, FedEx, USPS e DHL?
Inizia dalle tratte, dai servizi, dai profili dei pacchi, dalle condizioni dell’account e dalle funzioni API richieste, anziché scegliere basandoti solo sul marchio. Poi testa la documentazione e le risposte effettive del vettore per gli scenari nazionali e internazionali più comuni.
