Skip to main content
AccueilBlogGuidesQuelles données une API de suivi doit-elle renvoyer ? 12 champs au-delà du statut actuel ?

Quelles données une API de suivi doit-elle renvoyer ? 12 champs au-delà du statut actuel ?

17TRACK

Une API de suivi devrait renvoyer davantage qu'une simple étiquette telle que « En transit ». Au-delà du statut actuel, recherchez les identifiants de l'envoi, l'identité du transporteur, les informations détaillées sur le statut, les messages originaux du transporteur, l'historique des événements, leurs horodatages, les lieux, les estimations de livraison, les exceptions, les transferts entre transporteurs, les détails de livraison et les métadonnées de fraîcheur des données. Ensemble, ces 12 groupes de données aident les développeurs à créer des flux de travail fiables et fournissent aux équipes opérationnelles suffisamment de contexte pour agir.

Quelles données une API de suivi doit-elle renvoyer : 12 champs au-delà du statut

Il s'agit d'un contrat de réponse recommandé pour les développeurs, les acheteurs techniques et les équipes chargées des opérations e-commerce, et non de l'affirmation que chaque transporteur ou API fournit tous les champs. Certaines valeurs peuvent légitimement être indisponibles. Une meilleure conception rend ces absences explicites au lieu de les combler par des suppositions.

Qu'est-ce qui rend les données de suivi utiles ?

Un statut actuel répond à une question précise : quel est l'état récapitulatif de l'envoi ? Il n'explique pas nécessairement ce qui s'est passé, quand cela s'est produit, si les informations sont récentes ou ce que quelqu'un devrait faire ensuite.

Par exemple, deux envois peuvent tous deux afficher « En transit » tout en nécessitant des réponses différentes. L'un peut avoir fait l'objet d'un scan récent dans un centre et ne présenter aucun problème signalé. L'autre peut avoir un problème d'adresse non résolu enregistré dans son historique d'événements. Une application qui ne lit que le statut principal peut ne pas voir cette différence.

Évaluez la réponse au regard de trois tâches pratiques : associer l'envoi à la bonne commande, expliquer précisément sa progression et décider si une action est justifiée. Les champs suivants contribuent à ces tâches. Les noms de champs sont donnés à titre illustratif ; ils ne constituent ni une norme universelle ni le schéma d'un fournisseur particulier.

12 champs à évaluer au-delà du statut actuel

1. Identifiants de l'envoi et du suivi

La réponse doit identifier l'envoi décrit. Les valeurs utiles comprennent le numéro de suivi soumis, l'identifiant de l'enregistrement de suivi de l'API et une référence client que votre système peut associer à un enregistrement d'exécution ou de colis.

Ne partez pas du principe qu'une commande équivaut à un seul envoi. Une commande peut être répartie entre plusieurs colis et un remplacement peut créer un autre envoi. Stockez les enregistrements de suivi au niveau du colis ou de l'exécution, puis associez-les à la commande. Conservez les numéros de suivi sous forme de chaînes afin de ne pas perdre leur formatage ni leurs zéros initiaux.

2. Identité du transporteur

Recherchez un identifiant stable du transporteur ainsi qu'un nom lisible. Lorsque cela est possible, la réponse doit distinguer un transporteur fourni explicitement par votre application d'un transporteur sélectionné par détection automatique.

Le contexte du transporteur est important pour interpréter un numéro de suivi et ses événements. Si la détection est ambiguë, votre intégration doit permettre de le résoudre plutôt que de présenter silencieusement une correspondance incertaine comme confirmée. Conservez séparément les informations relatives au niveau de service : le seul nom d'un transporteur ne permet pas de déterminer si l'envoi utilise un service express, postal ou autre.

3. Détail du statut normalisé

En plus du statut principal, demandez un code de détail ou un sous-statut documenté. Une catégorie générale peut décrire un envoi comme une exception, tandis que le détail identifie une tentative de livraison, un problème d'adresse ou un blocage lié aux douanes.

Utilisez des codes stables pour la logique métier et des libellés lisibles pour la présentation. Vérifiez comment le fournisseur convertit les événements des transporteurs en ces codes, notamment la manière dont il traite les événements inconnus ou non mappés. Un libellé normalisé facilite l'utilisation de flux provenant de différents transporteurs, mais il ne doit pas effacer les distinctions dont votre équipe d'assistance a besoin.

4. Messages et codes originaux du transporteur

Conservez la description originale de l'événement et le code d'événement du transporteur lorsqu'ils sont fournis. Ces valeurs donnent aux agents d'assistance un contexte qui peut manquer dans un statut normalisé, notamment lorsqu'un transporteur emploie une expression opérationnelle précise.

Conservez le texte original séparément des descriptions traduites ou réécrites. Sinon, une explication destinée au client peut être prise pour la formulation exacte du transporteur. Traitez le texte du transporteur comme une entrée non fiable lors de son affichage : échappez-le correctement et ne le rendez pas comme du HTML exécutable.

5. Historique des événements de suivi

Une réponse utile doit exposer la chronologie de l'envoi, et pas seulement son dernier événement. Chaque événement devrait idéalement inclure un identifiant, un statut ou un code, une description, un horodatage et les informations de lieu disponibles.

Vérifiez si l'API renvoie l'historique complet, une fenêtre limitée ou des résultats paginés. Déterminez également comment sont représentées les corrections et les observations en double. Votre application ne doit pas supposer que le premier élément est toujours le plus récent, sauf si le contrat de réponse garantit explicitement cet ordre.

6. Horodatages des événements et informations de fuseau horaire

L'heure à laquelle un événement s'est produit diffère de l'heure à laquelle l'API l'a reçu ou renvoyé. Conservez les deux lorsqu'elles sont disponibles. Cette distinction aide à expliquer pourquoi une mise à jour nouvellement reçue peut décrire un événement antérieur.

Demandez des horodatages comportant des décalages UTC explicites ou la notation UTC. RFC 3339 définit un format d'horodatage adapté aux protocoles Internet, y compris les décalages horaires numériques. Si une source ne fournit qu'une heure locale sans décalage connu, préservez cette incertitude au lieu de la traiter silencieusement comme de l'UTC. Ne suggérez jamais une précision à la seconde lorsque la source sous-jacente ne fournit qu'une date.

7. Lieux des événements et géographie de l'envoi

Recherchez des éléments de lieu structurés tels que la ville, la région, le pays et le code postal lorsqu'ils sont fournis. Conservez également une chaîne de lieu brute si sa conversion en champs structurés risque d'en altérer le sens.

Le lieu d'un scan ne correspond pas nécessairement à la position actuelle du colis. De même, le dernier centre signalé ne prouve pas que le colis s'y trouve encore. Les pages destinées aux clients doivent le décrire comme le dernier lieu signalé. Évitez de déduire des coordonnées ou une adresse de livraison exacte à partir d'un texte de scan incomplet.

8. Date ou fenêtre de livraison estimée

Un champ de livraison estimée doit indiquer s'il contient une date unique ou une fenêtre, qui l'a produit et quand il a été mis à jour pour la dernière fois. Une estimation fournie par un transporteur et une prévision calculée séparément doivent rester distinguables.

Ne convertissez pas une estimation limitée à une date en heure d'arrivée précise. Votre intégration doit également gérer les estimations révisées ou retirées sans conserver une promesse obsolète sur la page de suivi. Si aucune estimation n'existe, indiquez qu'elle est indisponible plutôt que d'en calculer une à partir d'une hypothèse non étayée.

9. Motif de l'exception et action requise

Les informations relatives à une exception doivent expliquer le problème et, lorsque la source le permet, identifier une action, une partie responsable ou une échéance. Un avis général de retard est opérationnellement différent d'une demande d'informations au destinataire.

Séparez les faits signalés de vos propres décisions de flux de travail. Par exemple, votre entreprise peut ouvrir une tâche d'assistance après une période configurée sans mise à jour. Il s'agit d'une règle d'escalade interne, et non d'une preuve que le transporteur a déclaré le colis perdu. Ne générez pas d'instructions de paiement ni de demandes d'informations sensibles à partir d'un texte de suivi ambigu.

10. Transferts entre transporteurs et numéros de suivi associés

Lorsqu'un envoi passe d'un opérateur à un autre, les données utiles comprennent le transporteur suivant, un numéro de suivi associé et la relation entre l'enregistrement initial et les enregistrements ultérieurs. Cela peut aider à préserver la continuité lorsque l'étape de livraison utilise un identifiant différent.

Traitez un transfert signalé comme une relation au lieu d'écraser le transporteur initial. Ne fusionnez pas les enregistrements simplement parce que leurs destinations ou leurs numéros de suivi semblent similaires. Si la relation n'est pas fournie ou confirmée d'une autre manière, laissez-la non résolue au lieu d'inventer un parcours continu.

11. Résultat de la livraison et références de preuve

Lorsqu'une livraison est signalée, la réponse doit fournir l'heure de livraison enregistrée et tout détail disponible, comme la description d'un lieu sûr ou la catégorie du destinataire. Une référence de preuve de livraison peut également être utile lorsque le transporteur et le service la rendent disponible.

Un statut « livré » ne doit pas être considéré comme la preuve que le destinataire prévu a personnellement accepté le colis. Les signatures, photographies, noms et lieux précis peuvent contenir des informations personnelles. Limitez l'accès, évitez d'exposer ces détails sur les pages de suivi publiques et vérifiez les exigences d'autorisation ou d'expiration applicables aux liens de preuve.

12. Fraîcheur, état de récupération et métadonnées de réponse

Demandez suffisamment de métadonnées pour distinguer le dernier événement de l'envoi de la dernière récupération réussie des données. Les valeurs utiles comprennent la dernière vérification réussie, la dernière tentative échouée, l'heure de génération de la réponse et l'indication que les données renvoyées sont mises en cache ou partielles.

Une requête API réussie n'établit pas à elle seule que le transporteur a publié un nouveau scan. La sémantique de la réponse HTTP décrit le résultat de la requête ; la progression de l'envoi appartient aux données de l'application. Conservez séparément les erreurs de récupération et les exceptions d'expédition afin qu'un problème temporaire de connexion ne devienne pas une fausse alerte de livraison.

Les données manquantes doivent avoir une signification définie

La présence d'un champ ne représente qu'une partie du contrat. Votre équipe doit également comprendre ce que signifie une valeur absente. Une estimation de livraison peut être indisponible auprès de la source, ne pas encore avoir été récupérée ou ne plus être applicable après la livraison. Ces situations ne doivent pas automatiquement produire le même message client.

  • Inconnu : La valeur n'a pas encore été établie.
  • Non fourni : La source n'a pas fourni la valeur dans les données récupérées.
  • Non applicable : Le champ ne s'applique pas à cet enregistrement ou à cet état.
  • Échec de récupération : Le système n'a pas pu terminer la recherche correspondante.

Ces distinctions sont recommandées et ne constituent pas des valeurs littérales obligatoires. Quelle que soit la représentation choisie, documentez-la. Évitez les dates de remplacement, les objets vides ressemblant à des enregistrements valides et les coordonnées par défaut qui pourraient être prises pour de vrais lieux.

Comment tester la réponse avant l'intégration

Évaluez les charges utiles réelles provenant des transporteurs, services et itinéraires d'expédition utilisés par votre entreprise. Un schéma peut répertorier un champ facultatif sans garantir que chaque source sous-jacente le renseigne. Pour une intégration avec 17TRACK, utilisez la documentation officielle de l'API de suivi afin de vérifier le contrat de réponse, plutôt que de traiter les noms de champs conceptuels de ce guide comme des paramètres prêts à copier.

  1. Constituez un échantillon représentatif. Incluez les envois nouvellement enregistrés, les envois actifs, les tentatives de livraison, les livraisons terminées et les cas de transfert disponibles.
  2. Reliez les champs aux événements. Vérifiez que le statut affiché, le dernier événement et les détails de livraison décrivent un enregistrement cohérent. Examinez les divergences au lieu de les dissimuler.
  3. Testez les mises à jour retardées et répétées. Traitez à nouveau la même charge utile et recevez un événement plus ancien après un événement plus récent. Vérifiez qu'aucun des deux cas ne crée de notifications en double ni n'inverse incorrectement l'état affiché.
  4. Testez les valeurs manquantes et malformées. Incluez les estimations absentes, les lieux inconnus, les codes de statut inhabituels et les horodatages incomplets. L'application doit rester utilisable sans inventer de valeurs de remplacement.
  5. Séparez les échecs de transport des résultats de suivi. Un échec d'authentification, un délai d'attente ou une réponse malformée doit suivre un parcours d'erreur d'intégration, et non un flux de travail d'exception d'expédition.
  6. Validez la vue client. Vérifiez que les références internes, les détails de diagnostic bruts et les informations personnelles ne sont pas divulgués sur les pages ou dans les notifications publiques.

Pour les mises à jour fondées sur des webhooks, vérifiez également les identifiants de livraison, l'authentification, le comportement des nouvelles tentatives et la gestion des relectures dans la documentation du fournisseur. Il s'agit d'exigences d'intégration plutôt que de faits relatifs à l'envoi. Votre récepteur doit traiter les livraisons répétées de manière sûre et ne doit pas supposer que l'ordre d'arrivée correspond à l'ordre des événements.

Le critère d'acceptation doit être pratique : votre application peut-elle expliquer l'envoi sans formuler d'affirmations non étayées, et votre équipe opérationnelle peut-elle identifier la prochaine action justifiée ? Une charge utile plus petite et bien définie peut être plus utile qu'une réponse plus volumineuse remplie de valeurs facultatives inexpliquées.

FAQ

Chaque envoi doit-il contenir les 12 groupes de données ?

Non. Les preuves de livraison, les numéros de suivi ultérieurs et les dates de livraison estimées peuvent être indisponibles ou non applicables. Exigez des définitions de champs claires et un comportement prévisible pour les valeurs manquantes, plutôt qu'un remplissage universel. Vérifiez les champs les plus importants en fonction de votre mix d'expéditions réel.

Devons-nous stocker la réponse brute ou uniquement les champs normalisés ?

Stockez les champs normalisés pour la logique de l'application. La conservation des charges utiles sources pertinentes peut également faciliter le débogage et les changements de mappage, sous réserve de vos exigences en matière de confidentialité, de sécurité, de contrat et de conservation. Limitez l'accès et n'enregistrez pas de contenu sensible simplement parce qu'il apparaît dans une réponse.

Quel horodatage doit déterminer le dernier événement ?

Utilisez la chronologie documentée des événements et les règles d'ordre du fournisseur, en tenant compte des fuseaux horaires et des corrections. L'heure de réception indique quand votre système a pris connaissance d'un événement, pas nécessairement quand celui-ci s'est produit. Si les horodatages sont incomplets ou contradictoires, préservez l'ambiguïté au lieu de prétendre à une séquence précise.

Une API de suivi peut-elle confirmer qu'un colis est perdu ?

Ne considérez une perte comme signalée par le transporteur que lorsque la source permet explicitement cette interprétation. Une longue période sans scan peut justifier une enquête selon vos règles opérationnelles, mais le silence seul n'établit pas la perte. Conservez séparément les notions de « suivi obsolète » et de « perte signalée ».

Un statut livré suffit-il à clôturer une réclamation client ?

Pas automatiquement. Il établit le résultat de suivi signalé, mais peut ne pas résoudre le litige du destinataire. Examinez les détails de livraison disponibles, le compte du client et votre processus d'assistance. Évitez de traiter un libellé de statut comme un substitut à l'examen d'informations contradictoires.

Sources