Skip to main content
AccueilBlogGuides6 vérifications pour vérifier les derniers événements de suivi du transporteur synchronisés via votre API

6 vérifications pour vérifier les derniers événements de suivi du transporteur synchronisés via votre API

17TRACK

Pour vérifier que votre API a synchronisé les derniers événements de suivi du transporteur, vérifiez l’identité de l’expédition, les horodatages des événements, les détails des événements, l’itinéraire de livraison, l’ordre des événements et leur fraîcheur par rapport à une vue de suivi indépendante. Une réponse API réussie ou un accusé de réception du webhook ne confirme qu’une seule partie de cette chaîne ; cela ne prouve pas, à lui seul, que votre application dispose du dernier événement du transporteur.

6 vérifications pour confirmer la synchronisation des derniers événements de suivi du transporteur

Ce guide s’adresse aux développeurs et aux équipes opérationnelles responsables de l’intégration des données de suivi dans un système de gestion des commandes, une page destinée aux clients, un outil d’assistance ou un processus d’alerte. L’objectif est de déterminer où un événement a disparu ou a été modifié, puis de décider s’il faut relancer le traitement, corriger une correspondance ou attendre de nouvelles informations du transporteur.

Avant de commencer : définissez ce que signifie « dernier »

Gardez séparés les trois moments suivants : celui où le transporteur indique qu’un événement s’est produit, celui où votre fournisseur de suivi l’a reçu ou exposé, et celui où votre application l’a enregistré. Ces moments peuvent différer. Un transporteur peut publier un scan après l’événement physique, tandis que votre intégration peut le traiter encore plus tard. L’événement le plus récent selon l’heure de survenue n’est donc pas nécessairement l’enregistrement reçu le plus récemment.

Choisissez un point de comparaison avant de commencer l’analyse. Idéalement, utilisez la page de suivi du transporteur ou un autre enregistrement autorisé fourni par le transporteur pour la même expédition. Si cela n’est pas possible, comparez votre application avec la réponse API actuelle du fournisseur de suivi. Cette comparaison plus restreinte peut établir si votre application correspond au fournisseur ; elle ne peut pas établir que le fournisseur possède déjà tous les scans du transporteur. Notez le moment où vous avez effectué la comparaison afin qu’une mise à jour ultérieure ne rende pas incohérent un résultat antérieur.

1. Confirmez que les deux systèmes concernent la même expédition

Commencez par le numéro de suivi, le transporteur et tout identifiant de compte ou d’expédition utilisé par votre intégration. Les seuls numéros de suivi peuvent être insuffisants pour le dépannage : un numéro peut contenir une faute de frappe, être associé au mauvais transporteur ou être réutilisé dans un enregistrement interne après modification d’une commande. Un numéro de commande et un numéro de suivi ont également des fonctions différentes. Une commande peut comporter plusieurs colis ; vérifier le dernier statut de la commande peut donc masquer un colis obsolète.

  • Retrouvez le numéro de suivi exact et le transporteur transmis à l’API de suivi.
  • Confirmez quel enregistrement interne d’expédition ou de colis a reçu la réponse.
  • Vérifiez si l’expédition a été remplacée, divisée, annulée ou réassociée après son enregistrement.
  • Comparez le transporteur et le numéro affichés dans l’enregistrement source avec ceux affichés dans votre application.

Si les identifiants ne correspondent pas, cessez d’attribuer la différence à un retard de synchronisation. Corrigez d’abord l’association, puis répétez la comparaison des événements. Stockez suffisamment d’identifiants dans les journaux de diagnostic pour retracer une expédition sans y inscrire d’identifiants de compte sensibles.

2. Comparez les heures des événements sans leur faire perdre leur signification

Pour chaque candidat au dernier événement, capturez l’heure de survenue indiquée par le transporteur, son fuseau horaire ou son décalage lorsqu’il est fourni, ainsi que les heures de réception et d’enregistrement dans votre application. Convertissez les horodatages selon une base temporelle commune pour la comparaison, mais conservez la valeur d’origine. RFC 3339 définit un format d’horodatage Internet avec des informations explicites sur le décalage ; c’est une référence utile lors de la conception de vos propres champs d’horodatage. Cela ne garantit pas qu’un transporteur ou un fournisseur fournisse un fuseau horaire pour chaque événement.

Un affichage limité à l’heure, un fuseau local supposé ou un analyseur qui supprime silencieusement un décalage peut faire passer un événement à un autre jour calendaire ou le placer dans le mauvais ordre. Lorsque la source fournit une heure locale ambiguë, indiquez que la comparaison est incertaine plutôt que d’inventer un instant UTC précis. Distinguez également l’heure de survenue d’un événement de l’heure de la réponse API : une réponse récupérée maintenant peut légitimement contenir un événement survenu plus tôt.

Notez l’heure à laquelle vous avez consulté la vue du transporteur ou du fournisseur. Si la source a publié un nouveau scan après votre requête API, une différence entre les deux vues ne démontre pas que la requête précédente a échoué.

3. Vérifiez la charge utile de l’événement, pas seulement le statut principal

Comparez la description du dernier événement, son emplacement, le statut ou code du transporteur et tout champ de livraison pertinent avec l’enregistrement en amont. Un statut normalisé tel que « en transit » peut résumer plusieurs scans distincts. Si votre application ne stocke que le résumé, elle peut sembler inchangée même si un nouvel événement est arrivé.

Inspectez la réponse API brute ou le corps du webhook conservé lorsque vos règles de traitement des données le permettent. Suivez ensuite l’événement à travers l’analyse, la correspondance des champs, la persistance et la présentation. Recherchez les champs nuls remplacés par des valeurs par défaut, les codes de statut inattendus classés dans une catégorie générique, les textes tronqués ou une interface qui n’affiche que certains types d’événements. Une différence d’étiquette de statut est différente d’un événement manquant : elle indique plutôt un problème de transformation ou d’affichage qu’un problème de transmission.

Ne concluez pas à une livraison uniquement parce qu’un emplacement ou un statut semble final. Confirmez l’événement précis et les champs sur lesquels votre processus repose. Inversement, un statut général inchangé ne prouve pas que la synchronisation s’est arrêtée ; un nouveau scan peut être associé à la même catégorie. Votre enregistrement de diagnostic doit conserver à la fois l’événement en amont et la valeur affichée aux utilisateurs.

4. Suivez le chemin de l’événement jusqu’à votre application

Si vous utilisez des webhooks, consultez le journal de réception pour l’expédition et l’événement concernés. Vérifiez que votre point de terminaison a accepté la requête, que le message a passé la validation et que le traitement en aval s’est terminé. Une réponse HTTP réussie de votre point de terminaison ne prouve pas qu’un processus ultérieur dans la file a enregistré l’événement. Si le traitement est asynchrone, examinez à la fois la requête entrante et le résultat du traitement.

Si vous interrogez une API, vérifiez la dernière requête terminée, l’identifiant d’expédition utilisé dans cette requête, sa réponse ainsi que toute logique de pagination ou de récupération employée par votre intégration. Une requête réussie peut tout de même être suivie d’une écriture échouée dans la base de données ou de la lecture d’un cache obsolète. Utilisez la documentation applicable du fournisseur pour vérifier les champs de réponse réels, les exigences d’authentification et le comportement de transmission de votre intégration, plutôt que de supposer que toutes les API de suivi suivent le même contrat. Pour une intégration 17TRACK, les points de départ pertinents sont sa page de l’API de suivi et sa documentation API ; confirmez le comportement documenté du point de terminaison et de la méthode que vous utilisez.

Rendez le traitement des événements sûr en cas de répétition. Une nouvelle tentative ne doit pas créer de scans en double, envoyer plusieurs fois la même notification au client ni remplacer un état enregistré plus récent par une charge utile plus ancienne. La clé de déduplication appropriée dépend des champs réellement fournis par votre fournisseur. Testez la clé choisie avec des événements distincts qui partagent par hasard un statut ou un horodatage ; ces événements ne doivent pas être regroupés uniquement parce qu’ils se ressemblent.

5. Vérifiez les règles d’ordre et de transition d’état

Triez les événements enregistrés selon une règle clairement définie, puis inspectez le résultat. De nombreuses applications doivent distinguer le « dernier événement survenu » du « dernier événement reçu ». Un scan antérieur retardé peut arriver après un scan plus récent. Si votre base de données fait simplement du message traité le plus récemment l’état actuel de l’expédition, ce scan retardé peut faire reculer le statut affiché.

Comparez votre historique enregistré avec l’historique en amont, et pas seulement le champ de statut unique. Demandez-vous si un nouvel enregistrement reçu a été ajouté, rejeté comme doublon ou autorisé à mettre à jour l’état actuel. Vérifiez toute règle donnant la priorité à certains événements. Une telle règle peut être intentionnelle, mais elle ne doit pas masquer l’événement sous-jacent ni laisser penser que le transporteur a annulé une étape lorsque l’application a simplement reçu tardivement un scan plus ancien.

Pour un test pratique, prenez une expédition comportant plusieurs événements et rejouez ses messages dans un ordre d’arrivée différent dans un environnement hors production. Confirmez que l’historique des événements reste intact et que le statut destiné au client suit votre règle documentée. Cela révèle les défauts d’ordre qu’un test normal, effectué dans l’ordre, ne peut pas mettre en évidence.

6. Mesurez la fraîcheur et rapprochez les exceptions

Enfin, comparez ce que chaque couche savait au même point d’observation : la vue du transporteur, la réponse du fournisseur de suivi, le webhook entrant ou le résultat de l’interrogation, l’enregistrement de la base de données et la sortie destinée au client. Identifiez la première couche où l’événement attendu disparaît. Cette limite est plus utile qu’un rapport général indiquant que « le suivi est retardé ».

Mesurez à la fois l’ancienneté du dernier événement signalé par le transporteur et le temps écoulé depuis la dernière vérification ou réception réussie de données par votre intégration. Ces mesures répondent à des questions différentes. Un colis peut ne présenter aucun nouveau scan du transporteur alors que votre intégration fonctionne correctement ; inversement, le transporteur peut afficher un nouveau scan alors que votre dernière requête réussie est ancienne. Utilisez des seuils d’alerte adaptés à vos propres exigences opérationnelles et au comportement observé. Ne promettez pas aux clients un intervalle fixe de mise à jour si vos accords avec le transporteur et le fournisseur ne le permettent pas.

Créez une petite file de rapprochement pour les expéditions dont les enregistrements diffèrent de la source de comparaison choisie. Incluez les identifiants, l’événement manquant ou incohérent, les horodatages pertinents, la première couche défaillante et l’action suivante. Par exemple, un événement présent dans la réponse du fournisseur mais absent de votre base de données nécessite une investigation de l’intégration. Un événement présent dans votre base de données mais absent de la page de suivi nécessite une vérification de l’affichage ou du cache. Si le transporteur lui-même n’affiche aucun nouveau scan, une autre requête API ne peut pas en créer un.

Le test opérationnel est simple : pouvez-vous identifier la même expédition, localiser son dernier événement connu en amont et suivre cet événement jusqu’à la vue destinée à l’utilisateur sans en modifier le sens ? Si ce n’est pas le cas, les six vérifications permettent de circonscrire le problème à une limite précise et donnent à votre équipe une prochaine étape justifiable.

FAQ

Une réponse réussie à un webhook signifie-t-elle que le dernier événement est synchronisé ?

Non. Elle montre que votre point de terminaison a renvoyé une réponse réussie à une requête. Confirmez également que la validation, le traitement dans la file, l’enregistrement dans la base de données et l’affichage ont réussi. Vérifiez la charge utile pour déterminer quel événement la requête contenait.

Pourquoi la page du transporteur affiche-t-elle un scan plus récent que ma réponse API ?

Confirmez d’abord que vous consultez le même colis et que les deux observations ont été effectuées à des moments comparables. La publication par le transporteur et la réception ou l’exposition d’un événement par le fournisseur de suivi peuvent avoir lieu à des moments différents. Si la différence persiste, utilisez la documentation et le processus d’assistance du fournisseur pour examiner l’expédition concernée plutôt que de supposer une garantie de mise à jour.

Dois-je utiliser l’horodatage de l’événement ou l’heure de réception par mon système pour choisir le dernier statut ?

Utilisez une règle documentée adaptée à votre processus et conservez les deux valeurs. L’horodatage de l’événement décrit le moment où l’activité signalée s’est produite ; l’heure de réception décrit le moment où votre système en a pris connaissance. Aucun de ces champs ne suffit à résoudre tous les cas, en particulier lorsque les heures sources sont ambiguës ou que des scans antérieurs arrivent tardivement.

Que faire si le statut API est inchangé mais que la liste des événements contient une nouvelle entrée ?

Cela peut être normal si plusieurs événements du transporteur sont associés à un même statut normalisé. Comparez les détails de l’événement et vérifiez que votre application a enregistré et affiche la nouvelle entrée lorsque cela est approprié. Traitez un événement manquant et une étiquette de résumé inchangée comme deux problèmes différents.

Sources