Skip to main content
AccueilBlogGuidesComment obtenir le dernier statut de l’expédition via l’API sans attendre un webhook

Comment obtenir le dernier statut de l’expédition via l’API sans attendre un webhook

17TRACK

Pour obtenir le dernier statut d’expédition disponible sans attendre un webhook, envoyez une requête authentifiée à l’API de consultation des expéditions de votre fournisseur de suivi. Utilisez la réponse pour mettre immédiatement à jour votre application, puis laissez les webhooks activés pour les changements ultérieurs. La distinction importante est qu’une requête récupère généralement les dernières informations de suivi enregistrées par le fournisseur ; elle ne déclenche pas nécessairement une nouvelle vérification auprès du transporteur.

Comment obtenir le dernier statut d’expédition via une API sans attendre

Cette approche est utile lorsqu’un client ouvre une page de commande, qu’un agent du support a besoin d’une mise à jour ou que votre système doit récupérer une notification manquée. Une implémentation fiable combine des requêtes à la demande, des indicateurs clairs de fraîcheur et des protections contre les mises à jour en double ou dans le désordre.

Définir ce que signifie « dernier statut d’expédition »

Avant de choisir un point de terminaison, distinguez trois opérations qui peuvent sembler similaires, mais qui produisent des résultats différents.

OpérationCe qu’elle faitCe qu’elle ne permet pas d’établir
Lire votre propre base de donnéesRenvoie les informations de suivi que votre application détient déjà.Si le fournisseur a reçu une mise à jour plus récente.
Interroger l’API de suiviRécupère les informations disponibles via l’opération de consultation du fournisseur.Si une nouvelle recherche auprès du transporteur a eu lieu pendant cette requête.
Demander une actualisation du suiviDemande une nouvelle vérification en amont, si le fournisseur propose cette opération.Que le transporteur dispose d’un nouveau scan ou que l’actualisation soit terminée de manière synchrone.

Utilisez une requête lorsque vous avez besoin d’une réponse immédiate. N’examinez une opération d’actualisation que lorsque vous souhaitez que le fournisseur tente une nouvelle vérification en amont. Ne supposez pas que l’ajout d’un paramètre destiné à contourner le cache, la répétition d’une requête ou l’envoi d’un en-tête HTTP cache-control obligera le transporteur à fournir de nouvelles informations.

La visibilité d’une expédition comporte plusieurs étapes : le transporteur enregistre un événement, le fournisseur de suivi l’obtient, puis votre application le reçoit ou le récupère. Une requête API directe peut éviter d’attendre la livraison d’une notification, mais elle ne peut pas supprimer les retards antérieurs dans cette chaîne.

Vérifier le contrat de consultation avant d’écrire le code

Le développeur qui intègre le service de suivi est responsable de ce flux de travail. Commencez par la documentation actuelle du fournisseur, et non par un point de terminaison copié dans un ancien exemple d’intégration. Confirmez les détails suivants :

  • Identité de l’expédition : la requête accepte-t-elle un numéro de suivi, un identifiant d’expédition interne ou un numéro de suivi associé à un identifiant de transporteur ?
  • Conditions d’enregistrement : l’expédition doit-elle être enregistrée avant de pouvoir être consultée ?
  • Authentification : quel en-tête ou mécanisme d’authentification est requis ?
  • Signification de la réponse : l’opération renvoie-t-elle des informations enregistrées, lance-t-elle une collecte ou renvoie-t-elle une tâche à vérifier ultérieurement ?
  • Gestion des résultats : une réponse HTTP réussie peut-elle contenir un échec au niveau de l’expédition ou un résultat en attente ?
  • Contraintes d’utilisation : quelles limites de débit, limites de traitement par lot et restrictions propres au compte s’appliquent ?
  • Champs de fraîcheur : quels horodatages représentent les événements du transporteur, les mises à jour du fournisseur et la génération de la réponse ?

Pour une intégration 17TRACK, la Tracking API est le produit pertinent, plutôt qu’une page de suivi grand public ou une interface de suivi de boutique. Utilisez la documentation officielle de l’API pour confirmer l’opération de consultation des informations de suivi, l’authentification, les champs de requête et la structure de réponse adaptés à votre intégration. Traitez les requêtes et la gestion des webhooks comme des chemins applicatifs distincts qui mettent à jour le même enregistrement d’expédition.

Évitez de coder en dur des hypothèses concernant le comportement d’actualisation ou la fréquence des requêtes. Ces détails doivent correspondre à l’opération et aux conditions du service que vous utilisez réellement.

Construire une consultation à la demande via votre backend

Une conception pratique consiste à exposer un point de terminaison authentifié dans votre propre application. Le navigateur demande une mise à jour d’expédition à ce point de terminaison ; votre serveur vérifie les autorisations, décide si une requête auprès du fournisseur est nécessaire et renvoie un résultat normalisé.

Le chemin suivant est un exemple de point de terminaison que vous créeriez dans votre application. Il ne s’agit pas d’un point de terminaison 17TRACK ni d’une spécification de requête du fournisseur.

GET /api/orders/{order_id}/shipment-status

Utilisez l’identifiant de commande pour rechercher l’expédition sur le serveur. Ne permettez pas à un appelant de récupérer l’historique de suivi d’un autre client simplement en remplaçant un numéro de suivi dans une requête. Conservez les identifiants de l’API du fournisseur sur votre backend plutôt que dans le JavaScript du navigateur ou le paquet d’une application mobile.

Flux de requête que vous pouvez mettre en œuvre

  1. Autoriser l’accès. Confirmez que le client ou le membre du personnel est autorisé à consulter la commande.
  2. Identifier l’expédition. Lisez l’identifiant de suivi enregistré et les informations sur le transporteur, le cas échéant.
  3. Vérifier la fraîcheur locale. Si une requête récente réussie existe déjà, réutilisez-la conformément à la politique de fraîcheur de votre application.
  4. Interroger le fournisseur si nécessaire. Utilisez l’opération documentée et un délai d’expiration de requête limité.
  5. Valider le résultat. Vérifiez à la fois le résultat HTTP et le résultat au niveau de l’expédition.
  6. Fusionner les informations. Appliquez les mêmes règles de normalisation et de rapprochement que celles utilisées pour les événements de webhook.
  7. Renvoyer le statut et la fraîcheur. Incluez l’heure du dernier événement et, lorsqu’elle est disponible, l’heure de la dernière vérification réussie auprès du fournisseur.

La politique de fraîcheur locale est une décision d’ingénierie, et non une affirmation sur la fréquence des mises à jour du transporteur. Choisissez-la en fonction des exigences de votre interface, des limites du fournisseur, du volume d’expéditions et de l’utilité observée des requêtes. Un client qui clique à plusieurs reprises sur un bouton de mise à jour ne doit pas créer un flux illimité de requêtes en amont.

Normaliser la réponse sans inventer la fraîcheur

Votre application peut renvoyer un format interne stable même lorsque les structures de réponse des fournisseurs diffèrent. Cet objet illustratif constitue le contrat de votre propre application, et non une charge utile réelle du fournisseur :

{
  "shipment_id": "internal-shipment-id",
  "status": "in_transit",
  "latest_event_at": null,
  "provider_updated_at": null,
  "last_successful_query_at": null,
  "retrieval_state": "success",
  "source": "provider_query"
}

Ne renseignez chaque horodatage que lorsque sa signification est connue. L’heure à laquelle votre serveur a reçu une réponse appartient aux métadonnées de votre requête ; elle ne doit pas être présentée comme l’heure à laquelle le colis a été déplacé. Si le fournisseur ne fournit pas d’horodatage de mise à jour, laissez ce champ absent ou nul plutôt que de lui substituer un autre horodatage.

Dans l’interface client, séparez les messages : « Dernier événement du transporteur » décrit l’activité de l’expédition, tandis que « Suivi vérifié » décrit l’activité de récupération de votre application. Cette distinction empêche qu’un scan inchangé semble avoir été enregistré récemment.

Empêcher les requêtes API et les webhooks de s’écraser mutuellement

Une fois les deux mécanismes actifs, un même événement peut arriver via une requête et un webhook. Ils peuvent également se terminer dans un ordre différent de celui dans lequel ils ont commencé. Une requête lancée en premier peut se terminer après qu’un webhook a déjà fourni des informations plus récentes.

N’utilisez pas une logique où la dernière réponse l’emporte. La charge utile reçue le plus récemment ne correspond pas nécessairement à l’état d’expédition le plus récent.

  • Partagez un seul pipeline de mise à jour. Faites passer les résultats des requêtes et les charges utiles des webhooks par les mêmes fonctions de validation, de normalisation et de persistance.
  • Dédupliquez les événements. Privilégiez un identifiant d’événement documenté. S’il n’en existe aucun, construisez une empreinte soigneusement définie à partir des champs disponibles, tels que l’heure de l’événement, le statut, le lieu et la description.
  • Utilisez des champs d’ordre dont la sémantique est connue. Une révision ou une séquence documentée est plus utile que de supposer que l’heure d’arrivée représente l’ordre des événements.
  • Conservez l’historique. Un événement nouvellement reçu peut combler une lacune historique sans modifier le résumé actuel de l’expédition.
  • Autorisez les corrections. Les statuts ne constituent pas une échelle linéaire universelle. Suivez le comportement de correction documenté au lieu de rejeter définitivement chaque transition apparemment régressive.

Lorsque l’ordre des événements est incertain, conservez la charge utile originale et sa provenance pour investigation. Ne résolvez pas l’ambiguïté en fabriquant un horodatage d’événement ou en supposant que tous les horodatages des transporteurs utilisent le même fuseau horaire.

Traiter différemment les données manquantes et les requêtes échouées

Un résultat vide, un résultat inchangé et une requête échouée ne doivent pas produire le même message pour le client.

La requête réussit, mais le statut n’a pas changé

Conservez le statut d’expédition existant et mettez à jour l’heure de la dernière requête réussie. Ne créez pas de nouvel événement d’expédition simplement parce qu’une autre consultation est terminée. Si le client a besoin de plus de détails, affichez l’historique des événements existant et expliquez qu’aucun événement de suivi plus récent n’a été renvoyé.

L’expédition ne possède pas encore d’informations de suivi

Vérifiez si un enregistrement est requis, si l’identifiant et le transporteur sont corrects et comment le fournisseur représente une collecte en attente. L’absence d’événements ne prouve pas à elle seule que le numéro de suivi est invalide ou que le colis est perdu. Préservez la distinction du fournisseur entre un identifiant inconnu, une expédition enregistrée en attente d’informations et une requête qui n’a pas pu être traitée.

La requête du fournisseur expire ou échoue

Si vous disposez d’un statut valide précédent, renvoyez-le en indiquant explicitement que la dernière vérification n’a pas abouti. Conservez inchangée l’heure de la requête réussie précédente. Une erreur réseau n’est pas une exception de livraison et ne doit pas modifier le statut commercial du colis.

Utilisez des tentatives limitées avec temporisation progressive et variation aléatoire pour les défaillances transitoires appropriées. Ne répétez pas les tentatives avec des identifiants invalides ou des requêtes mal formées. Lorsqu’une réponse fournit Retry-After, interprétez-la conformément au contrat du fournisseur et à la sémantique HTTP. La spécification HTTP autorise l’expression de cette valeur sous forme de délai en secondes ou de date HTTP.

Plusieurs requêtes arrivent pour la même expédition

Regroupez les consultations simultanées afin qu’elles puissent partager une seule requête en amont. Appliquez des limites par compte et par expédition, et empêchez une nouvelle tentative automatique de se multiplier à travers plusieurs couches de l’application. Lorsque le traitement par lot est pris en charge, examinez le résultat de chaque expédition plutôt que de considérer l’ensemble du lot comme réussi parce que la requête HTTP est terminée.

Utiliser l’interrogation comme solution de secours contrôlée

Sans webhooks, une interrogation planifiée peut maintenir votre base de données à jour, mais elle nécessite une politique opérationnelle explicite. Décidez quelles expéditions restent éligibles, comment les échecs influencent la planification et à quel moment l’interrogation régulière s’arrête.

Pour la plupart des intégrations, une conception hybride constitue un point de départ pertinent : les webhooks gèrent les changements en arrière-plan, les requêtes à la demande répondent aux demandes interactives et les tâches de rapprochement vérifient les enregistrements nécessitant une intervention. Il s’agit d’une recommandation architecturale, et non d’une garantie de minimisation des coûts pour chaque compte.

  • Donnez la priorité aux expéditions actives et aux enregistrements présentant des erreurs de récupération non résolues.
  • Évitez d’interroger toutes les expéditions historiques à chaque exécution planifiée.
  • Définissez le traitement des expéditions terminées, y compris toute période de correction requise par votre entreprise.
  • Suivez la fréquence à laquelle les requêtes trouvent de véritables nouvelles informations.
  • Examinez les problèmes de livraison des webhooks au lieu de les masquer par des interrogations de plus en plus fréquentes.

Surveillez la latence des requêtes adressées au fournisseur, les requêtes infructueuses, les réponses de limitation de débit et les différences entre les données interrogées et les enregistrements alimentés par webhook. Surveillez séparément l’ancienneté du dernier événement du transporteur. Des réponses API réussies peuvent coexister avec des informations de suivi qui n’ont pas changé.

Tester le flux de travail avant la mise en production

Une requête réussie n’est que le premier test. Vérifiez les situations qui pourraient autrement créer des mises à jour de statut trompeuses :

  • Un webhook arrive alors qu’une requête à la demande est encore en cours.
  • Deux clients ou sessions d’employés demandent simultanément la même expédition.
  • Le fournisseur renvoie une réussite HTTP, mais signale une erreur au niveau de l’expédition.
  • Une requête échoue alors que votre application détient déjà des informations de suivi valides.
  • Un événement ne contient pas de fuseau horaire ou comporte un code de statut inhabituel.
  • Une correction du transporteur modifie un résultat précédemment affiché.
  • Un utilisateur tente d’accéder à une expédition appartenant à un autre compte.

Votre critère de mise en production doit être que l’application renvoie les meilleures informations d’expédition connues, explique précisément leur fraîcheur et ne les corrompe pas lorsque les requêtes échouent ou arrivent dans le désordre.

FAQ

La consultation de l’API oblige-t-elle le transporteur à scanner ou à mettre à jour un colis ?

Non. La récupération des informations de suivi ne peut pas provoquer un scan physique. La question de savoir si une requête déclenche une recherche en amont dépend de l’opération documentée. Même une actualisation prise en charge peut renvoyer des informations inchangées si le transporteur ne dispose d’aucun événement plus récent.

Puis-je utiliser des requêtes API sans configurer de webhooks ?

Si le fournisseur prend en charge le flux de consultation requis, vous pouvez créer une intégration basée sur des requêtes à la demande ou une interrogation planifiée. Confirmez d’abord les exigences d’enregistrement et de consultation. Votre application devra alors décider quand effectuer les vérifications, contrôler le volume des requêtes et détecter les changements.

À quelle fréquence dois-je interroger le statut d’une expédition ?

Il n’existe pas d’intervalle universel. Choisissez une planification adaptée aux limites de votre fournisseur, au volume de vos expéditions et à la valeur commerciale d’une détection plus rapide des mises à jour. Mesurez la fréquence à laquelle l’interrogation renvoie de nouveaux événements, puis ajustez-la au lieu de supposer que des requêtes fréquentes produisent des données plus récentes du transporteur.

Pourquoi l’API renvoie-t-elle des informations que j’ai déjà reçues via un webhook ?

Les deux chemins peuvent exposer le même enregistrement d’expédition sous-jacent. Un webhook transmet une notification, tandis qu’une requête récupère des informations à la demande. Recevoir le même événement par les deux voies n’est pas nécessairement une erreur ; votre application doit le dédupliquer.

Le bouton de mise à jour doit-il indiquer « Actualiser le suivi » ?

Uniquement si cette formulation décrit précisément l’opération. Si le bouton récupère des données enregistrées par le fournisseur, « Vérifier les mises à jour » est plus clair. Affichez séparément le dernier événement du transporteur et l’heure à laquelle votre application a effectué sa dernière vérification réussie.

Sources