Skip to main content
AccueilBlogGuidesComment utiliser les API de suivi des expéditions pour envoyer des notifications de livraison proactives

Comment utiliser les API de suivi des expéditions pour envoyer des notifications de livraison proactives

17TRACK

Pour envoyer des notifications proactives de livraison avec une API de suivi des expéditions, associez chaque colis à sa commande, ingérez les mises à jour de suivi, traduisez ces mises à jour en événements pertinents pour le client, puis déclenchez des messages via votre service de notifications par e-mail, SMS ou application. Placez une file d’attente durable et des contrôles de doublons entre les données de suivi entrantes et les messages sortants afin que les mises à jour répétées ou retardées ne génèrent pas d’alertes déroutantes.

Comment utiliser les API de suivi des expéditions pour envoyer des notifications de livraison proactives

Ce guide s’adresse aux développeurs et aux équipes chargées des opérations e-commerce qui mettent en place ce workflow. L’objectif n’est pas de transférer chaque scan du transporteur, mais d’indiquer aux clients lorsqu’un changement significatif se produit, ce qu’il signifie et s’ils doivent agir.

Concevoir le workflow de notification avant de connecter l’API

Une API de suivi des expéditions fournit des informations de suivi ; c’est votre application qui décide comment les utiliser. Traitez la visibilité des expéditions et la communication avec les clients comme deux responsabilités distinctes, même si le service choisi propose les deux.

Une architecture pratique comporte six étapes :

  1. Association de la commande : associer un numéro de suivi et, si nécessaire, un identifiant de transporteur à un enregistrement d’expédition interne.
  2. Enregistrement du suivi : soumettre ou enregistrer l’expédition conformément aux exigences d’intégration du fournisseur.
  3. Ingestion des mises à jour : recevoir des rappels webhook, récupérer les mises à jour via des requêtes API ou combiner les deux approches.
  4. Traitement des événements : valider, normaliser, dédupliquer et évaluer les événements entrants.
  5. Décision de notification : choisir s’il faut notifier, qui contacter, ainsi que le canal et le modèle à utiliser.
  6. Envoi du message : envoyer la notification et enregistrer la réponse du service de messagerie.

Conservez les coordonnées des clients dans votre propre système de commandes ou de messagerie, sauf si l’intégration exige réellement leur partage. Un service de suivi n’a généralement pas besoin de l’adresse e-mail du client simplement pour permettre à votre application d’associer un événement de suivi à une commande.

1. Confirmer le contrat d’intégration

Avant d’écrire le récepteur, consultez la documentation du fournisseur concernant l’authentification, l’enregistrement des expéditions, l’identification des transporteurs, les méthodes de mise à jour prises en charge, les formats de réponse, les limites de requêtes et la gestion des erreurs. Pour les intégrations webhook, vérifiez également comment les rappels sont authentifiés, quelle réponse confirme la réception et comment les livraisons infructueuses sont traitées.

Pour une implémentation 17TRACK, commencez par la page de l’API de suivi 17TRACK et sa documentation officielle de l’API. Utilisez le contrat documenté pour votre intégration plutôt que de considérer les noms de champs illustratifs de ce guide comme des champs de requête ou de réponse 17TRACK. Confirmez la configuration des rappels, les exigences de sécurité et les limites propres au compte avant l’implémentation.

Choisissez votre méthode de mise à jour selon le contrat d’intégration :

  • Webhooks : utilisez des rappels lorsqu’ils sont pris en charge et adaptés à votre infrastructure. Ils permettent à votre application de traiter les mises à jour lorsque le fournisseur les envoie, sans demander répétitivement les informations de la même expédition.
  • Interrogation périodique : récupérez les informations de suivi selon un calendrier lorsque les rappels sont indisponibles ou inadaptés. Respectez les limites de requêtes documentées.
  • Approche combinée : utilisez les rappels pour le traitement normal et des récupérations sélectives via l’API afin de réconcilier les expéditions dont les mises à jour semblent obsolètes, si le fournisseur prend en charge ce workflow.

Ne promettez pas aux clients des notifications instantanées simplement parce que vous utilisez des webhooks. Votre application ne peut pas signaler un événement du transporteur avant que les données de suivi en amont ne le rendent disponible.

2. Créer un enregistrement d’expédition capable de gérer les commandes réelles

Utilisez un identifiant d’expédition interne comme référence principale, et non le seul numéro de suivi. Une commande peut contenir plusieurs colis, et il ne faut pas supposer que les numéros de suivi resteront toujours uniques à l’échelle mondiale.

Un enregistrement interne utile comprend :

  • L’identifiant interne de la commande et l’identifiant de l’expédition.
  • Le numéro de suivi et l’identifiant du transporteur, lorsqu’ils sont connus.
  • La référence d’expédition du fournisseur, si elle est fournie.
  • Le statut normalisé actuel et le dernier événement significatif.
  • L’heure de l’événement du transporteur, y compris son fuseau horaire ou son décalage lorsqu’il est disponible.
  • L’heure à laquelle votre système a reçu la mise à jour.
  • Une référence aux préférences de communication du client.
  • L’historique des notifications et tout workflow d’exception actif.

Stockez séparément l’heure de l’événement et l’heure de réception. Un scan effectué plus tôt peut arriver après un scan plus récent. Si votre application trie uniquement selon l’ordre d’arrivée, elle peut modifier par erreur le statut d’une expédition livrée pour la faire repasser en transit.

Pour les commandes fractionnées, associez les notifications au colis concerné. « Un colis de votre commande est arrivé » est plus précis que « Votre commande est arrivée » lorsqu’un autre colis est encore en transit.

3. Associer les événements de suivi aux décisions des clients

Les descriptions des transporteurs sont des données opérationnelles, et non des messages prêts à être envoyés aux clients. Créez une couche de normalisation qui conserve l’événement d’origine tout en lui attribuant une catégorie interne comprise par vos règles de notification.

Les catégories suivantes sont des concepts applicatifs suggérés, et non un vocabulaire universel de statuts d’API :

Catégorie interneDécision de notificationLimite de communication
Informations d’expédition reçuesEnvoyer une mise à jour de préparation uniquement si elle est utile.Ne pas laisser entendre que le transporteur est physiquement en possession du colis sur la seule base de la création de l’étiquette.
En transitEnvisager une notification lors du premier déplacement significatif.Supprimer les scans de routine dans les centres, sauf s’ils modifient la prochaine étape du client.
En cours de livraisonNotifier lorsqu’un événement pris en charge indique ce statut.Ne pas transformer le statut en heure d’arrivée garantie.
Tentative de livraison ou retrait requisEnvoyer une notification nécessitant une action.N’inclure des délais ou instructions de retrait que lorsqu’ils sont vérifiés.
Exception de livraisonÉvaluer la cause et déterminer si le client doit agir.Ne pas décrire chaque exception comme un colis perdu.
LivréEnvoyer une confirmation au niveau du colis.Ne pas inventer de destinataire, de lieu de livraison ou de preuve de livraison.

Conservez l’incertitude. Un événement non reconnu doit suivre un parcours de vérification ou de secours plutôt que d’être forcé dans la catégorie familière la plus proche. Conservez la description brute afin que le personnel d’assistance puisse effectuer des dépannages.

4. Recevoir les mises à jour sans perdre ni dupliquer le travail

Votre endpoint webhook doit valider la requête, enregistrer durablement la mise à jour acceptée et renvoyer l’accusé de réception requis par le fournisseur. Générez les messages de manière asynchrone au lieu d’attendre un service d’e-mail ou de SMS pendant la requête de rappel.

Implémentez la méthode documentée par le fournisseur pour vérifier les rappels. N’inventez pas d’en-tête de signature et ne supposez pas que tous les fournisseurs utilisent le même système d’authentification. Appliquez également HTTPS, des limites de taille des requêtes, la validation des charges utiles et des contrôles d’accès appropriés.

Un flux de traitement simplifié ressemble à ceci. Il s’agit d’opérations au niveau de l’application, et non d’un exemple fonctionnel de SDK :

receive callback
  verify request using documented provider mechanism
  validate payload
  persist accepted payload and enqueue processing atomically
  return documented acknowledgment

process queued update
  find internal shipment
  normalize relevant events
  ignore already-processed events
  evaluate chronology and state transition
  create notification job if policy permits
  commit state and job together

send notification job
  check recipient preferences and suppression rules
  submit message to messaging service
  record result and retry only when appropriate

Les étapes atomiques sont importantes. Si votre application enregistre une modification de statut mais tombe en panne avant de créer la tâche de notification, le client risque de ne jamais recevoir l’alerte. Un outbox transactionnel constitue une possibilité de conception : enregistrez la modification d’état et la tâche en attente dans la même transaction de base de données, puis laissez un worker distribuer la tâche.

Traitez explicitement les références d’expédition inconnues. Mettez-les en quarantaine pour investigation ou rapprochement au lieu de deviner quel client doit recevoir une notification.

5. Ajouter une protection contre les doublons et des contrôles chronologiques

Concevez le récepteur pour qu’il tolère les rappels répétés et les nouvelles tentatives des workers. Préférez un identifiant d’événement stable du fournisseur lorsqu’il est documenté. Sinon, créez une empreinte déterministe de l’événement à partir de champs appropriés, tels que l’identifiant interne de l’expédition, le code de l’événement, l’heure de l’événement et le lieu. Testez cette empreinte sur des charges utiles réelles avant de vous y fier.

La déduplication des événements et la suppression des notifications répondent à des problèmes différents. La déduplication empêche le traitement deux fois du même événement. La suppression empêche plusieurs scans distincts de générer essentiellement le même message client.

Définissez l’identité d’une notification autour de l’événement métier. Une confirmation de livraison peut utiliser l’identifiant de l’expédition et l’étape de livraison. Une tentative de livraison peut nécessiter une identité propre à la tentative, car une tentative ultérieure peut constituer un événement réellement nouveau.

Pour les mises à jour reçues dans le désordre, comparez les horodatages des événements et évaluez les transitions d’état autorisées. Ne supposez pas qu’un rappel ne contient qu’un nouveau scan ; vérifiez si sa structure documentée représente un événement individuel, un instantané ou un historique. Dirigez les mises à jour contradictoires vers un rapprochement au lieu d’ignorer silencieusement toutes les corrections.

6. Rédiger des messages qui expliquent la prochaine étape

Chaque notification doit indiquer le colis concerné, le changement confirmé et la prochaine étape pour le client. Incluez un lien de suivi sécurisé et une référence de commande reconnaissable. Évitez d’exposer les adresses complètes ou des informations personnelles inutiles dans les SMS et les aperçus sur écran verrouillé.

Par exemple :

  • En cours de livraison : « Votre colis de la commande {order_reference} est en cours de livraison. Suivez sa progression ici : {tracking_link}. »
  • Tentative de livraison : « Le transporteur a signalé une tentative de livraison pour votre colis. Consultez la page de suivi pour connaître les prochaines étapes disponibles : {tracking_link}. »
  • Livré : « Le transporteur a marqué votre colis de la commande {order_reference} comme livré. Consultez les détails de livraison disponibles : {tracking_link}. »

Affichez les espaces réservés uniquement à partir de données validées. Si une estimation de livraison est disponible et adaptée à l’affichage, indiquez clairement qu’il s’agit d’une estimation. Si elle est absente, omettez-la plutôt que d’inventer une date.

Pour les exceptions, distinguez un problème d’expédition d’une tâche à accomplir par le client. Une perturbation peut nécessiter uniquement une explication ; un problème d’adresse vérifié peut nécessiter une action. Ne dirigez pas les clients vers une page de paiement ou de téléversement de documents sur la seule base d’un contenu de suivi en texte libre non fiable.

Choisissez les canaux en fonction des préférences du client, des autorisations de canal, de l’urgence et des règles applicables. Vérifiez les exigences relatives au consentement, au désabonnement et aux heures silencieuses pour les juridictions et les canaux de messagerie utilisés. Séparez les notifications de service de livraison des campagnes promotionnelles au lieu de supposer que les mêmes autorisations couvrent les deux.

7. Définir ce qui se passe lorsque le suivi cesse d’être mis à jour

La communication proactive doit couvrir l’absence de progression aussi bien que les nouveaux événements, mais le silence seul ne prouve pas qu’une expédition est retardée ou perdue.

Créez une règle de suivi obsolète à partir du niveau de service, de l’itinéraire, du dernier événement significatif et de toute estimation de livraison prise en charge. Définissez les seuils à partir de vos données opérationnelles et de votre processus d’assistance plutôt que d’appliquer une période d’attente universelle à toutes les expéditions.

Lorsque cette règle se déclenche, vérifiez l’absence de traitement, rapprochez les données avec la source de suivi lorsque cela est possible et décidez s’il faut ouvrir une tâche d’assistance interne. Si vous informez le client, utilisez une formulation qui reflète ce que vous savez : « Nous n’avons pas reçu de nouvelle mise à jour de suivi » est différent de « Votre colis est perdu ».

Attribuez un responsable aux exceptions non résolues. Un système de notification qui annonce à plusieurs reprises un problème sans créer de voie de résolution peut accroître la frustration des clients.

8. Tester le parcours complet avant d’activer les envois automatiques

Exécutez d’abord le workflow en mode fantôme : ingérez des événements réels ou de test approuvés, générez les notifications proposées et examinez les résultats sans contacter les clients.

  • Rejouez un rappel identique et confirmez qu’il ne crée pas de message supplémentaire.
  • Traitez un événement de transit plus ancien après un événement de livraison et examinez l’état obtenu.
  • Testez les horodatages manquants, les statuts inconnus et les charges utiles malformées.
  • Simulez une défaillance de la base de données avant l’accusé de réception et une défaillance du worker après la persistance.
  • Testez les délais d’attente de la messagerie, y compris une réponse incertaine lorsque le service a peut-être déjà accepté le message.
  • Confirmez que les expéditions fractionnées produisent une formulation propre à chaque colis.
  • Vérifiez les destinataires désabonnés, les coordonnées invalides et la gestion des heures silencieuses.
  • Vérifiez que les liens de suivi n’exposent pas les informations de commande d’un autre client.

Surveillez les rappels acceptés, les échecs de traitement, l’ancienneté de la file d’attente, les tâches de notification, la suppression des doublons et les résultats de la messagerie. Mesurez séparément la latence de traitement à partir de l’heure de réception par votre système et l’ancienneté de l’événement du transporteur. Cette distinction permet de déterminer si une notification lente provient de la disponibilité des données en amont ou de votre propre pipeline.

Commencez par un petit ensemble d’étapes bien comprises. N’élargissez les règles qu’après accord des équipes d’assistance et des opérations sur le fait que les messages sont exacts, exploitables et utiles.

FAQ

Une API de suivi des expéditions envoie-t-elle automatiquement des e-mails ou des SMS ?

Pas nécessairement. L’accès aux données de suivi et la messagerie client sont deux fonctionnalités distinctes. Consultez le périmètre documenté du service. Dans une intégration personnalisée, votre application peut traiter les mises à jour de suivi et envoyer des notifications via un service de messagerie distinct.

Dois-je informer les clients de chaque scan de suivi ?

Généralement non. Donnez la priorité aux étapes importantes et aux événements nécessitant une action. Plusieurs scans dans des centres peuvent correspondre à un transit normal sans modifier ce que le client doit savoir. Conservez l’historique détaillé sur la page de suivi.

Puis-je garantir des notifications de livraison en temps réel ?

Vous pouvez définir et surveiller un objectif de traitement après que votre système a reçu une mise à jour. Vous ne pouvez pas garantir le moment où un transporteur enregistrera ou publiera un scan. Décrivez le service en termes qui reflètent cette dépendance.

Comment empêcher l’envoi de messages de livraison en double ?

Utilisez une déduplication persistante des événements, une identité de notification distincte pour chaque étape métier et une création transactionnelle des tâches. Lorsque votre service de messagerie prend en charge l’idempotence, utilisez-la comme protection supplémentaire. Un simple contrôle des doublons en mémoire ne survivra pas aux redémarrages ni à l’utilisation de plusieurs workers.

Que se passe-t-il si le transporteur corrige un statut livré ?

Conservez les deux événements et réconciliez l’état de l’expédition. Si la correction affecte matériellement le client, envoyez une correction claire ou transmettez-la à l’assistance conformément à votre politique. Ne rendez pas définitivement irréversible le statut livré simplement pour simplifier le code.

Sources

Les ressources officielles suivantes constituent les références d’implémentation pour l’intégration 17TRACK évoquée ci-dessus. Le schéma interne, les règles de notification et le flux de traitement de ce guide sont des recommandations architecturales, et non des contrats d’API cités.

  • API de suivi 17TRACK — point de départ officiel pour évaluer l’intégration de l’API.
  • Documentation de l’API 17TRACK — référence pour les formats de requêtes propres au fournisseur, l’authentification, les opérations de suivi et les exigences d’intégration.