Best Practice per le API di integrazione FedEx

Questa è una guida rapida di riferimento finalizzata ad aiutare i consumatori di API a capire come migliorare l'esperienza di integrazione con FedEx e garantire la qualità della soluzione di integrazione in termini di design, velocità e sicurezza.

Per integrare in maniera efficace le API FedEx, gli sviluppatori dovrebbero seguire le seguenti best practice per l'integrazione:

API URI

• Esistono API URI diverse per il test e la produzione. 
• Gli sviluppatori dovrebbero usare URI di prova per testare lo sviluppo e l'integrazione e URI di produzione per la produzione.

Di seguito un elenco delle API URI:

Test: https://apis-sandbox.fedex.com/

Produzione: https://apis.fedex.com/

Gestione delle credenziali

• Chiave API e Chiave segreta.

• La vostra Chiave API e la Chiave segreta servono a identificare la vostra applicazione e devono essere usate nella richiesta del token OAuth.

1. La vostra Chiave API e la Chiave segreta devono essere trattate con la massima sicurezza. Non distribuitele via email o tramite codice distribuito incluso JavaScript lato cliente.
2. La vostra applicazione sarà compromessa se la vostra Chiave API o la Chiave segreta vengono rubate. Se sospettate che le vostre credenziali siano state rubate o corrotte, vi invitiamo a ricreare immediatamente la Chiave Segreta.
3. Evitate di registrare informazioni sensibili come la Chiave segreta.

• Non codificate la Chiave API e la Chiave segreta nel vostro codice.
• La vostra applicazione dovrebbe essere in grado di aggiornare dinamicamente la Chiave API e la Chiave segreta.
• Le credenziali client devono essere conservate in una cassaforte/posto sicuro, così da non poter essere corrotte.

• Token OAuth

• Il token di accesso dovrebbe essere conservato soltanto nell'applicazione server e non deve essere esposto al browser.
• Non codificate il token nelle vostre applicazioni.
• Conservate in sicurezza i token di accesso per evitare di comprometterli.
• Evitate di effettuare chiamate multiple all'API token OAuth per un nuovo token di accesso. Si consiglia di nascondere il token di accesso fino a quando si registra il codice di errore HTTP 401. Rigenerate il token OAuth in quel momento.
• Non esponete il token al cliente finale o all'applicazione.
• Utilizzate HTTP per ogni transazione API.

Pratiche di codifica

• Nel rispetto dell'ultimo e più sicuro protocollo di comunicazione con crittografia dei dati, si consiglia di utilizzare Transport Layer Security (TLS) versione 1.2 o superiore.
• Non dimenticate di impostare i giusti titoli API necessari per ogni richiesta API. Troverete le informazioni sul titolo in ogni pagina contenente la documentazione API. 
• Il 'Tipo di contenuto nel POST HTTP dovrebbe essere 'applicazione/json'.
• Vi invitiamo a fare riferimento al codice campione per iniziare con ogni API. Ogni terminale API è accompagnato da diversi campioni che vi aiuteranno a capire gli elementi necessari, i formati e altri dettagli.
• Quando gli utenti o gli sviluppatori inviano diversi decimali nei loro valori, possono causare errori strani. Per i valori/quantità di peso e valuta, sono consentite solo due cifre decimali espresse. Le dimensioni – come lunghezza, altezza e profondità – non supportano i decimali.

Esempio: Peso: 45,26, Importo/valore valuta: 100,52, lunghezza: 10, larghezza: 25, altezza: 15.

• Evitate di inviare elementi vuoti.

Esempio:“Streetlines”:””

• Inviate solamente dati necessari a elaborare la richiesta.

Ad esempio, per una spedizione domestica negli USA, evitate di inviare la fattura commerciale e i dati relativi alla merce che potrebbero essere necessari solamente per spedizioni internazionali.

• Durante lo sviluppo, determinate come reagire se un elemento di risposta non richiesto, come una tariffa, non viene restituito. Valutate la risposta della transazione per gli elementi mancanti prima di utilizzare i dati.

Ad esempio, è possibile spedire un collo se il servizio rating non è funzionale. Testate la risposta della transazione per gli elementi mancanti prima di utilizzare i dati.

• In generale, evitate una forte dipendenza dall'integrazione di API FedEx ove applicabile.
• Per ridurre la latenza e ottenere risultati accurati, devono essere usati i seguenti elementi:
  
  • Filtrazione - Per restringere la ricerca secondo i parametri desiderati.
  • Ordinamento - Per ordinare i risultati secondo un certo parametro, in ordine ascendente o discendente.
• Verificate che i campi necessari – come destinatario, codice postale e peso del collo – abbiano dati prima di inviare la transazione. Verificate che i dati siano appropriati per il campo in questione. Questo ridurrà gli errori di transazione.
  

Ad esempio, per i codici postali USA, verificate che il campo sia completamente numerico e di cinque cifre oppure nel formato ZIP+4.

• Per evitare un impatto indesiderato sulla disponibilità e l'affidabilità del sistema FedEx:
  
  • Non eseguite test di performance nell'ambiente di test o produzione.
  • Predisponete una logica di codifica per far sì che la stessa transazione non fallisca ripetutamente.
• Il limite di throttling è impostato su 750 transazioni in 10 secondi. Se tale limite viene raggiunto nei primi secondi, verrà restituito il codice di errore HTTP 429 Troppe richieste e le transazioni saranno limitate per i successivi 10 secondi; le transazioni saranno poi ripristinate nuovamente.
  

Ad esempio, se riceviamo 750 richieste nei primi quattro secondi, verrà restituito un codice di errore HTTP 429 Troppe richieste - "Abbiamo ricevuto troppe richieste in un breve periodo di tempo. Vi invitiamo ad attendere prima di riprovare." e le transazioni saranno limitate per i successivi sei secondi e poi verranno ripristinate.

• Non codificate regole aziendali come i tipi di servizi, i tipi di colli, i limiti di peso, ecc. per le spedizioni poiché sono soggetti a modifica.

Gestione degli errori

Ogni risposta API conterrà un codice di stato HTTP e un carico utile di risposta. Alcune risposte avranno un errore, un avviso o una nota, come applicabile. Avvisi e note non indicano un fallimento; tuttavia, il messaggio di avviso o errore dovrebbe essere registrato ed esaminato. Un'appropriata gestione degli errori assicura che l'integrazione con FedEx vada a buon fine e potrebbe contribuire a evitare danni.

Codici di stato HTTP

Tariffa

• Due sono i modi di calcolare la tariffa:
  
  • Tariffa per un Tipo di servizio specifico - I risultati saranno filtrati per il valore Tipo di servizio indicato. Ciò diminuirà la mole delle risposte e ridurrà il tempo di risposta della transazione.
    

    Esempio: STANDARD_OVERNIGHT

  • Acquista tariffa – Se non viene indicato alcun Tipo di servizio, allora tutti i servizi applicabili e le tariffe corrispondenti saranno restituiti.
• Utilizzate l'API relativa alla disponibilità del servizio per stabilire quali servizi, opzioni per i colli e servizi speciali sono disponibili per un determinato abbinamento origine-destinazione e passare l'opzione Tipo di servizio e collo nella richiesta di tariffe.
  

  Ad esempio, STANDARD_OVERNIGHT (tra gli altri) non è disponibile tra tutti i codici postali.

• Affinché un servizio speciale sia applicato a una spedizione, deve essere incluso il tipo di servizio speciale e i suoi dettagli. 
  
  • Nota: Alcuni servizi speciali non hanno dettagli.
• Visualizzate la documentazione relativa alla API Tariffe.

Spedire

• Utilizzate l'API relativa alla disponibilità del servizio per determinare quali servizi sono disponibili per un dato abbinamento origine-destinazione e passare l'opzione tipo di servizio e collo nella richiesta di spedizione.
• Affinché un servizio speciale sia applicato a una spedizione, deve essere incluso il tipo di servizio speciale e i suoi dettagli.  
  • Nota: Alcuni servizi speciali non hanno dettagli.
• Effettuate la chiusura per FedEx Ground alla fine della giornata di spedizione prima che la spedizione sia ritirata.
  
• Visualizzate la documentazione relativa alla API di spedizione.
  

Monitoraggio

• Limitate il numero di numeri di monitoraggio in una singola richiesta di monitoraggio a 30. Ciò diminuirà la mole delle risposte e ridurrà il tempo di risposta della transazione.
• Limitate il numero di volte in cui un collo è monitorato a quelle necessarie per i bisogni aziendali.
• Per il monitoraggio di un lotto, rimuovete dal lotto ogni collo che ha restituito come stato di monitoraggio "consegnato".
• Visualizzate la documentazione relativa all'API di monitoraggio.

Convalida indirizzo

• FedEx fornisce la Convalida dell'indirizzo come suggerimento e non come una decisione finale. L'utente finale deve poter determinare in ultima istanza se un indirizzo è utilizzabile dai dati forniti e dai loro bisogni aziendali. Deve esistere un processo per la gestione degli indirizzi che non possono essere convalidati così che gli ordini possano ancora essere processati.
• Per assicurare un'esperienza di spedizione migliore, non rendete il processo di spedizione dipendente da servizi opzionali come la Convalida indirizzi.

Ad esempio, se la API relativa alla convalida indirizzi non è disponibile al momento dell'inserimento dell'ordine o della spedizione, deve essere in vigore una contingenza per completare la spedizione.

• Visualizzate la documentazione sulla API relativa alla convalida indirizzi.
  

Ricerca filiali FedEx

• Ristringete la ricerca fornendo attributi specifici (ad esempio, tipo di filiale, servizi offerti, etc.) per ottenere opzioni idonee sulle filiali e un tempo di risposta più rapido.
• Visualizzate la documentazione API per la ricerca di location FedEx.
  

Richiesta di ritiro

• Non inserito un orario collo pronto passato, una data passata o una data che è troppo lontana nel futuro per prenotare un ritiro.
• I ritiri anonimi non sono consentiti.
  
• Visualizzate la documentazione relativa alla API sulla richiesta di ritiro.
  

Disponibilità servizio

• Per ottenere risultati per più società operanti come FedEx Express (FDXE), FedEx Ground (FDXG), FedEx Freight (FXFR) e FedEx Ground® Economy, è necessario omettere i Codici vettore oppure inviare richieste separate sulla disponibilità del servizio poiché i codici per più vettori non possono essere specificati.
• Assicuratevi di avere una preapprovazione per pallet individuali di almeno 151 lb e pallet superiori a 2.200 lb.
  
• Se specificate SATURDAY_DELIVERY per opzioni variabili, otterrete sia opzioni di consegna di sabato che opzioni regolari per tutti i servizi in cui la consegna il sabato è un'opzione. Non specificate SATURDAY_DELIVERY per servizi speciali, o restituirà solamente tutte le opzioni applicabili per la consegna di sabato.
• Visualizzate la documentazione relativa alla API disponibilità del servizio.

Servizio Clienti

Siamo pronti ad aiutarla nel caso abbia domande o abbia bisogno di assistenza! La invitiamo a visitare la pagina di Supporto per maggiori informazioni su come contattarci.