Skip to main content
AccueilBlogGuidesQuels champs de réponse de l’API de suivi permettent de créer une chronologie complète du suivi de l’expédition ?

Quels champs de réponse de l’API de suivi permettent de créer une chronologie complète du suivi de l’expédition ?

17TRACK

Une chronologie complète du suivi d’un envoi nécessite davantage qu’un statut actuel. Pour chaque événement de suivi, conservez un identifiant d’envoi, l’horodatage de l’événement, la description ou le code de l’événement du transporteur, un statut normalisé lorsqu’il est disponible, ainsi que le lieu de l’événement lorsqu’il est fourni. Ajoutez le contexte du transporteur et du numéro de suivi, les détails de livraison ou d’exception, ainsi qu’un moyen de préserver l’ordre des événements et les mises à jour. Les noms exacts des champs varient selon l’API ; l’objectif est de reconstituer ce qui s’est passé, quand, où et pour quel colis.

Quels champs de réponse d’une API de suivi permettent de créer un suivi complet des envois

Pour un développeur qui crée une page de commande, un tableau de bord d’assistance ou un flux logistique, la distinction la plus utile est celle entre le récapitulatif de l’envoi et l’historique des événements. Un récapitulatif répond à la question « Quel est le dernier état connu ? » Une chronologie répond à la question « Comment l’envoi est-il arrivé à cet état ? » Les deux sont nécessaires, mais ne doivent pas être considérés comme interchangeables.

Commencez par l’identité de l’envoi, pas par le statut

Chaque événement doit être associé au bon envoi. Un numéro de suivi constitue souvent le point de départ, mais il ne devrait pas être le seul identifiant dans un modèle de données interne. Conservez l’identifiant d’envoi ou d’enregistrement de suivi de l’API s’il est fourni, ainsi que vos propres identifiants de commande et de colis. Enregistrez l’identifiant ou le nom du transporteur et, le cas échéant, le contexte de destination ou d’origine utilisé pour identifier l’envoi.

Cela est important lorsqu’une commande comporte plusieurs colis, qu’un numéro de suivi est corrigé ou qu’un transfert introduit un autre transporteur ou un autre numéro de référence. Si une API expose des numéros de suivi associés ou des détails sur le transfert entre transporteurs, enregistrez cette relation au lieu de fusionner deux historiques simplement parce qu’ils appartiennent à la même commande. Une commande peut comporter plusieurs chronologies d’envoi valides.

Au niveau de l’événement, un ensemble d’identifiants pratique comprend la référence de l’envoi, le transporteur responsable de l’événement s’il est connu et soit un identifiant d’événement stable fourni par l’API, soit suffisamment de données sources pour identifier un événement répété. Ne supposez pas que deux scans portant le même statut sont des doublons : un colis peut recevoir le même type de scan dans des installations ou à des moments différents.

Les champs de réponse qui rendent chaque événement utile

Les noms de champs tels que event_time et status ci-dessous décrivent des rôles de données et non un schéma universel d’API de suivi. Faites-les correspondre à la réponse réelle documentée par votre fournisseur.

  • Heure de l’événement : l’heure à laquelle le transporteur indique que l’événement s’est produit. Conservez la valeur d’origine et les informations de fuseau horaire lorsqu’elles sont fournies. Il s’agit normalement de l’horodatage principal d’une chronologie destinée aux clients.
  • Description de l’événement ou code du transporteur : le texte original du scan ou le code d’événement lisible par machine. La conservation de la valeur source rend le libellé normalisé vérifiable et aide les équipes d’assistance à examiner les scans inconnus.
  • Statut normalisé : une catégorie définie par le fournisseur ou l’application, comme en transit, en cours de livraison, livré ou exception. Utilisez-la pour regrouper les événements, mais ne la laissez pas remplacer le détail original du scan.
  • Lieu : l’installation, la ville, la région, le pays ou tout autre champ de localisation réellement fourni par le transporteur. Affichez uniquement le niveau de précision présent dans la réponse ; ne transformez pas un scan au niveau du pays en une localisation implicite au niveau de la rue.
  • Contexte du transporteur et du suivi : l’identifiant du transporteur, le numéro de suivi et tout numéro associé nécessaire pour expliquer un transfert ou distinguer les colis.
  • Métadonnées de l’événement : un identifiant d’événement source, un numéro de séquence ou une autre référence du fournisseur, si disponible. Ces champs peuvent aider à dédupliquer les événements, à gérer les corrections et à maintenir un ordre stable.

Une chronologie utile peut toujours être créée même lorsque certains champs facultatifs sont absents. Par exemple, un événement « livré » valide peut ne comporter aucun lieu de livraison public. L’application doit afficher l’événement confirmé sans inventer de lieu ni de destinataire.

Gardez l’heure de l’événement distincte de l’heure de traitement

Les systèmes de suivi peuvent exposer plusieurs horodatages : le moment où un scan a eu lieu, celui où un transporteur l’a publié, celui où un fournisseur d’API l’a enregistré et celui où votre application l’a reçu. Ces horodatages répondent à des questions différentes. Triez principalement le parcours affiché selon l’heure à laquelle l’événement s’est produit lorsque cette heure est fiable ; utilisez l’heure d’ingestion pour indiquer quand votre système a pris connaissance de l’événement et pour détecter les mises à jour arrivées tardivement.

Les données reçues tardivement sont suffisamment courantes pour qu’il soit nécessaire de les prendre en compte dès la conception. Un transporteur peut publier un scan antérieur après qu’un scan ultérieur est déjà visible. Si l’application ajoute simplement chaque nouvelle réponse de l’API en bas de la page, la chronologie obtenue peut être incorrecte. Réconciliez les événements avec l’historique stocké, puis ordonnez-les selon une règle documentée. Si deux événements ont la même heure d’occurrence, une séquence source ou un identifiant d’événement peut servir de critère de départage. Sinon, conservez un ordre interne déterministe sans prétendre que la source en a établi un.

La gestion des fuseaux horaires mérite une attention particulière. Un horodatage contenant un décalage peut être normalisé pour le stockage tout en conservant l’horodatage original pour l’affichage ou l’analyse. Un horodatage sans décalage indiqué ne doit pas être interprété silencieusement comme étant en UTC. Pour les intégrations qui acceptent ou émettent des horodatages Internet, RFC 3339 constitue une référence utile pour la représentation des horodatages ; elle ne permet toutefois pas, à elle seule, de déterminer le fuseau horaire voulu par un transporteur lorsque ses données n’en indiquent aucun.

Séparez le dernier état de l’historique complet

De nombreuses réponses de suivi comprennent à la fois le statut actuel de l’envoi et une liste d’événements historiques. Le statut actuel est utile pour une carte de commande compacte, le filtrage et les notifications. L’historique constitue la source de la séquence des scans. Ne créez pas de nouvel événement historique chaque fois que vous interrogez un statut actuel inchangé et ne supprimez pas les événements plus anciens simplement parce que l’objet contenant le dernier statut est complet.

Évitez également de supposer que le dernier élément d’un tableau correspond au scan le plus récent. Vérifiez les règles d’ordre du fournisseur, puis triez ou réconciliez les éléments en conséquence. Une réponse peut ne contenir qu’une partie de l’historique, ou une intégration peut devoir récupérer des pages supplémentaires. Si l’API documente la pagination ou une limite d’historique, suivez ce mécanisme avant de présenter le parcours affiché comme complet. Lorsque l’historique n’est pas disponible, indiquez qu’il s’agit des événements reçus plutôt que de laisser entendre qu’aucun scan antérieur n’a eu lieu.

Pour une représentation interne robuste, stockez la réponse brute ou les champs sources nécessaires pour reproduire votre interprétation, en parallèle d’un enregistrement d’événement normalisé. La conservation des valeurs sources est particulièrement utile lorsqu’une correspondance change : vous pouvez retraiter les anciens événements sans demander à un transporteur de recréer des données qui pourraient ne plus être récupérables.

Modélisez soigneusement les étapes clés, les exceptions et les preuves de livraison

Un libellé de statut n’est pas toujours une étape clé. « En transit » peut résumer plusieurs scans, tandis que « en cours de livraison » et « livré » représentent généralement des étapes distinctes. Construisez les étapes clés à partir de la signification documentée des événements au lieu de supposer que tous les transporteurs utilisent une terminologie identique. Si un statut est ambigu, affichez la description originale et évitez d’ajouter une affirmation plus catégorique.

Les événements d’exception nécessitent à la fois une catégorie et le détail du transporteur lorsqu’il est disponible. « Livraison tentée » raconte une histoire différente de « Dédouanement en attente », même si une application regroupe les deux dans un état nécessitant une attention particulière. Conservez le texte du motif, le code du motif et les informations sur la prochaine action dans des champs distincts si la réponse les fournit. Un agent d’assistance pourra ainsi distinguer un retard temporaire d’un événement pouvant nécessiter une action du destinataire.

La confirmation de livraison doit être traitée avec le même soin. Si la réponse comprend un événement de livraison, enregistrez son horodatage ainsi que les informations disponibles sur le lieu ou le destinataire. Si elle comprend une preuve de livraison, conservez le type de preuve et les éventuelles restrictions d’accès définies par le fournisseur. N’inférez pas une signature, une photographie ou un destinataire nommé à partir du seul statut « livré ». De même, une date de livraison estimée est une prévision et non un événement terminé ; affichez-la séparément de la chronologie historique.

Flux pratique de correspondance pour les développeurs

  1. Examinez une réponse réelle et sa documentation. Identifiez l’objet au niveau de l’envoi, le tableau des événements, les formats d’horodatage, le vocabulaire des statuts ainsi que les limites ou la pagination documentées. Ne supposez pas que les noms de champs illustratifs d’un article correspondent au schéma de production.
  2. Définissez un modèle d’événement interne unique. Incluez l’identité de l’envoi, le transporteur source, l’heure d’occurrence, le texte ou code de statut original, la catégorie normalisée, le lieu facultatif, l’identifiant d’événement source et l’heure de réception. Rendez les champs facultatifs nullables plutôt que de les remplir avec des suppositions.
  3. Rédigez des règles de correspondance explicites. Notez comment chaque champ source devient un champ interne et quelle valeur source justifie chaque statut normalisé. Laissez les codes inconnus visibles pour examen au lieu de les forcer dans une étape inexacte.
  4. Réconciliez les réponses répétées. Utilisez un identifiant d’événement documenté lorsqu’il est disponible. Sinon, définissez une règle de rapprochement prudente fondée sur des valeurs sources stables et testez-la avec plusieurs scans partageant légitimement le même statut.
  5. Testez les parcours difficiles. Incluez plusieurs colis, des scans tardifs, des horodatages identiques, des transferts entre transporteurs, des tentatives de livraison, des lieux manquants, des estimations modifiées et un événement livré avec des détails de confirmation limités.
  6. Vérifiez les promesses de l’interface. La chronologie doit distinguer les événements observés des prévisions, préserver l’incertitude et éviter de présenter un historique incomplet comme un compte rendu exhaustif de l’envoi.

Pour une intégration de l’API de suivi 17TRACK, utilisez la documentation officielle de l’API pour confirmer la structure réelle de la réponse et la signification des champs avant d’implémenter cette correspondance. Les rôles des champs présentés dans ce guide constituent une liste de contrôle d’implémentation ; ils ne signifient pas que 17TRACK renvoie des champs portant exactement ces noms ni que chaque transporteur fournit tous les détails.

Qu’est-ce qui constitue une chronologie complète ?

Une chronologie est complète pour votre application lorsqu’elle relie chaque événement affiché au bon colis, conserve l’événement source et son heure, ordonne les événements connus de manière cohérente et représente le statut, le lieu, les exceptions et la confirmation de livraison uniquement dans la mesure où la réponse le permet. L’exhaustivité opérationnelle nécessite également de connaître les limites des données : l’API a-t-elle renvoyé tout l’historique disponible, une période limitée ou uniquement les événements d’un transporteur ou d’un enregistrement de suivi particulier ?

Le meilleur test d’acceptation ne consiste pas à compter le nombre de champs remplis. Il consiste à vérifier si un client ou un agent d’assistance peut lire le parcours sans être induit en erreur. Si l’application peut répondre à ce qui s’est passé, au moment où cela s’est passé, à l’envoi concerné et à ce qui reste incertain, les champs de réponse remplissent leur fonction.

FAQ

Un champ de statut actuel suffit-il pour créer une chronologie d’envoi ?

Non. Un statut actuel fournit un instantané. Une chronologie nécessite des enregistrements d’événements historiques avec des horodatages et le contexte nécessaire pour associer chaque enregistrement au bon envoi.

Dois-je afficher le texte des scans du transporteur ou uniquement les statuts normalisés ?

Conservez les deux lorsque l’API les fournit. Les statuts normalisés facilitent la lecture du parcours ; les descriptions originales conservent les détails et aident à expliquer les événements inhabituels ou propres à un transporteur.

Quel horodatage doit déterminer l’ordre des événements ?

Utilisez l’heure d’occurrence de l’événement lorsque sa signification et son fuseau horaire sont suffisamment clairs. Conservez séparément l’heure de réception par l’API et définissez un critère de départage stable pour les événements dont l’heure d’occurrence est identique ou incertaine.

Que faire si un événement de suivi n’a pas de lieu ?

Affichez l’événement sans lieu. L’absence de données de localisation ne rend pas l’événement invalide, mais elle ne justifie pas d’inférer une installation, une ville ou une adresse de livraison.

Comment savoir si l’API a renvoyé l’intégralité du parcours ?

Consultez la documentation du fournisseur concernant la portée de l’historique, la pagination et les limites de réponse, puis vérifiez comment votre intégration récupère les événements supplémentaires. Si la portée ne peut pas être confirmée, décrivez la chronologie comme étant constituée des événements disponibles pour votre application.

Sources