Best practices van Fedex voor het integreren van API's

Dit is een korte handeling waarin API-klanten kunnen lezen hoe ze de integratiebeleving met FedEx verder kunnen verbeteren en de kwaliteit van de integratieoplossing kunnen waarborgen wat betreft ontwerp, snelheid en beveiliging.

Om de integratie met de API's van FedEx efficiënt te laten verlopen, moeten ontwikkelaars deze best practices voor integratie hanteren:

API-URI's

• Er zijn aparte API-URI's voor testen en productie. 
• Ontwikkelaars moeten de test-URI's gebruiken voor het testen van de ontwikkeling en de integratie en de productie-URI voor de productie.

Dit zijn de API-URI's:

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

Productie: https://apis.fedex.com/

Beheer van aanmeldingsgegevens

• API-sleutel en geheime sleutel

• Uw API-sleutel en geheime sleutel worden gebruikt om uw applicatie te herkennen en moeten worden gebruikt bij een aanvraag voor een OAuth-token.

1. Veiligheid staat voorop bij het gebruik van de API-sleutel en de geheime sleutel. Stuur de API-sleutel of geheime sleutel nooit per e-mail of via gedistribueerde code, met inbegrip van JavaScript van de klant.
2. De toepassing loopt gevaar als de API-sleutel of geheime sleutel worden gestolen. Als u vermoedt dat uw gegevens zijn gestolen of gecompromitteerd, maak de geheime sleutel dan meteen opnieuw aan.
3. Leg gevoelige informatie zoals de geheime sleutel niet vast.

• Leg de API-sleutel en geheime sleutel niet vast in uw code.
• Uw toepassing moet de API-sleutel en geheime sleutel dynamisch kunnen bijwerken.
• De klantreferenties moeten in een kluis of veilige plaats worden opgeslagen, zodat ze niet kunnen worden gecompromitteerd.

• OAuth-token

• Het toegangstoken mag alleen op de webtoepassingsserver worden opgeslagen en mag niet aan de browser worden blootgesteld.
• Leg het token niet vast in uw toepassingen.
• Beveilig de toegangstokens om te voorkomen dat ze worden gecompromitteerd.
• Vraag nooit meerdere keren tegelijkertijd een nieuw toegangstoken aan via de OAuth-token-API. Het wordt aanbevolen om het toegangstoken in de cache op te slaan totdat de HTTP-foutcode 401 wordt weergegeven. Maak op dat moment een nieuwe OAuth-token aan.
• Stel het token niet bloot aan de eindgebruiker of toepassing.
• Gebruik HTTPS voor elke API-transactie.

Coderingspraktijken

• Voor de naleving van het nieuwste en veiligste communicatieprotocol voor gegevenscodering, wordt aanbevolen Transport Layer Security (TLS) versie 1.2 of hoger te gebruiken.
• Vergeet niet voor elke API-aanvraag de juiste API-kopteksten in te stellen. U vindt de koptekstgegevens onder elke API-documentatiepagina. 
• Het 'Inhoudstype' in HTTP POST moet 'application/json' zijn.
• Raadpleeg de voorbeeldcode om met elke API aan de slag te gaan. Elk API-eindpunt wordt vergezeld door verschillende voorbeelden die u helpen de vereiste elementen, indelingen en andere details te begrijpen.
• Wanneer gebruikers of ontwikkelaars hun waarden met veel decimalen verzenden, kan dit vreemde fouten veroorzaken. Voor het gewicht, de valutawaarde en het valutabedrag zijn slechts twee expliciete decimalen toegestaan. Decimalen worden niet ondersteund voor afmetingen, zoals lengte, breedte en hoogte.

Voorbeeld: gewicht: 45,26, valutawaarde of -bedrag: 100,52, lengte: 10, breedte: 25, hoogte: 15.

• Vermijd het verzenden van lege elementen.

Voorbeeld: “Streetlines”:””

• Verzend alleen gegevens die nodig zijn om de aanvraag te verwerken.

Vermijd bijvoorbeeld voor een binnenlandse zending in de VS dat u de handelsfactuur en artikelgegevens verzendt die mogelijk alleen voor internationale zendingen zijn vereist.

• Bepaal bij het ontwikkelen hoe te reageren als een niet-vereist antwoordelement, zoals een tarief, niet wordt geretourneerd. Evalueer de transactiereactie op ontbrekende elementen voordat u gegevens gebruikt.

Het is bijvoorbeeld mogelijk om een pakket te verzenden als de tarieven niet functioneel zijn. Test de transactiereactie op ontbrekende elementen voordat u gegevens gebruikt.

• Vermijd, indien van toepassing, over het algemeen harde afhankelijkheden van de API-integratie van FedEx.
• Voor het verminderen van latentie en het verkrijgen van nauwkeurige resultaten, moet het volgende worden gebruikt:
  
  • Filteren: te gebruiken om de zoekopdracht te verfijnen met de door u gezochte parameters.
  • Sorteren: te gebruiken om de resultaten in oplopende of aflopende volgorde te sorteren op basis van een specifieke parameter.
• Controleer of de vereiste velden, zoals de postcode van de ontvanger en het gewicht van het pakket, gegevens bevatten voordat de transactie wordt verzonden. Controleer of de gegevens voor het betreffende veld geschikt zijn. Zo worden transactiefouten tot een minimum beperkt.
  

Controleer bijvoorbeeld voor Amerikaanse postcodes of het veld volledig numeriek is en of de postcode een vijfcijferige of een ZIP+4-indeling heeft.

• Voor het voorkomen van nadelige gevolgen voor de beschikbaarheid en betrouwbaarheid van het FedEx-systeem:
  
  • Voer geen prestatietests uit in de test- of productieomgeving.
  • Zorg voor coderingslogica om te voorkomen dat dezelfde transactie herhaaldelijk mislukt.
• De beperkingslimiet is ingesteld op 750 transacties per 10 seconden. Als deze limiet in de eerste paar seconden wordt overschreden, wordt de HTTP-foutcode 429 'Te veel aanvragen' geretourneerd en zullen transacties worden beperkt totdat er 10 seconden zijn verstreken; daarna zullen de transacties weer worden hervat.
  

Als we bijvoorbeeld in de eerste 4 seconden 750 aanvragen ontvangen, wordt de HTTP-foutcode 429 'Te veel aanvragen' - 'We hebben te veel aanvragen ontvangen in een korte tijd. Wacht even en probeer het daarna opnieuw.' geretourneerd en worden transacties de daaropvolgende 6 seconden beperkt en daarna hervat.

• Leg voor zendingen geen zakelijke regels vast, zoals servicetypen, pakkettypen en gewichtslimieten, aangezien deze aan wijzigingen onderhevig zijn.

Foutafhandeling

Elk API-antwoord bevat een HTTP-statuscode en nettolading van het antwoord. Sommige antwoorden gaan, indien van toepassing, vergezeld van een fout, waarschuwing of opmerking. Waarschuwingen en opmerkingen zijn geen indicatie van een fout; de fout- of waarschuwingsmelding moet echter worden vastgelegd en onderzocht. Een goede foutafhandeling zorgt ervoor dat uw integratie met FedEx soepel verloopt en kan breuken helpen voorkomen.

HTTP-statuscodes

Tarief

• Er zijn twee manieren om een prijsopgave te verkrijgen:
  
  • Prijs voor een specifiek servicetype. De resultaten worden gefilterd op de aangegeven serviceType-waarde. Zo wordt de omvang van het antwoord verkleind en de reactietijd van de transactie verminderd.
    

    Voorbeeld: STANDARD_OVERNIGHT

  • Tariefwinkel: als er geen serviceType is aangegeven, dan worden alle van toepassing zijnde diensten en bijbehorende tarieven geretourneerd.
• Gebruik de API voor servicebeschikbaarheid om te bepalen welke services, pakketopties en speciale services er beschikbaar zijn voor een bepaald herkomst-bestemmingspaar en geef het serviceType en de pakketoptie door in het tariefverzoek.
  

  STANDARD_OVERNIGHT is bijvoorbeeld (onder andere) niet beschikbaar voor alle postcodes.

• Om een speciale service op een zending toe te passen, moeten het speciale servicetype en de bijbehorende details worden vermeld. 
  
  • Opmerking: sommige speciale services hebben geen details.
• Raadpleeg de documentatie over de tarief-API.

Verzend

• Gebruik de API voor servicebeschikbaarheid om te bepalen welke services beschikbaar zijn voor een bepaald oorsprong-bestemmingspaar en geef de optie serviceType en pakket door in het verzoek Ship.
• Om een speciale service op een zending toe te passen, moeten het speciale servicetype en de bijbehorende details worden vermeld.
  
  • Opmerking: sommige speciale services hebben geen details.
• Voer aan het einde van de verzenddag de afsluiting voor FedEx Ground uit, voordat de zending wordt opgehaald.
  
• Raadpleeg de documentatie over de verzend-API.
  

Traceren

• Beperk het aantal trackingnummers in een enkele trackingaanvraag tot 30. Dit verkleint de omvang van het antwoord en vermindert de reactietijd van de transactie.
• Beperk de tracering van een pakket tot het aantal dat nodig is voor zakelijke behoeften.
• Voor batch-tracking, verwijdert u alle pakketten met de zendingsstatus 'afgeleverd' uit de batch.
• Raadpleeg de documentatie over de traceer-API.

Adresvalidatie

• FedEx biedt adresvalidatie als een suggestie en niet als een definitieve vaststelling. De eindgebruiker moet bepalen of een adres bruikbaar is op basis van de verstrekte gegevens en hun zakelijke behoeften. Er moet een proces zijn voor adressen die niet kunnen worden gevalideerd, zodat bestellingen nog steeds kunnen worden verwerkt.
• Voor een betere verzendervaring, maakt u het verzendproces niet afhankelijk van optionele services zoals adresvalidatie.

Als de adresvalidatie-API bijvoorbeeld niet beschikbaar is op het moment dat de bestelling wordt ingevoerd of verzonden, moet er een onvoorziene gebeurtenis zijn om de verzending te voltooien.

• Raadpleeg de documentatie over de adresvalidatie-API.
  

Zoeken naar FedEX-locaties

• Verfijn uw zoekopdracht door specifieke kenmerken op te geven (bijvoorbeeld het type locatie, aangeboden services, etc.) voor geschikte locatie-opties en een snellere responstijd.
• Raadpleeg de documentatie over de zoek-API voor FedEx-locaties.
  

Ophaalverzoek

• Bij het plannen van een ophaling, dient u geen tijd of datum in het verleden of in de verre toekomst in te voeren.
• Anonieme ophalingen zijn niet toegestaan.
  
• Raadpleeg de documentatie over de ophaalverzoek-API.
  

Servicebeschikbaarheid

• Voor resultaten voor meerdere werkmaatschappijen zoals FedEx Express (FDXE), FedEx Ground (FDXG), FedEx Freight (FXFR) en FedEx Ground® Economy laat u het carrierCodes-element weg of verzendt u afzonderlijke aanvragen voor servicebeschikbaarheid, aangezien er niet meerdere vervoerderscodes kunnen worden gespecificeerd.
• Zorg ervoor dat u voorafgaande goedkeuring hebt voor individuele pallets van 68 kilo of meer of voor pallets die zwaarder zijn dan 1.000 kg.
  
• Als u als variabele optie SATURDAY_DELIVERY opgeeft, krijgt u zowel bezorgopties op zaterdag als reguliere opties voor alle services waarbij bezorging op zaterdag een optie is. Geef geen SATURDAY_DELIVERY voor speciale services op, anders worden er alleen toepasselijke bezorgopties op zaterdag geretourneerd.
• Raadpleeg de documentatie over de API voor servicebeschikbaarheid.

Klantenservice

We staan voor u klaar als u vragen of hulp nodig hebt! Ga naar onze pagina Ondersteuning voor bronnen en voor informatie over hoe u contact met ons kunt opnemen.