Meilleures pratiques d'intégration des API FedEx

Voici un guide de référence rapide destiné à aider les consommateurs d’API à comprendre comment améliorer l’expérience d’intégration avec FedEx et de garantir la qualité de la solution d’intégration en matière de conception, de rapidité et de sécurité.

Pour une intégration efficace avec les API FedEx, les développeurs doivent suivre les meilleures pratiques d’intégration suivantes :

URI d'API

• Il existe des URI d'API distinctes pour l'environnement de test et celui de production. 
• Les développeurs doivent utiliser les URI de test pour les tests de développement et d'intégration, et les URI de production pour la production.

Voici les URI d'API :

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

Production : https://apis.fedex.com/

Gestion des identifiants

• Clé API et clé secrète

• Votre clé API et votre clé secrète permettent d’identifier votre application et doivent être utilisées dans la demande de jeton OAuth.

1. Votre clé API et votre clé secrète doivent être traitées de manière très sécurisée. Ne distribuez pas de clés API ou de clés secrètes par courriel ou code distribué, y compris le JavaScript côté client.
2. Votre application sera compromise si votre clé API ou votre clé secrète est volée. Si vous pensez que vos identifiants ont été volés ou sont compromis, veuillez recréer la clé secrète immédiatement.
3. Évitez de consigner des renseignements sensibles tels que la clé secrète.

• Ne codez pas en dur la clé API et la clé secrète dans votre code.
• Votre application doit être capable de mettre à jour dynamiquement la clé API et la clé secrète.
• Les identifiants des clients doivent être stockés dans une chambre forte/un lieu sûr afin de ne pas être compromis.

• Jeton OAuth

• Le jeton d’accès doit être stocké sur le serveur d’application Web uniquement et ne doit pas être exposé au navigateur.
• Ne codez pas en dur le jeton dans vos applications.
• Sécurisez les jetons d’accès pour éviter de les compromettre.
• Évitez de passer plusieurs appels à l’API du jeton OAuth pour obtenir un nouveau jeton d’accès. Il est recommandé de mettre le jeton d’accès sous cache jusqu’à ce que le code d’erreur HTTP 401 soit observé. Régénérez le jeton OAuth à ce moment-là.
• N’exposez pas le jeton à l’utilisateur final ou à l’application.
• Utilisez le HTTPS pour toute transaction API.

Pratiques de codage

• Pour respecter le protocole de communication de cryptage des données le plus récent et le plus sûr, il est recommandé d’utiliser la version 1.2 ou supérieure du protocole TLS.
• N’oubliez pas de définir les bons en-têtes API nécessaires pour chaque demande API. Vous trouverez les renseignements sur les en-têtes sous chaque page de documentation sur les API. 
• Le « type de contenu » dans HTTP POST doit être « application/json ».
• Veuillez vous référer à l’exemple de code pour démarrer avec chaque API. Chaque point de terminaison d’API est accompagné de plusieurs exemples qui vous aideront à comprendre les éléments, les formats et d'autres détails requis.
• Lorsque les utilisateurs ou les développeurs envoient de nombreuses décimales dans leurs valeurs, cela peut provoquer des erreurs inhabituelles. Seules deux décimales explicites sont autorisées pour le poids et la valeur monétaire/le montant. Les dimensions, comme la longueur, la largeur et la hauteur, ne prennent pas en charge les décimales.

Exemple : poids : 45,26; valeur monétaire/montant : 100,52; longueur : 10; largeur : 25; hauteur : 15.

• Évitez d’envoyer des éléments vides.

Exemple : « lignes de rues » : «»

• Envoyez uniquement les données nécessaires au traitement de la demande.

Par exemple, pour un envoi à l'intérieur des États-Unis, évitez d’envoyer la facture commerciale et les données sur les marchandises qui pourraient être requises uniquement pour les envois internationaux.

• Lors du développement, déterminez la réaction lorsqu’un élément de réponse non requise, tel qu’un tarif, n’est pas renvoyé. Évaluez la réponse de la transaction lorsqu'il manque des éléments avant d’utiliser les données.

Par exemple, est-il possible d’expédier un colis si la tarification n’est pas fonctionnelle? Testez la réponse de la transaction lorsqu'il manque des éléments avant d’utiliser les données.

• D’une manière générale, il faut éviter de dépendre fortement de l’intégration des API FedEx, s’il y a lieu.
• Afin de réduire le temps de latence et d’obtenir des résultats précis, il convient d’utiliser ce qui suit :
  
  • Filtrage – utilisez cette fonction pour affiner la recherche avec les paramètres que vous recherchez.
  • Tri – utilisez cette fonction pour trier les résultats selon un certain paramètre, en ordre croissant ou décroissant.
• Vérifiez que les champs obligatoires, tels que le code postal du destinataire et le poids du colis, comportent des données avant d’envoyer la transaction. Vérifiez que les données sont appropriées pour le champ en question. Cela permettra de réduire les erreurs de transaction.
  

Par exemple, pour les codes postaux américains, vérifiez que le champ est entièrement numérique et se présente sous la forme d’un code postal à 5 chiffres ou au format ZIP+4.

• Pour éviter tout impact négatif sur la disponibilité et la fiabilité du système FedEx :
  
  • N’effectuez pas de tests de performance dans l’environnement de test ou de production.
  • Disposez d’une logique de codage pour éviter que la même transaction échoue à plusieurs reprises.
• La limite des demandes est fixée à 750 transactions en 10 secondes. Si cette limite est atteinte dans les premières secondes, le code d’erreur HTTP 429 Trop de demandes sera renvoyé et les transactions seront limitées jusqu’à ce que 10 secondes se soient écoulées; les transactions reprendront alors.
  

Par exemple, si nous recevons 750 demandes dans les quatre premières secondes, un code d’erreur HTTP 429 Trop de demandes - «Nous avons reçu trop de demandes dans une courte durée. Veuillez attendre un moment, puis réessayer.» sera renvoyé et les transactions seront limitées pendant les six secondes suivantes, puis reprendront à nouveau.

• Ne codez pas en dur les règles métier comme les types de services, les types de colis, les limites de poids, etc., pour les envois, car elles sont susceptibles de changer.

Gestion des erreurs

Chaque réponse API contiendra un code de statut HTTP et une charge utile de réponse. Certaines réponses seront accompagnées d’une erreur, d’un avertissement ou d’une note, selon le cas. Les avertissements et les notes ne sont pas des indications d’une défaillance; cependant, le message d’erreur ou d’avertissement doit être consigné et examiné. Une bonne gestion des erreurs garantira le bon déroulement de votre intégration avec FedEx et pourrait contribuer à éviter les ruptures.

Codes de statut HTTP

Tarif

• Il y a deux façons d’obtenir une estimation de tarif :
  
  • Tarif pour un serviceType précis – les résultats seront filtrés selon la valeur de serviceType indiquée. Cela permettra de réduire la taille de la réponse et le temps de réponse de la transaction.
    

    Exemple : STANDARD_OVERNIGHT

  • Comparaison de tarifs – si aucun serviceType n’est indiqué, tous les services applicables et les tarifs correspondants seront retournés.
• Utilisez l’API de disponibilité des services pour connaître les services, les options de colis et les services spéciaux disponibles pour une paire origine-destination donnée, et transmettez le serviceType et l’option de colis dans la demande de tarif.
  

  Par exemple, STANDARD_OVERNIGHT (entre autres) n’est pas disponible entre tous les codes postaux.

• Pour qu’un service spécial soit appliqué à un envoi, le type de service spécial et ses détails doivent être inclus. 
  
  • Note : Certains services spéciaux ne s’accompagnent pas de détails.
• Consultez la documentation sur l’API des tarifs.

Expédier

• Utilisez l’API de disponibilité des services pour connaître les services disponibles pour une paire origine-destination donnée et transmettez le serviceType et l’option de colis dans la demande d’expédition.
• Pour qu’un service spécial soit appliqué à un envoi, le type de service spécial et ses détails doivent être inclus.
  
  • Note : Certains services spéciaux ne s’accompagnent pas de détails.
• Effectuez la fermeture de FedEx Ground à la fin de la journée d’expédition, avant que l’envoi soit ramassé.
  
• Consultez la documentation sur l’API d'expédition.
  

Suivi

• Limitez à 30 le nombre de numéros de suivi dans une demande de suivi unique. Cela permettra de réduire la taille de la réponse et le temps de réponse de la transaction.
• Limitez le nombre de fois qu’un colis est suivi au strict nécessaire pour les besoins de l'entreprise.
• Pour le suivi par lot, retirez du lot tous les colis qui ont renvoyé un statut de suivi « livré ».
• Consultez la documentation sur l’API de suivi.

Validation de l'adresse

• FedEx fournit une validation de l’adresse à titre de suggestion et non de décision définitive. L’utilisateur final doit déterminer de manière définitive si une adresse est utilisable à partir des données fournies et de ses besoins commerciaux. Un processus doit être mis en place pour traiter les adresses qui ne peuvent pas être validées afin que les commandes puissent continuer d'être traitées.
• Pour garantir une meilleure expérience d’expédition, ne faites pas dépendre le processus d’expédition de services facultatifs tels que la validation de l’adresse.

Par exemple, si l’API de validation de l’adresse n’est pas disponible au moment de la saisie de la commande ou de l’expédition, un dispositif de secours doit être mis en place pour terminer l’envoi.

• Consultez la documentation sur l’API de validation de l’adresse.
  

Recherche de centres FedEx

• Limitez votre recherche en fournissant des attributs précis (par exemple, le type d'emplacement, les services offerts, etc.) pour obtenir des options d'emplacements appropriés et un temps de réponse plus rapide.
• Consultez la documentation sur l’API de recherche des centres FedEx.
  

Demande de ramassage

• Ne saisissez pas une heure de disponibilité passée, une date passée ou une date trop éloignée dans le futur pour planifier un ramassage.
• Les ramassages anonymes ne sont pas autorisés.
  
• Consultez la documentation sur l’API de demande de ramassage.
  

Disponibilité du service

• Pour obtenir des résultats pour plusieurs sociétés en exploitation comme FedEx Express (FDXE), FedEx Ground (FDXG), FedEx Freight (FXFR) et FedEx Ground^MD Economy, vous pouvez soit omettre l’élément carrierCodes, soit envoyer des demandes de disponibilité de service distinctes, car il est impossible d'indiquer plusieurs codes de transporteur.
• Veuillez vous assurer d'obtenir une autorisation pour les palettes individuelles de 68,5 kg (151 lb) ou plus et les palettes de plus de 998 kg (2 200 lb).
  
• Si vous indiquez SATURDAY_DELIVERY pour les options variables, vous obtiendrez à la fois les options de livraison le samedi et les options courantes pour tous les services où la livraison le samedi est une option. N'indiquez pas SATURDAY_DELIVERY pour les services spéciaux, car dans ce cas, seules les options de livraison le samedi applicables seront retournées.
• Consultez la documentation sur l’API de disponibilité des services.

Soutien à la clientèle

Nous sommes à votre disposition si vous avez des questions ou avez besoin d’aide! Veuillez accéder à notre page Soutien pour obtenir des ressources et des renseignements sur les façons de communiquer avec nous.