Skip to main content
AccueilBlogGuidesFlux de travail de l’API de suivi des expéditions : de l’enregistrement d’une expédition à la récupération des détails de suivi

Flux de travail de l’API de suivi des expéditions : de l’enregistrement d’une expédition à la récupération des détails de suivi

17TRACK

Un workflow d’API de suivi des expéditions commence par l’envoi d’un numéro de suivi et de toute information requise sur le transporteur, la vérification de la réussite de l’enregistrement, l’attente de la disponibilité des données de suivi, puis la récupération du statut et de l’historique des événements de l’expédition. Pour une intégration en production, les développeurs doivent également associer chaque enregistrement de suivi à une commande, gérer les échecs partiels, traiter les mises à jour de manière sûre et distinguer un enregistrement accepté d’un véritable scan effectué par le transporteur.

Workflow de l’API de suivi des expéditions, de l’enregistrement d’une expédition à la récupération des informations

Ce guide explique ce workflow aux développeurs qui connectent une plateforme e-commerce, un système de gestion des commandes, une application d’entrepôt ou un outil de service client. Il sépare les recommandations de conception applicative des exigences propres à chaque fournisseur. Pour une intégration 17TRACK, utilisez la documentation officielle de l’API afin de confirmer le schéma des requêtes, l’authentification, les opérations prises en charge et les champs de réponse avant d’implémenter les exemples ci-dessous.

Comprendre ce que fait — et ne fait pas — l’enregistrement

Enregistrer une expédition auprès d’un service de suivi signifie envoyer un identifiant afin que le service puisse suivre ou gérer cette expédition conformément à son contrat d’API. Il ne s’agit pas de la même opération que l’achat de frais de port, la génération d’une étiquette d’expédition, la réservation d’une collecte ou la remise d’un colis à un transporteur.

Séparez trois résultats dans votre application :

  • Requête reçue : L’API a renvoyé une réponse à votre requête HTTP.
  • Enregistrement accepté : Le service a accepté l’enregistrement de suivi individuel pour traitement.
  • Informations de suivi disponibles : Le service dispose d’informations sur l’expédition que votre application peut récupérer ou recevoir.

Ces résultats ne doivent pas être regroupés sous un seul indicateur de réussite. Un numéro de suivi accepté peut encore ne comporter aucun événement du transporteur. De même, une réponse HTTP réussie à une requête groupée ne prouve pas que chaque élément du lot a été accepté ; examinez la structure du résultat au niveau de l’application définie par le fournisseur.

1. Préparer l’identification de l’expédition et la configuration de l’API

Avant d’envoyer une requête d’enregistrement, déterminez comment une expédition sera identifiée dans votre propre système. Un identifiant de commande seul est généralement insuffisant, car une commande peut être divisée en plusieurs colis. Attribuez à chaque expédition ou colis son propre enregistrement interne et associez cet enregistrement à la commande concernée.

Un enregistrement interne utile comprend les informations suivantes. Il s’agit de champs applicatifs suggérés, et non d’un schéma de requête 17TRACK.

  • ID interne de l’expédition : Votre identifiant stable pour le colis.
  • Référence de commande : La commande ou l’enregistrement d’exécution auquel il appartient.
  • Numéro de suivi : L’identifiant fourni par le transporteur, stocké sous forme de texte afin de préserver les zéros initiaux.
  • Informations sur le transporteur : L’identité du transporteur fournie par votre système d’exécution, si elle est connue.
  • Référence du fournisseur : Tout identifiant renvoyé par le service de suivi et nécessaire aux opérations ultérieures.
  • État de l’enregistrement : Votre indication précisant si l’envoi est en attente, accepté, rejeté ou en attente de rapprochement.
  • État du suivi : Le dernier statut de l’expédition, géré séparément de l’état de l’enregistrement.

Validez les données avant l’envoi. Supprimez les espaces superflus accidentels, mais ne réécrivez pas le numéro de suivi en vous fondant sur des hypothèses concernant le format d’un transporteur. Conservez la valeur originale pour le dépannage. Si le transporteur est connu, faites-le correspondre à l’identifiant documenté du fournisseur plutôt que d’envoyer un nom d’affichage informel.

Configurez l’authentification côté serveur. Conservez les identifiants hors du contrôle de version, séparez les configurations de développement et de production et masquez les secrets dans les journaux. Confirmez la version documentée de l’API, les limites de requêtes, les limites des lots et les exigences du compte au lieu de reprendre des valeurs provenant d’une intégration sans rapport.

2. Enregistrer l’expédition et consigner le résultat au niveau de l’élément

Envoyez l’enregistrement de suivi à l’aide de l’opération d’enregistrement décrite dans la documentation de votre fournisseur. Incluez uniquement les champs obligatoires et les informations facultatives ayant un objectif défini. Évitez d’envoyer les noms, adresses ou autres données personnelles des clients simplement parce qu’elles sont disponibles dans votre base de données de commandes.

Le pseudocode suivant illustre la séquence applicative. Les noms de fonctions sont donnés à titre d’illustration ; ils ne correspondent pas à des points de terminaison d’API ni à des méthodes de SDK.

shipment = load_internal_shipment(shipment_id)
validate_tracking_input(shipment)

result = tracking_adapter.register(shipment)

if result.item_accepted:
    save_registration_result(shipment_id, result)
elif result.outcome_unknown:
    schedule_registration_reconciliation(shipment_id)
else:
    save_registration_error(shipment_id, result)
    route_for_retry_or_correction(result)

Conservez suffisamment d’informations pour expliquer ce qui s’est passé : l’ID interne de l’expédition, l’heure d’envoi, le numéro de tentative, le résultat au niveau de l’élément et toute référence de requête du fournisseur. Ne vous fiez pas uniquement à un journal temporaire de tâche. Vos équipes de service client et d’exploitation ont besoin d’une réponse durable indiquant si une expédition a bien été enregistrée.

Traiter individuellement les envois groupés

Si l’API prend en charge l’enregistrement par lots, associez chaque élément renvoyé à son expédition d’origine. Ne marquez pas l’ensemble du lot comme accepté simplement parce que la requête HTTP s’est terminée avec succès. Enregistrez les éléments acceptés, isolez ceux qui sont rejetés et examinez séparément les résultats ambigus.

Cela empêche un numéro de suivi mal formé d’entraîner des nouvelles tentatives inutiles pour des enregistrements déjà traités avec succès. Cela fournit également au personnel opérationnel une liste exploitable des enregistrements nécessitant une correction.

Traiter les délais d’attente comme un résultat inconnu

Un délai d’attente ne prouve pas que l’enregistrement a échoué. Le fournisseur peut avoir accepté la requête avant l’interruption de votre connexion. Utilisez le comportement d’idempotence, la gestion des doublons ou les opérations de recherche documentés afin de rapprocher le résultat avant de renvoyer la requête sans vérification.

Lorsque le comportement du fournisseur en cas de doublon n’est pas clair, testez-le avec des enregistrements contrôlés et confirmez le contrat avant d’activer les nouvelles tentatives automatiques. Dédupliquer en interne les tâches d’enregistrement reste utile, mais cela ne remplace pas la compréhension de la manière dont le service distant gère les requêtes répétées.

3. Prévoir l’arrivée des premières informations de suivi

Après l’acceptation de l’enregistrement, les détails du suivi peuvent ne pas être disponibles immédiatement. Une étiquette peut exister avant que le transporteur n’ait enregistré un événement physique de traitement. L’absence d’informations peut également nécessiter la vérification du numéro de suivi, de la sélection du transporteur ou des exigences de recherche propres à l’expédition.

Représentez explicitement cette situation. « Enregistré ; informations de suivi en attente » est plus exact que « En transit » ou « Échec de l’enregistrement ». N’inventez pas d’estimation de livraison ni d’événement de mouvement pour remplir une interface vide.

Lorsqu’un enregistrement reste vide, effectuez les vérifications dans l’ordre pratique suivant :

  1. Confirmez que l’enregistrement individuel a été accepté.
  2. Comparez le numéro de suivi envoyé avec l’enregistrement d’exécution.
  3. Vérifiez la correspondance du transporteur et toute exigence supplémentaire de recherche documentée.
  4. Consultez la page de suivi du transporteur pour la même expédition.
  5. Si le transporteur dispose d’événements mais que votre intégration n’en affiche pas, examinez les réponses de récupération et contactez le fournisseur de l’API avec des informations de diagnostic anonymisées.

Évitez d’adopter un délai d’attente universel sans preuves. Les règles d’escalade doivent tenir compte du service d’expédition, du processus de remise prévu et de vos propres engagements opérationnels.

4. Récupérer les détails de suivi et les interpréter correctement

Une fois l’enregistrement disponible, appelez l’opération documentée de récupération des détails de suivi en utilisant les identifiants requis. Ne supposez pas que l’enregistrement et la récupération acceptent des champs identiques. Certains contrats d’API distinguent les numéros de suivi, les identifiants de transporteur et les références d’enregistrement générées par le fournisseur.

Votre application doit distinguer trois niveaux d’information :

  • Résumé de l’expédition : L’état général utilisé dans les tableaux de bord, les pages de commande et les filtres opérationnels.
  • Historique des événements : Les observations individuelles, notamment les descriptions, horodatages et lieux des événements lorsqu’ils sont fournis.
  • Métadonnées de récupération : Le moment où votre application a reçu ou récupéré les informations et si la requête s’est terminée avec succès.

Une recherche réussie signifie que l’opération de récupération a réussi. Cela ne signifie pas que le colis a bougé depuis la recherche précédente. Comparez les informations de suivi renvoyées avec votre enregistrement stocké avant de générer une notification ou un workflow en aval.

Séparer l’heure de l’événement de l’heure de récupération

Stockez séparément l’heure associée à un événement du transporteur et l’heure à laquelle votre système l’a reçu. Un événement récupéré cet après-midi peut décrire un scan antérieur. Remplacer son heure d’événement par l’heure de récupération ferait passer une ancienne mise à jour pour un nouveau mouvement physique.

Conservez l’horodatage d’origine et tout décalage fourni. Normalisez les horodatages à des fins de comparaison uniquement lorsque le fuseau horaire est connu. Si un événement ne comporte aucune information de fuseau horaire, conservez cette incertitude au lieu d’attribuer silencieusement le fuseau horaire de votre serveur.

Préserver le sens original לצד du statut normalisé

Un statut normalisé est utile pour regrouper les expéditions de différents transporteurs, mais la description originale de l’événement peut expliquer plus précisément un problème opérationnel. Conservez les deux lorsqu’ils sont disponibles. Une vaste catégorie d’exception ne suffit pas toujours à indiquer à un agent d’assistance s’il doit vérifier une adresse, contacter le destinataire ou attendre une autre mise à jour.

N’inférez pas une garantie de livraison, une perte confirmée ou un résultat douanier particulier à partir d’un statut vague. Faites remonter le problème en fonction des informations sous-jacentes et de votre politique opérationnelle.

5. Maintenir les enregistrements à jour par interrogation ou webhooks

Récupérer les détails une seule fois suffit pour tester la connectivité, mais pas pour maintenir la visibilité de l’expédition. Votre conception de production nécessite un mécanisme de mise à jour. Confirmez les mécanismes pris en charge par le fournisseur choisi et les conditions qui leur sont associées.

Avec l’interrogation périodique, votre application demande les détails de suivi selon un calendrier. Planifiez les requêtes dans les limites documentées, évitez d’interroger à répétition des enregistrements inchangés sans raison et utilisez un backoff pour les échecs pouvant faire l’objet d’une nouvelle tentative. L’ouverture d’une page de commande par un client ne doit pas déclencher automatiquement une requête amont sans restriction ; une vue de suivi stockée peut servir la page tandis qu’un processus d’arrière-plan contrôlé l’actualise.

Si vous utilisez des webhooks, validez les requêtes entrantes au moyen du mécanisme de vérification documenté par le fournisseur. Enregistrez ou placez durablement en file les messages acceptés avant de les confirmer conformément au contrat du webhook, puis traitez les événements de manière asynchrone.

Concevez le récepteur pour tolérer les doublons et un ordre d’arrivée inattendu, sauf si le contrat de livraison documenté garantit le contraire. Utilisez un identifiant d’événement du fournisseur pour la déduplication lorsqu’il est disponible. Sinon, définissez et testez une empreinte fondée sur des champs d’événement appropriés, en reconnaissant que cette empreinte peut nécessiter des ajustements pour vos données.

Une intégration pilotée par webhook peut également utiliser une récupération contrôlée à des fins de rapprochement. Par exemple, une tâche de récupération peut vérifier les enregistrements concernés par une panne du récepteur. Il s’agit d’un modèle de résilience, et non d’une autorisation à ignorer les limites de débit ou les recommandations propres au fournisseur.

6. Transformer les informations de suivi en actions commerciales sûres

Mettez à jour votre enregistrement interne d’expédition avant de déclencher des actions destinées aux clients. Conservez un historique durable des notifications et des transitions de workflow afin qu’un événement répété ne génère pas plusieurs messages.

Associez les actions commerciales à des changements significatifs plutôt qu’à chaque réponse de l’API. Un événement de livraison nouvellement observé peut justifier une notification de livraison. Une réponse répétée contenant le même événement ne le devrait pas. Une exception peut justifier un examen interne, mais le message adressé au client doit refléter ce que l’événement indique réellement.

Définissez la manière de traiter les événements reçus après qu’une expédition a été considérée comme terminée. Ne supprimez pas l’historique des événements et ne bloquez pas définitivement toutes les mises à jour ultérieures simplement parce qu’un résumé a atteint un état terminal. Vos règles de conservation, de rapprochement et de notification doivent tenir compte des corrections légitimes sans rouvrir continuellement les workflows terminés.

Appliquer le workflow à une intégration 17TRACK

Pour une intégration de suivi personnalisée, les points de départ pertinents sont la page de l’API de suivi 17TRACK et sa documentation destinée aux développeurs. Utilisez la page produit pour évaluer l’offre et la documentation pour établir le véritable contrat d’intégration. Les pages de suivi destinées aux consommateurs ne remplacent pas les spécifications d’API.

Avant d’écrire votre adaptateur, confirmez le format d’authentification, les opérations d’enregistrement et de récupération, les règles d’identification des transporteurs, le traitement des réponses au niveau des éléments et les limites de requêtes applicables. Pour un traitement fondé sur les webhooks, confirmez également le schéma de charge utile, le processus de vérification, les exigences d’accusé de réception et le comportement en cas de nouvelle tentative.

Conservez ces détails propres au fournisseur dans un adaptateur plutôt que de disperser les hypothèses sur les champs de réponse dans tout votre système de commandes. Le reste de votre application pourra alors fonctionner avec des concepts internes tels que le résultat de l’enregistrement, le statut de l’expédition, l’historique des événements et la dernière synchronisation réussie.

Vérifications avant lancement permettant d’éviter des erreurs coûteuses

  • Enregistrement accepté mais vide : L’interface indique que les informations de suivi sont en attente, et non que le colis est en mouvement.
  • Résultat de lot mixte : Chaque expédition reçoit son propre résultat conservé.
  • Délai d’attente après l’envoi : Le processus rapproche le résultat incertain au lieu de supposer un échec.
  • Événement répété : La chronologie de l’expédition et la notification client restent dédupliquées.
  • Événement plus ancien reçu ultérieurement : L’événement est conservé sans remplacer aveuglément un résumé plus récent.
  • Service amont indisponible : La page client peut afficher le dernier résultat stocké avec une indication appropriée de fraîcheur.
  • Mauvaise correspondance du transporteur : L’enregistrement peut être corrigé par une procédure de récupération documentée.
  • Commande divisée : Chaque colis conserve son propre état de suivi et son historique des événements.
  • Exposition d’identifiants ou de charges utiles : Les journaux contiennent des références de diagnostic sans divulguer de secrets ni d’informations personnelles inutiles.

Le critère pratique d’achèvement ne consiste pas simplement à recevoir une réponse d’enregistrement réussie. Il consiste à pouvoir suivre un colis de l’envoi aux mises à jour, expliquer un résultat vide ou en échec et récupérer après une interruption du traitement sans perdre d’événements ni dupliquer les actions destinées aux clients.

FAQ

Enregistrer un numéro de suivi crée-t-il une expédition ?

Pas dans le workflow décrit ici. L’enregistrement du suivi soumet un identifiant existant à un service de suivi. La création d’une étiquette, l’achat de frais de port et la réservation auprès d’un transporteur sont des opérations distinctes, sauf si une API particulière les combine explicitement.

Pourquoi les détails de suivi sont-ils vides après la réussite de l’enregistrement ?

L’acceptation de l’enregistrement et la disponibilité des données de suivi sont deux conditions différentes. Le transporteur n’a peut-être pas encore enregistré d’événement, ou le numéro de suivi, la correspondance du transporteur ou les informations de recherche supplémentaires doivent peut-être être vérifiés. Examinez le résultat au niveau de l’élément avant de considérer l’enregistrement comme réussi.

Dois-je enregistrer l’expédition chaque fois que je récupère son statut ?

N’utilisez pas l’enregistrement répété comme mécanisme d’actualisation par défaut. Stockez l’état d’enregistrement accepté et utilisez le mécanisme de récupération ou de mise à jour documenté. Suivez les règles explicites du fournisseur concernant les corrections, la réactivation ou les envois en double.

Dois-je utiliser l’interrogation périodique ou les webhooks ?

Utilisez le mécanisme adapté au contrat d’API documenté et à vos exigences opérationnelles. L’interrogation nécessite un calendrier de requêtes contrôlé. Les webhooks nécessitent un récepteur sécurisé et durable ainsi qu’un traitement sûr vis-à-vis des doublons. Lorsqu’elles sont prises en charge, les mises à jour par webhook associées à un rapprochement ciblé peuvent fournir une voie de récupération pratique.

Puis-je utiliser un numéro de suivi comme seul identifiant d’expédition dans ma base de données ?

Utilisez plutôt un identifiant interne d’expédition. Stockez le numéro de suivi et le contexte pertinent du transporteur comme attributs de cet enregistrement. Cela facilite la gestion des commandes divisées, des numéros de suivi corrigés et des références propres au fournisseur sans modifier l’identité de votre expédition interne.

Sources

  • 17TRACK Tracking API — point d’entrée produit officiel pour évaluer une intégration d’API 17TRACK.
  • Documentation de l’API 17TRACK — référence officielle pour les formats de requête, les opérations, les réponses et les exigences d’intégration propres à l’implémentation. Le pseudocode et les suggestions de champs internes de ce guide sont des exemples de conception applicative, et non des citations de ce contrat d’API.