Bonnes pratiques en matière d’intégration d’API FedEx

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

Pour une intégration efficace avec les API FedEx, les développeurs doivent suivre ces bonnes pratiques en matière d’intégration :

URI API

• Il y a des URI API distinctes pour le test et pour la production. 
• Les développeurs doivent utiliser les URI de test pour les tests de développement et d’intégration, et l’URI de production pour la production.

Ci-après se trouve la liste des URI API :

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

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

Gestion des informations d’identification

• 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é API ou de clé secrète par e-mail 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 informations d’identification ont été volées ou sont compromises, veuillez recréer la clé secrète immédiatement.
3. Évitez de consigner des informations sensibles telles 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 informations d’identification des clients doivent être stockées dans une chambre forte/un lieu sûr afin de ne pas être compromises.

• 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 en 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 protocole HTTPS pour toute transaction API.

Pratiques en matière de codage

• Pour rester conforme au 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 de Transport Layer Security (TLS).
• N’oubliez pas de définir les bons en-têtes API nécessaires pour chaque demande API. Vous trouverez les informations d’en-tête sur la page de documentation de chaque API. 
• Le « type de contenu » dans HTTP POST doit être « application/json ».
• Veuillez vous référer à l’exemple de code pour commencer avec chaque API. Chaque point de terminaison de l’API est accompagné de plusieurs exemples qui vous aideront à comprendre les éléments, formats et autres détails requis.
• Lorsque les utilisateurs ou les développeurs envoient de nombreuses décimales dans leurs valeurs, cela peut provoquer des erreurs bizarres. Pour le poids et la valeur monétaire/le montant, seules deux décimales explicites sont autorisées. Les dimensions, comme la longueur, la largeur et la hauteur, ne prennent pas en charge les décimales.

Exemple : Poids : 45,26 - Valeur/montant de la devise : 100,52 - Longueur : 10 - Largeur : 25 - Hauteur : 15

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

Exemple : « Lignes de rue » : «»

• N’envoyez que les données nécessaires au traitement de la demande.

Par exemple, pour un envoi au sein des États-Unis, évitez d’envoyer la facture commerciale et les données sur les articles qui ne sont peut-être requises que pour les envois internationaux.

• Lors du développement, déterminez la réaction lorsqu’un élément de réponse non requis, tel qu’un tarif, n’est pas renvoyé. Évaluez la réponse à la transaction pour détecter les éléments manquants avant d’utiliser les données.

Par exemple, il est possible d’expédier un colis si la tarification n’est pas fonctionnelle. Testez la réponse à la transaction pour détecter les éléments manquants avant d’utiliser les données.

• D’une manière générale, il faut éviter de dépendre de l’intégration des API FedEx.
• 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 dans l’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 d’étranglement est fixée à 1400 transactions en 10 secondes. Si cette limite est atteinte dans les premières secondes, le code d’erreur HTTP 429 Trop de requêtes sera renvoyé et les transactions seront limitées jusqu’à ce que 10 secondes se soient écoulées ; les transactions reprendront alors.
  

Par exemple, si 1400 requêtes sont envoyées dans les quatre premières secondes, un code d’erreur HTTP 429 Trop de requêtes - « Nous avons reçu trop de requêtes en peu de temps. Veuillez patienter quelques instants, puis réessayer. » sera renvoyé. Les transactions seront alors limitées pendant les six secondes suivantes, puis reprendront.

• Ne codez pas en dur les règles professionnelles 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 remarque, selon le cas. Les avertissements et les remarques ne sont pas les 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 un devis :
  
  • Tarif pour un serviceType spécifique - Les résultats seront filtrés par 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

  • Boutique des 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 pour 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. 
  
  • Remarque : certains services spéciaux n’ont pas de détails.
• Consultez la documentation sur l’API de 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.
  
  • Remarque : certains services spéciaux n’ont pas de détails.
• Effectuez la fermeture pour FedEx Ground à la fin de la journée d’expédition avant que l’envoi ne soit enlevé.
  
• 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 professionnels.
• 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 finale. 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 professionnels. Un processus doit être mis en place pour traiter les adresses qui ne peuvent pas être validées afin que les commandes puissent toujours ê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 point de dépôt FedEx

• Limitez votre recherche en fournissant des attributs spécifiques (par exemple, le type de lieu, les services offerts, etc.) pour obtenir des options de localisation appropriées et un temps de réponse plus rapide.
• Consultez la documentation sur l’API de recherche de point de dépôt FedEx.
  

Demande d’enlèvement

• 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 enlèvement.
• Les enlèvements anonymes ne sont pas autorisés.
  
• Consultez la documentation sur l’API de demande d’enlèvement.
  

Disponibilité du service

• Pour obtenir des résultats pour plusieurs sociétés d’exploitation comme FedEx Express (FDXE), FedEx Ground (FDXG), FedEx Freight (FXFR) et FedEx Ground® Economy, vous pouvez soit omettre l’élément carrierCodes, soit envoyer des requêtes de disponibilité de service distinctes, car il est impossible de spécifier plusieurs codes de transporteur.
• Veuillez vous assurer que vous détenez une autorisation préalable pour les palettes individuelles de 151 livres (68,5 kg) ou plus et les palettes de plus de 2 200 livres (998 kg).
  
• Si vous indiquez SATURDAY_DELIVERY pour les options variables, vous obtiendrez à la fois les options de livraison le samedi et les options régulières pour tous les services où la livraison le samedi est une option. Ne spécifiez pas SATURDAY_DELIVERY pour les services spéciaux, sinon, seules les options de livraison le samedi applicables seront renvoyées.
• Consultez la documentation sur l’API de disponibilité des services.

Service Clientèle

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