Bästa praxis för integrering av FedEx API:er

Det här är en snabbguide som innehåller information som kan förbättra integreringen med FedEx API:er och säkerställa integreringslösningarnas kvalitet gällande design, hastighet och säkerhet.

Utvecklare bör följa följande bästa praxis för integrering av FedEx API:er:

API URI:er

• Det finns separata API URI:er för tester och produktion. 
• Utvecklare bör använda test-URI:et för utveckling och tester av integreringen, och produktions-URI:et för produktion.

Här följer API URI:erna:

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

Produktion: https://apis.fedex.com/

Hantering av autentiseringsuppgifter

• API-nyckeln och den hemliga nyckeln

• Din API-nyckel och hemliga nyckel används för att identifiera ditt program och måste användas när en OAuth-token begärs.

1. Din API-nyckel och hemliga nyckel bör hanteras med stor försiktighet. Dela inte API-nyckeln eller den hemliga nyckeln via e-post eller distribuerad kod, inklusive JavaScript på klientsidan.
2. Ditt program kommer att äventyras om din API-nyckel eller hemliga nyckel stjäls. Skapa omedelbart en ny hemlig nyckel om du misstänker att dina autentiseringsuppgifter har stulits eller exponerats på något sätt.
3. Undvik att logga känslig information, som den hemliga nyckeln.

• Hårdkoda inte API-nyckeln och den hemliga nycken i din kod.
• Ditt program bör kunna uppdatera API-nyckeln och den hemliga nyckeln dynamiskt.
• Du bör skydda autentiseringsuppgifterna för klienten genom att spara dem i ett valv/på en säker plats.

• OAuth-token

• Åtkomsttoken bör endast sparas på webbprogramservern och får inte exponeras för webbläsaren.
• Hårdkoda inte token i ditt program.
• Skydda åtkomsttoken genom att spara dem på en säker plats.
• Undvik att göra flera anrop till API:t OAuth-token för en ny åtkomsttoken. Vi rekommenderar att du cachelagrar åtkomsttoken tills HTTP-felkod 401 visas. Skapa en ny OAuth-token när felkoden visas.
• Exponera inte token för slutanvändaren eller programmet.
• Använd HTTPS för alla API-transaktioner.

Kodningspraxis

• Vi rekommenderar att du använder Transport Layer Security-version 1.2 eller senare för att följa det senaste och säkraste kommunikationsprotokollet för datakryptering.
• Glöm inte bort att konfigurera rätt API-rubriker för varje API-förfrågan. Du hittar rubrikinformation på varje sida med API-dokumentation. 
• Innehållstypen i HTTP POST bör vara application/json.
• Använd exempelkoden för att komma igång med de olika API:erna. Varje API-slutpunkt har flera exempel med nödvändiga element, format och annan information.
• Det kan uppstå fel när användare eller utvecklare skickar värden med många decimaler. Det är endast tillåtet att använda två decimaler för vikt och valuta/belopp. Mått – som längd, bredd och höjd – har inte stöd för decimaler.

Exempel: Vikt: 45,26. Valuta/belopp: 100,52. Längd: 10. Bredd: 25. Höjd: 15.

• Undvik att skicka tomma element.

Exempel: ”Adressrader”:””

• Skicka endast data som är nödvändiga för att bearbeta förfrågan.

För försändelser inom USA ska du till exempel undvika att skicka den kommersiella fakturan och varuinformation som endast krävs för internationella försändelser.

• Under utvecklingen bör du bestämma vad som ska hända om ett icke-nödvändigt svarselement, som ett pris, inte returneras. Utvärdera transaktionssvaret för saknade element innan du använder data.

Det är till exempel möjligt att skicka ett paket om priset inte är funktionellt. Testa transaktionssvaret för saknade element innan du använder data.

• Det är i allmänhet bra att undvika strikta beroenden på integreringen med FedEx API:er när det är möjligt.
• För att minska antalet förseningar och få mer exakta resultat bör följande användas:
  
  • Filtrering – Används för att begränsa sökningen med parametrarna du letar efter.
  • Sortering – Används för att sortera resultaten efter en specifik parameter i stigande eller fallande ordning.
• Validera att obligatoriska fält – som mottagarens postnummer och paketvikt – innehåller data innan transaktionen skickas. Validera även att angivna data är lämpliga för fältet i fråga. Det kommer att minimera antalet transaktionsfel.
  

För amerikanska postnummer bör du till exempel verifiera att det angivna värdet är helt numeriskt och antigen har ett format som är 5-siffrigt eller en ZIP-kod + 4 siffror.

• För att undvika negativa effekter på FedEx-systemets tillgänglighet och pålitlighet:
  
  • Kör inte prestandatester i test- eller produktionsmiljön.
  • Använd kodningslogik för att förhindra att samma transaktion misslyckas upprepade gånger.
• Gränsen är inställd på 1400 transaktioner under 10 sekunder. Om gränsen uppnås under de första sekunderna kommer HTTP-felkoden 429 Too many requests returneras och transaktionerna kommer att begränsas tills 10 sekunder har gått, sedan kommer transaktionerna att återupptas igen.
  

Om vi till exempel får 1400 förfrågningar under de första fyra sekunderna kommer HTTP-felkoden 429 Too many requests – ”Vi har fått för många förfrågningar på för kort tid. Vänta lite och försök igen.” – att returneras och transaktionerna att begränsas under de kommande sex sekunderna för att sedan återupptas igen.

• Hårdkoda inte affärsregler som servicetyper, pakettyper, viktgränser osv. för försändelser eftersom de kan komma att ändras.

Felhantering

Varje API-svar kommer att innehålla en HTTP-statuskod och svarets nyttolast. Vissa svar kommer att innehålla ett fel, en varning eller en notering. Varningar och noteringar indikerar inte ett fel, men fel- och varningsmeddelanden ska loggas och kontrolleras. Korrekt felhantering kommer att säkerställa att integreringen med FedEx fungerar som den ska och kan hjälpa till att undvika avbrott.

HTTP-statuskoder

Pris

• Det finns två sätt att få en prisoffert:
  
  • Pris för en specifik tjänstetyp – Resultaten kommer att filtreras efter det angivna tjänstetypsvärdet. Det kommer att minska storleken på svaret och minska svarstiden för transaktionen.
    

    Exempel:STANDARD_OVERNIGHT

  • Visa priser – Om ingen tjänstetyp anges kommer alla tillämpliga tjänster och motsvarande priser att returneras.
• Använd API:et Tillgängliga tjänster för att fastställa vilka tjänster, paketalternativ och specialtjänster som är tillgängliga för ett angivet ursprungs-/destinationspar och hoppa över alternativen för tjänstetyp och paket i Pris-förfrågan.
  

  Till exempel är STANDARD_OVERNIGHT (och andra alternativ) inte tillgängligt för alla postnummer.

• Specialtjänstetyp och tillhörande information måste anges för att en specialtjänst ska tillämpas för en försändelse. 
  
  • Obs! Vissa specialtjänster innehåller inte information.
• Mer information finns i API-dokumentationen för Pris.

Skicka

• Använd API:et Tillgängliga tjänster för att fastställa vilka tjänster som är tillgängliga för ett angivet ursprungs-/destinationspar och hoppa över alternativen för tjänstetyp och paket i Skicka-förfrågan.
  
• Specialtjänstetyp och tillhörande information måste anges för att en specialtjänst ska tillämpas för en försändelse.
  
  • Obs! Vissa specialtjänster innehåller inte information.
• Stäng FedEx Ground vid slutet av leveransdagen, innan försändelsen hämtas.
  
• Mer information finns i API-dokumentationen för Skicka.
  

Spåra

• Begränsa antalet spårningsnummer i en enskild spårningsbegäran till 30. Det kommer att minska storleken på svaret och minska svarstiden för transaktionen.
  
• Begränsa antalet gånger ett paket spåras till vad som är nödvändigt för affärsbehovet.
• Ta bort alla paket som har returnerat spårstatusen ”levererat” från batchen när du använder batchspårning.
• Mer information finns i API-dokumentationen för Spåra.

Validering av adress

• FedEx tillhandahåller Validering av adress som en källa till förslag, det ger inga slutgiltiga alternativ. Slutanvändaren måste avgöra om en adress kan användas utifrån den angivna informationen och affärsbehovet. En process måste finnas på plats för att hantera adresser som inte kan valideras för att beställningarna fortfarande ska kunna behandlas.
• Gör inte leveransprocessen beroende av valfria tjänster som Validering av adress för att säkerställa en bättre leveransupplevelse.

Om API:et Validering av adress till exempel inte är tillgängligt vid tidpunkten för orderregistrering eller leverans bör det finnas en beredskapsplan på plats så att försändelsen kan slutföras.

• Mer information finns i API-dokumentationen för Validering av adress.
  

Sök efter FedEx-kontor

• Begränsa din sökning genom att ange specifika attribut (typ av kontor, tjänster som erbjuds osv.) för att få lämpliga förslag på kontor och en snabbare svarstid.
• Mer information finns i API-dokumentationen för Sök efter FedEx-kontor.
  

Upphämtningsbegäran

• Ange inte en passerad klartid, ett passerat datum eller ett datum som är för långt fram i tiden när du schemalägger en upphämtning.
• Anonyma upphämtningar är inte tillåtna.
  
• Mer information finns i API-dokumentationen för Upphämtningsbegäran.
  

Tillgängliga tjänster

• Om du vill få resultat för flera företag som FedEx Express (FDXE), FedEx Ground (FDXG), FedEx Freight (FXFR) och FedEx Ground® Economy ska du antingen utelämna elementet carrierCodes eller skicka separata förfrågningar om tillgänglighet för tjänster, eftersom flera transportörskoder inte kan anges.
• Kontrollera att du har förhandsgodkännande för enskilda lastpallar som överstiger 69 kg och lastpallar som överstiger 1 000 kg.
  
• Om du anger SATURDAY_DELIVERY får du både alternativ för lördagsleverans och vanliga alternativ för alla tjänster där lördagsleverans är möjligt. Ange inte SATURDAY_DELIVERY för specialtjänster eftersom du endast kommer att få tillämpliga alternativ för lördagsleverans då.
• Mer information finns i API-dokumentationen för Tillgängliga tjänster.

Kundtjänst

Vi finns här för dig om du har frågor eller behöver hjälp. Du hittar resurser och information om hur du kan kontakta oss på supportsidan.