Comment utiliser l’API de suivi UPS : guide de configuration étape par étape

Pour utiliser l’API de suivi UPS, créez un compte UPS Developer, enregistrez une application, obtenez des identifiants OAuth 2.0, demandez un jeton d’accès et envoyez des requêtes de suivi authentifiées avec un numéro de suivi UPS valide. Les libellés exacts du portail, les étapes d’approbation et les exigences de l’API peuvent changer. Vérifiez donc les instructions actuelles dans le portail officiel UPS Developer avant de mettre en production une intégration.

Ce guide s’adresse aux développeurs et aux équipes chargées des opérations e-commerce qui doivent afficher le statut des expéditions dans une boutique en ligne, un système de gestion des commandes, un flux de travail d’entrepôt, un outil de service client ou un tableau de bord interne. Il se concentre sur la séquence d’intégration, les décisions qui influent sur la fiabilité et les vérifications qui permettent d’éviter les échecs de suivi courants.

Fonctionnement de l’API de suivi UPS

Une intégration API permet aux logiciels de demander des informations d’expédition à UPS, au lieu d’obliger un employé ou un client à ouvrir manuellement la page de suivi du transporteur. Votre application peut utiliser la réponse pour afficher le dernier statut connu, identifier les événements de livraison, faciliter les recherches du service client ou déclencher un flux de travail interne.

L’API n’est pas équivalente à une page de suivi. Une page de suivi est conçue pour être lue par une personne. Une réponse API est constituée de données structurées que les logiciels doivent analyser, stocker et présenter. Votre système reste responsable de l’authentification, de la gestion des erreurs, de l’interrogation périodique ou de la collecte des événements, de la conservation des données, de la conception de l’interface utilisateur et des règles métier liées aux événements de livraison.

Avant de commencer

Préparez les éléments suivants avant d’ouvrir le portail développeur :

• Un compte UPS Developer ou le type de compte requis par le processus actuel d’intégration UPS.
• Une application enregistrée et les identifiants émis pour cette application.
• Un numéro de suivi de test ou une autre méthode de test approuvée. Ne commencez pas avec des données client réelles si la documentation UPS fournit un environnement ou une procédure de test distincte.
• Une décision claire concernant le système qui gère les enregistrements d’expédition, les événements de suivi et les messages de statut destinés aux clients.
• Un emplacement sécurisé pour stocker les identifiants client et les jetons d’accès. Ne placez jamais de secrets dans du code exécuté dans le navigateur, des dépôts publics, des captures d’écran ou des applications mobiles que les utilisateurs peuvent inspecter.

Vous devez également déterminer si votre application a uniquement besoin du suivi ou d’une intégration UPS plus large. Le suivi, la tarification, l’expédition, la validation des adresses et les services de documents peuvent avoir des produits, des autorisations, des formats de requête et des exigences opérationnelles différents.

Étape 1 : ouvrir le portail UPS Developer

Commencez sur le portail officiel UPS Developer. Consultez le catalogue actuel des API, les instructions d’authentification, les exigences d’intégration, les conditions et les informations relatives aux environnements. Recherchez spécifiquement la documentation de l’API de suivi au lieu de supposer que les instructions d’un autre service UPS s’appliquent également au suivi.

Le portail constitue la source appropriée pour connaître les champs de requête actuels, les portées d’autorisation, les définitions des réponses, les limites de débit, les codes d’erreur et les détails des environnements. Ces informations peuvent changer, et un exemple de code tiers peut utiliser une ancienne interface UPS ou une méthode d’authentification obsolète.

Étape 2 : enregistrer une application

Créez une application dans le portail développeur et sélectionnez les API UPS dont l’application a réellement besoin. Pour un projet limité au suivi, demandez uniquement la fonctionnalité de suivi, sauf si votre flux de travail nécessite des services supplémentaires. Limiter les autorisations réduit la complexité de la configuration et facilite le dépannage ultérieur.

Enregistrez l’identifiant et le secret de l’application dans un gestionnaire de secrets côté serveur ou dans un système protégé de variables d’environnement. Traitez le secret comme un mot de passe. S’il est exposé, renouvelez-le en suivant la procédure fournie par UPS et examinez les journaux afin de détecter toute utilisation non autorisée.

Si le portail demande des informations relatives au compte, à la facturation, à l’entreprise ou à l’application, fournissez des données exactes. N’inventez pas un cas d’utilisation en production et n’utilisez pas les informations de compte d’une autre personne simplement pour terminer un test. L’accès à un service peut dépendre de la configuration du compte et du processus d’approbation UPS en vigueur.

Étape 3 : mettre en œuvre l’authentification OAuth 2.0

La documentation actuelle destinée aux développeurs UPS utilise une authentification fondée sur OAuth pour ses API. Votre serveur échange normalement les identifiants de l’application selon le flux de jeton documenté et reçoit un jeton d’accès. Il inclut ensuite ce jeton dans l’en-tête d’autorisation d’une requête API.

Séparez l’authentification de la logique de suivi. Une conception pratique comprend un composant qui obtient et met en cache un jeton valide et un autre qui appelle le point de terminaison de suivi. Le composant de gestion des jetons doit :

• Envoyer les identifiants uniquement au point de terminaison d’autorisation UPS documenté.
• Utiliser le type de contenu et les paramètres d’octroi indiqués dans la documentation UPS actuelle.
• Stocker temporairement le jeton et le réutiliser jusqu’à son expiration, plutôt que de demander un nouveau jeton pour chaque numéro de suivi.
• Actualiser ou récupérer à nouveau le jeton lorsque la condition d’expiration documentée se produit.
• Masquer les identifiants et les jetons dans les journaux de l’application, les rapports d’erreur et les tickets d’assistance.

Ne copiez pas un jeton depuis une session de navigateur dans une intégration permanente. Un service backend constitue généralement un emplacement plus sûr pour gérer les identifiants, car il maintient les secrets à l’écart du code client public.

Étape 4 : créer la requête de suivi

Utilisez le format de requête présenté dans la référence officielle de l’API de suivi. Une requête type comprend un numéro de suivi dans le chemin ou les paramètres de la requête, un jeton d’accès dans l’en-tête d’autorisation et les en-têtes requis par l’API UPS. Ne supposez pas qu’un numéro de suivi est la seule valeur requise : la référence actuelle peut spécifier une version, une transaction, un type de contenu ou des en-têtes de corrélation.

Un modèle de requête simplifié se présente comme suit :

GET [UPS tracking endpoint]/[tracking-number]
Authorization: Bearer [access-token]
Accept: application/json

Il s’agit d’un exemple structurel et non d’un point de terminaison à copier-coller. Utilisez le point de terminaison, la version, les en-têtes et les noms de paramètres publiés dans la documentation UPS pour votre application. Normalisez le numéro de suivi conformément à vos propres règles de données de commande, mais ne supprimez aucun caractère sans confirmation de la documentation du transporteur indiquant que cette opération est sûre.

Étape 5 : intégrer les événements à votre modèle de données

Les réponses des transporteurs contiennent souvent davantage d’informations qu’un simple libellé de statut. Avant de programmer la page destinée aux clients, mappez la réponse vers un modèle interne comprenant, par exemple, l’identifiant de l’expédition, le transporteur, le dernier statut, le code de l’événement, sa description, son horodatage, le lieu, les informations de livraison estimée et l’horodatage de livraison lorsqu’il est disponible.

Conservez la réponse originale du transporteur lorsque vos règles de conservation et de confidentialité vous y autorisent. Une réponse brute peut aider à diagnostiquer une erreur de mappage ou à expliquer pourquoi votre statut normalisé diffère de la formulation du transporteur. Évitez toutefois d’afficher des codes d’événement techniques aux clients sans explication compréhensible.

Ne considérez pas chaque statut comme une issue finale de livraison. Par exemple, un événement « en transit », une exception, une tentative de livraison et un événement « livré » ne doivent pas être regroupés dans le même message client. Créez des mappages explicites et définissez le comportement à adopter lorsque UPS ajoute une valeur d’événement que votre code ne reconnaît pas.

Étape 6 : ajouter des tentatives, une validation et une surveillance

Une intégration de production nécessite davantage qu’une requête réussie dans une console de développement. Ajoutez des validations et des mesures de protection opérationnelles :

• Validation des entrées : rejetez les numéros de suivi vides, mal formés ou manifestement incomplets avant d’envoyer les requêtes.
• Délais d’attente : empêchez une réponse lente du transporteur de bloquer toute une procédure de paiement, d’assistance ou d’entrepôt.
• Règles de nouvelle tentative : relancez prudemment les échecs temporaires du réseau ou du service, avec temporisation progressive. Ne relancez pas à répétition les erreurs d’authentification ou les numéros de suivi invalides.
• Respect des limites : suivez les limites et les règles d’utilisation indiquées dans la documentation UPS. Mettez en cache les résultats récents lorsque votre processus métier le permet.
• États inconnus : conservez un événement non reconnu pour examen au lieu de le qualifier à tort de livré ou de perdu.
• Observabilité : enregistrez la durée des requêtes, la catégorie de réponse et les informations de corrélation sans journaliser de secrets ni de données personnelles inutiles.

Un système de suivi doit également définir la fréquence d’actualisation d’une expédition. Une interrogation trop agressive peut créer une charge évitable et ne pas fournir de nouvelles informations. Une interrogation trop rare peut donner l’impression qu’une page destinée aux clients est obsolète. Choisissez un intervalle en fonction du volume d’expéditions, de l’urgence opérationnelle, des règles du transporteur et de la fraîcheur réellement nécessaire à vos utilisateurs.

Étape 7 : tester avec des scénarios réalistes

Ne testez pas uniquement une expédition livrée avec succès. Incluez un numéro de suivi inconnu, une expédition en transit, une exception, une expédition comportant plusieurs événements, un jeton expiré, un délai d’attente, un échec d’autorisation et une réponse contenant des champs inattendus pour votre analyseur. Si UPS fournit un environnement ou des identifiants de test distincts, suivez d’abord cette procédure.

Vérifiez l’ensemble du parcours, de la requête à l’interface utilisateur. Confirmez que la bonne commande reçoit la bonne expédition, que les horodatages sont affichés dans le fuseau horaire prévu, que les événements en double ne créent pas de messages clients en double et qu’une panne du transporteur ne remplace pas un statut auparavant valide par un texte trompeur.

Quand une API de suivi multitransporteurs est-elle plus adaptée ?

Une intégration directe avec UPS peut être appropriée lorsque votre activité expédie principalement avec UPS et nécessite un contrôle étroit du flux de travail du transporteur. Elle devient moins pratique lorsque les commandes peuvent passer par plusieurs transporteurs, places de marché, opérateurs postaux ou sociétés de livraison régionales. Dans ce cas, des identifiants, formats de réponse, vocabulaires de statuts et règles de nouvelle tentative distincts peuvent accroître les tâches de maintenance.

Un service multitransporteurs tel que 17TRACK Tracking API peut offrir un modèle d’intégration différent aux applications qui doivent assurer le suivi auprès de plusieurs transporteurs. Sa documentation pour les développeurs doit être consultée directement pour connaître les transporteurs pris en charge, les formats de requête, l’authentification, les conditions d’utilisation et les fonctionnalités disponibles. Cela ne le rend pas automatiquement meilleur qu’une connexion directe à UPS : le choix approprié dépend de la combinaison de transporteurs, des exigences en matière de données, du niveau de contrôle de l’intégration et des contraintes commerciales ou de conformité.

Pour une recherche destinée aux consommateurs plutôt que pour une intégration développeur, la page de suivi de 17TRACK peut être plus appropriée que la création d’une connexion API. Pour une boutique en ligne qui a besoin de mises à jour après achat aux couleurs de sa marque, examinez séparément l’intégration pertinente de la plateforme au lieu d’ajouter un travail d’API dont la boutique n’a pas besoin.

Erreurs courantes d’implémentation

• Utiliser d’anciens exemples : un exemple de code peut faire référence à une version retirée, à une ancienne méthode d’authentification ou à un autre service UPS.
• Placer des secrets dans le code frontend : tout ce qui est envoyé à un navigateur doit être considéré comme inspectable.
• Supposer qu’un résultat vide signifie l’absence d’expédition : vérifiez le numéro de suivi, les autorisations du compte, l’environnement et le message de réponse avant de tirer une conclusion métier.
• Mapper uniquement le texte : les descriptions de statut peuvent varier. Utilisez les codes documentés et conservez les valeurs inconnues pour examen.
• Ignorer les exigences liées au compte et à l’utilisation : le code technique peut être correct alors que l’application n’est pas configurée pour le service demandé.
• Actualiser sans règle métier : des interrogations inutiles peuvent accroître les coûts, la charge et le bruit opérationnel sans améliorer l’expérience client.

Liste de contrôle pratique avant la mise en production

1. Confirmez que l’application utilise la documentation UPS actuelle et l’environnement approuvé.
2. Vérifiez que les identifiants sont stockés côté serveur et peuvent être renouvelés.
3. Testez les échecs d’authentification, les erreurs du transporteur, les entrées mal formées et les délais d’attente.
4. Comparez les statuts normalisés avec la réponse originale pour des expéditions représentatives.
5. Définissez une politique d’actualisation et surveillez le volume des requêtes.
6. Définissez les responsabilités concernant les événements non identifiés, les mises à jour tardives et les demandes d’assistance des clients.
7. Documentez l’intégration afin qu’un autre développeur puisse mettre à jour les identifiants, les versions des points de terminaison et les mappages de statuts en toute sécurité.

FAQ

Ai-je besoin d’un compte UPS pour utiliser l’API de suivi ?

Consultez les exigences actuelles d’intégration et d’accès UPS dans le portail Developer. L’accès à l’API peut dépendre de l’enregistrement de l’application, des identifiants, de la configuration du compte et du service demandé. Ne supposez pas qu’une connexion à la page de suivi publique est interchangeable avec un accès à l’API développeur.

L’API de suivi UPS est-elle gratuite ?

Ne supposez pas que l’accès à l’API est dépourvu de conditions commerciales ou d’utilisation. UPS publie les informations actuelles relatives aux services et aux comptes par ses canaux officiels, et certaines exigences peuvent dépendre du produit, du compte ou de l’accord. Confirmez directement les conditions applicables avant de planifier un budget de production.

Puis-je appeler directement l’API UPS depuis JavaScript dans un navigateur ?

Un appel depuis un navigateur peut exposer les identifiants de l’application et créer des problèmes liés aux requêtes cross-origin, à la sécurité et au contrôle de l’utilisation. Une intégration côté serveur constitue généralement le modèle le plus sûr pour stocker les secrets, obtenir les jetons, appliquer les règles de nouvelle tentative et limiter l’accès aux données d’expédition.

À quelle fréquence mon application doit-elle demander les mises à jour de suivi ?

Utilisez une politique d’actualisation fondée sur les limites documentées du transporteur, le volume d’expéditions, l’urgence opérationnelle et le niveau de fraîcheur requis par vos utilisateurs. Mettez en cache les résultats récents lorsque cela est approprié, utilisez une temporisation progressive après les échecs temporaires et n’utilisez pas des interrogations répétées comme substitut à une fonctionnalité documentée d’événement ou de notification.

Dois-je utiliser une intégration directe avec UPS ou une API multitransporteurs ?

Une intégration directe avec UPS peut convenir à un flux de travail principalement axé sur UPS et nécessitant un contrôle spécifique du transporteur. Une API multitransporteurs peut réduire le nombre d’intégrations lorsque vos expéditions utilisent plusieurs transporteurs. Comparez les transporteurs pris en charge, l’authentification, les champs de données, les exigences de fiabilité, les conditions d’utilisation et l’effort d’implémentation avant de choisir.

Sources

• UPS Developer Portal — catalogue officiel des API, accès aux applications, authentification et documentation pour les développeurs.
• UPS Technology Integration — informations officielles sur l’intégration de la technologie UPS aux systèmes d’entreprise.
• 17TRACK Tracking API — point d’entrée officiel du produit et des développeurs pour le suivi multitransporteurs.
• 17TRACK API Documentation — documentation officielle de l’API concernant l’authentification, les requêtes et le traitement des réponses.