Bedste praksis for integration af FedEx API'er

Dette er en hurtig referencevejledning, der er beregnet til at hjælpe API-brugere med at forstå måder at forbedre integrationsoplevelsen med FedEx på og sikre kvaliteten af integrationsløsningen med hensyn til design, hastighed og sikkerhed.

For effektivt at integrere med FedEx API'er bør udviklere følge disse bedste praksisser for integration:

API URI'er

• Der findes separate API URI'er til test og produktion. 
• Udviklere skal bruge test-URI'er til udvikling og integrationstest og produktions-URI'er til produktion.

Nedenfor vises API-URI'er:

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

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

Håndtering af legitimationsoplysninger

• API-nøgle og hemmelig nøgle

• Din API-nøgle og hemmelige nøgle bruges til at identificere din applikation og skal bruges i OAuth-token-anmodning.

1. Din API-nøgle og hemmelige nøgle skal behandles meget sikkert. Distribuer ikke din API-nøgle eller hemmelige nøgle via e-mail eller distribueret kode, inklusive JavaScript på klientsiden.
2. Din applikation kompromitteres, hvis din API-nøgle eller hemmelige nøgle bliver stjålet. Hvis du har mistanke om, at dine legitimationsoplysninger er blevet stjålet eller kompromitteret, skal du genoprette den hemmelige nøgle med det samme.
3. Undgå at logføre følsomme oplysninger såsom din hemmelige nøgle.

• Undlad at hardkode API-nøglen og den hemmelige nøgle i din kode.
• Din applikation bør være dynamisk i stand til at opdatere API-nøglen og den hemmelige nøgle.
• Klientens legitimationsoplysninger skal opbevares i en samling af legitimationsoplysninger/et sikkert sted, så de ikke kan kompromitteres.

• OAuth-token

• Adgangstokenet må kun gemmes på webapplikationsserveren og må ikke bruges i browseren.
• Undlad at hardkode tokenet i dine applikationer.
• Sørg for at sikre adgangstoken for at beskytte det.
• Undgå at foretage flere opkald til OAuth-token API'en for en ny adgangstoken. Det anbefales at cache adgangstokenet, indtil HTTP-fejlkoden 401 er observeret. Genopret OAuth-tokenet på det tidspunkt.
• Vis ikke tokenet for slutbrugeren eller applikationen.
• Brug HTTPS til enhver API-transaktion.

Kodningspraksis

• For at bevare overholdelsen af den nyeste og mest sikre kommunikationsprotokol for datakryptering anbefales det at bruge Transport Layer Security (TLS) version 1.2 eller nyere.
• Glem ikke at indstille de korrekte API-overskrifter, der er nødvendige for hver API-anmodning. Du finder overskriftsoplysningerne på hver API-dokumentationsside. 
• 'Indholdstype' i HTTP POST skal være 'applikation/json'.
• Se prøvekoden for at komme i gang med hver API. Hvert API-slutpunkt ledsages af flere eksempler, der hjælper dig med at forstå de nødvendige elementer, formater og andre detaljer.
• Når brugere eller udviklere sender mange decimaler i deres værdier, kan det forårsage underlige fejl. For vægt og valutaværdi/-beløb er kun to eksplicitte decimaler tilladte. Mål – såsom længde, bredde og højde – understøtter ikke decimaler.

Eksempel: Vægt: 45,26, valutaværdi/-beløb: 100,52, længde: 10, bredde: 25, højde: 15.

• Send ikke tomme elementer.

Eksempel: "Gadelinjer":""

• Send kun de nødvendige data for at behandle anmodningen.

For eksempel for en amerikansk indenlandsk forsendelse skal du undgå at sende den kommercielle faktura og varedata, der muligvis kun er påkrævet til internationale forsendelser.

• Under udviklingen skal du afgøre, hvordan der skal reageres, hvis et ikke-påkrævet svarelement, såsom en vurdering, ikke returneres. Evaluer transaktionssvaret for manglende elementer før brug af data.

For eksempel er det muligt at sende en pakke, hvis vurderingen ikke er funktionel. Test transaktionssvaret for manglende elementer før brug af data.

• Generelt skal du undgå hårde afhængigheder af FedEx API-integration, når det er relevant.
• For at reducere latenstid og få nøjagtige resultater skal følgende bruges:
  
  • Filtrering – Brug dette til at indskrænke søgningen med de parametre, du søger efter.
  • Sortering - Brug dette til at sortere resultaterne efter en bestemt parameter i stigende eller faldende rækkefølge.
• Kontrollér, at de krævede felter –- såsom modtagerens postnummer og pakkevægt – har data, før transaktionen sendes. Kontrollér, at dataene er passende for det pågældende felt. Derved minimeres transaktionsfejl.
  

For eksempel skal du for amerikanske postnumre kontrollere, at feltet er udfyldt med tal og indeholder 5 cifre eller har et postnummer i +4-format.

• For at undgå negativ indflydelse på FedEx-systemets tilgængelighed og pålidelighed:
  
  • Kør ikke ydelsestest i test- eller produktionsmiljøet.
  • Sørg for at oprette kodningslogik for at forhindre, at den samme transaktion mislykkes gentagne gange.
• Transaktionsgrænsen er indstillet til 1400 transaktioner i løbet af 10 sekunder. Hvis denne grænse nås i de første få sekunder, returneres HTTP-fejlkoden 429 For mange anmodninger, og transaktioner vil blive begrænset, indtil 10 sekunder er nået. Derefter optages transaktioner igen.
  

Hvis vi fx modtager 1400 anmodninger i de første fire sekunder, vises HTTP-fejlkode 429 For mange anmodninger - ”Vi har modtaget for mange anmodninger i en kort periode. Vent et stykke tid, og prøv igen." og transaktioner begrænses i de næste seks sekunder og genoptages derefter.

• Sørg for ikke at hardkode forretningsregler såsom servicetyper, pakketyper, vægtgrænser osv. for forsendelser, da de kan ændres.

Håndtering af fejl

Hvert API-svar vil indeholde en HTTP-statuskode og nyttelast for svar. Nogle svar vil være ledsaget af en fejl, advarsel eller noter, hvis det er relevant. Advarsler og noter er ikke tegn på en fejl; dog skal fejlen eller advarselsmeddelelsen logges og undersøges. Korrekt fejlhåndtering sikrer, at din integration med FedEx er problemfri og kan hjælpe med at undgå nedbrud.

HTTP-statuskoder

Pris

• Der er to måder at få et pristilbud på:
  
  • Pris for en bestemt servicetype – Resultaterne filtreres efter den angivne servicetypeværdi. Dette vil reducere størrelsen på svaret og reducere transaktionens responstid.
    

    Eksempel: STANDARD_OVERNIGHT

  • Prisbutik – Hvis der ikke er angivet nogen servicetype, returneres alle de relevante tjenester og de tilsvarende priser.
• Brug servicetilgængelighed-API'en til at afgøre, hvilke tjenester, pakkemuligheder og specialtjenester der er tilgængelige for et givet oprindelsesdestinationspar, og videregiv tjenestetypen og pakkemuligheden i prisanmodningen.
  

  Fx er STANDARD_OVERNIGHT (blandt andet) ikke tilgængelig for alle postnumre.

• Hvis der skal anvendes en speciel servicetype for en forsendelse, skal den specielle servicetype og dens detaljer inkluderes. 
  
  • Bemærk: Nogle specielle servicetyper har ikke detaljer.
• Se Dokumentation til Pris API.

Send

• Brug servicetilgængelighed-API'en til at afgøre, hvilke tjenester der er tilgængelige for et givet oprindelsesdestinationspar, og videregiv tjenestetypen og pakkemuligheden i forsendelsesanmodningen.
• Hvis der skal anvendes en speciel servicetype for en forsendelse, skal den specielle servicetype og dens detaljer inkluderes.
  
  • Bemærk: Nogle specielle servicetyper har ikke detaljer.
• Udfør afslutningen for FedEx Ground sidst på forsendelsesdagen, før forsendelsen afhentes.
  
• Se Dokumentation til Forsendelse API.
  

Track

• Begræns antallet af trackingnumre i en enkelt trackinganmodning til 30. Dette vil reducere størrelsen på svaret og reducere transaktionens responstid.
• Begræns antallet af gange, en pakke trackes til det, der er nødvendigt for virksomhedens behov.
• Ved batchtracking fjernes eventuelle pakker, der har returneret en trackingstatus som "leveret" fra batch.
• Se Dokumentation til Tracking API.

Adressevalidering

• FedEx leverer adressevalidering som et forslag og ikke som en endelig bestemmelse. Slutbrugeren skal foretage en endelig afgørelse for, om en adresse kan bruges ud fra de leverede data og deres forretningsbehov. Der skal være fastlagt en proces for at håndtere adresser, der ikke kan valideres, så ordrer stadig kan behandles.
• For at sikre en bedre forsendelsesoplevelse skal du ikke gøre forsendelsesprocessen afhængig af valgfrie tjenester såsom Adressevalidering.

Hvis Adressevaliderings-API'en for eksempel ikke er tilgængelig på tidspunktet for ordreindtastning eller forsendelse, skal der være et muligt alternativ for at afslutte forsendelsen.

• Se Dokumentation til Adressevalidering API.
  

Søgning efter FedEx-adresser

• Begræns din søgning ved at give specifikke attributter (dvs. placeringstype, tilbudte tjenester osv.) for at få passende placeringsindstillinger og hurtigere responstid.
• Se Dokumentation til FedEx-adressesøgning API.
  

Afhentningsanmodning

• Indtast ikke tidligere klar tid, tidligere dato eller en dato, der er for langt ude i fremtiden til at planlægge en afhentning.
• Anonyme afhentninger er ikke tilladt.
  
• Se Dokumentation til Afhentningsanmodning API.
  

Servicetilgængelighed

• Hvis du ønsker at få resultater for flere opererende virksomheder, såsom FedEx Express (FDXE), FedEx Ground (FDXG), FedEx Freight (FXFR) og FedEx Ground® Economy, skal du enten udelade carrierCodes-elementet eller sende separate anmodninger om servicetilgængelighed, da der ikke kan specificeres flere kurerkoder.
• Sørg for, at du har forhåndsgodkendelse for individuelle paller på 68,5 kg (151 lbs) eller mere og paller, der overstiger 1000 kg (2,200 lbs).
  
• Hvis du specificerer SATURDAY_DELIVERY for variable indstillinger, får du både leveringsmuligheder for lørdag og regelmæssige indstillinger for alle servicetyper, hvor lørdagslevering er en mulighed. Angiv ikke SATURDAY_DELIVERY for specielle servicetyper, ellers vil det kun returnere alle relevante muligheder for lørdagslevering.
• Se Dokumentation til Servicetilgængelighed API.

Kundeservice

Vi er her for at hjælpe, hvis du har spørgsmål eller har brug for hjælp! Gå til vores side Support for ressourcer og information om måder at kontakte os på.