Comment connecter les données de suivi des expéditions à un Oms : mappage des commandes et règles de synchronisation
Pour connecter les données de suivi des expéditions à un système de gestion des commandes (OMS), associez chaque colis suivi à un enregistrement d’expédition interne, puis reliez cette expédition à sa commande et à ses lignes de traitement. Recevez les mises à jour de suivi via l’interface prise en charge par le fournisseur, conservez les événements d’origine et appliquez des règles explicites pour les doublons, les mises à jour tardives, le statut de l’expédition et la finalisation de la commande. N’utilisez pas un numéro de suivi seul comme identifiant de commande et ne laissez pas un seul événement de livraison clôturer automatiquement une commande composée de plusieurs colis.

Ce guide s’adresse aux ingénieurs chargés des intégrations et aux équipes chargées des opérations e-commerce qui mettent en œuvre cette connexion. La conception recommandée sépare les observations du transporteur des décisions métier : les données de suivi décrivent le parcours d’un colis, tandis que l’OMS détermine ce que ce parcours signifie pour le traitement des commandes, la communication avec les clients et la clôture des commandes.
Définir quel système est responsable de chaque enregistrement
Avant de créer une connexion API, définissez les responsabilités avec l’administrateur de l’OMS, l’équipe de traitement des commandes et l’équipe du service client. Dans le cas contraire, une intégration techniquement réussie peut malgré tout écraser des données métier valides.
- OMS : est responsable des commandes, des lignes de commande, des quantités requises, des annulations et des règles de finalisation des commandes.
- Système de traitement des commandes : est responsable des enregistrements d’expédition ou de colis qu’il crée, notamment des affectations de colisage et des attributions d’étiquettes. Il peut s’agir de l’OMS lui-même ou d’un système d’entrepôt distinct.
- Fournisseur de suivi : fournit les observations de suivi et les classifications de statut définies par le fournisseur.
- Couche d’intégration : est responsable des correspondances entre identifiants, du traitement des événements, de la normalisation, de la gestion des nouvelles tentatives et des enregistrements d’audit de synchronisation.
Considérez ces éléments comme des limites recommandées, et non comme des hypothèses concernant vos logiciels. Documentez les exceptions. Par exemple, si l’entrepôt peut remplacer une étiquette d’expédition, l’intégration doit recevoir une mise à jour explicite de ce système au lieu de supposer qu’un nouveau numéro observé remplace l’ancien.
Créer la correspondance commande-colis avant de synchroniser les statuts
Une relation pratique est la suivante : commande → traitement → colis → attribution du suivi. Votre OMS peut utiliser des noms différents ou combiner certains de ces enregistrements. Préservez les relations même si la structure de la base de données diffère.
Une commande peut comporter plusieurs traitements, et un traitement peut contenir plusieurs colis. Un colis peut également recevoir une nouvelle attribution de suivi ou un identifiant de dernier kilomètre associé. Ces identifiants ne doivent pas créer de quantités commandées supplémentaires.
| Enregistrement | Champs recommandés | Objectif |
|---|---|---|
| Commande | ID du locataire ou du magasin, ID de commande OMS immuable | Sépare les marchands et évite de dépendre des numéros de commande affichés. |
| Traitement | ID du traitement, ID de commande, ID et quantités des lignes affectées | Identifie les articles achetés en cours de traitement. |
| Colis | ID de colis interne, ID de traitement, affectations du colis lorsqu’elles sont disponibles | Fournit une identité stable, indépendante des étiquettes de suivi. |
| Attribution du suivi | ID d’attribution, ID de colis, compte du fournisseur, identifiant du transporteur, numéro de suivi, période d’activité | Relie les observations de suivi entrantes au colis correct et au cycle de vie de l’attribution. |
Faire correspondre les mises à jour à l’aide d’une table de correspondance enregistrée
Lorsqu’une expédition est créée, enregistrez ses identifiants internes avant de l’inscrire au suivi. Stockez tout ID d’enregistrement de suivi fourni par le fournisseur et renvoyé par le processus d’inscription documenté. Si le fournisseur prend en charge une référence marchand, utilisez une référence interne opaque et conservez la correspondance localement.
Pour les mises à jour entrantes, résolvez d’abord l’ID d’enregistrement du fournisseur enregistré dans le compte fournisseur et le locataire appropriés. Si cet identifiant n’est pas disponible, utilisez la combinaison documentée du numéro de suivi, de l’identité du transporteur, du contexte du compte et de l’historique des attributions. Considérez cela comme une stratégie de recherche, et non comme une garantie que cette combinaison est globalement unique.
N’effectuez pas de correspondance à partir du nom du client, de son adresse e-mail ou d’un numéro de commande affiché sans contexte. Conservez les numéros de suivi sous forme de chaînes afin de préserver les zéros initiaux. Évitez de supprimer des caractères ou de modifier la casse, sauf si le contrat du transporteur ou du fournisseur concerné autorise cette normalisation.
Si une recherche ne renvoie aucune correspondance ou plusieurs correspondances possibles, placez la mise à jour en quarantaine pour investigation. Un événement non résolu est plus sûr qu’une mise à jour certaine de la commande du mauvais client.
Gérer les commandes fractionnées sans inventer d’affectations de colis
Considérons une commande illustrative contenant trois unités. Le colis A transporte deux unités et le colis B en transporte une. La livraison du colis A signifie que deux unités disposent d’une preuve de livraison ; cela ne signifie pas que toute la commande est livrée.
Si le système de traitement enregistre uniquement que les deux colis appartiennent au même traitement, n’inventez pas d’affectations au niveau de l’unité. Vous pouvez tout de même calculer si tous les colis requis sont livrés, mais le suivi de la livraison au niveau de l’article doit rester indisponible ou explicitement incertain tant que les données d’affectation n’existent pas.
Connecter l’API de suivi via une couche d’ingestion durable
Utilisez un pipeline qui sépare la communication avec le fournisseur des écritures dans l’OMS :
Création de l’expédition → inscription au suivi → mise à jour entrante ou récupération planifiée → stockage durable de l’événement → correspondance et normalisation → mise à jour de l’OMS → rapprochement
Pour une implémentation 17TRACK, la page produit de l’API de suivi et la documentation officielle de l’API constituent les points de départ pertinents. Confirmez l’interface d’inscription applicable, les identifiants des transporteurs, les options de transmission des mises à jour, les exigences d’authentification, les définitions des statuts et les limites du compte avant d’implémenter l’adaptateur. Le modèle de données présenté dans ce guide est une recommandation d’intégration ; il ne prétend pas que 17TRACK utilise ces noms de champs ou fournisse un connecteur natif pour votre OMS.
Si le fournisseur sélectionné prend en charge les webhooks, authentifiez les requêtes entrantes à l’aide du mécanisme documenté et stockez durablement les messages acceptés avant de les confirmer. Gardez les opérations OMS lentes en dehors du chemin de requête. Suivez le contrat réel d’accusé de réception et de nouvelle tentative du fournisseur au lieu de supposer un corps de réponse ou un délai d’expiration particulier.
Si l’interrogation est nécessaire, stockez la progression de récupération lorsque l’API le permet, contrôlez la concurrence et respectez les limites de débit documentées. Ni la réception d’un webhook ni la réussite d’une requête d’interrogation ne prouvent que l’OMS a été mis à jour ; enregistrez ces résultats séparément.
Définir des règles de synchronisation qui résistent aux nouvelles tentatives et aux événements tardifs
1. Rendre le traitement idempotent
Le traitement deux fois de la même observation ne doit pas dupliquer une expédition, augmenter deux fois les quantités ni envoyer à nouveau la même notification au client. HTTP ne rend pas une opération POST arbitraire idempotente ; l’intégration doit mettre en œuvre une protection contre les doublons. La RFC 9110 explique l’idempotence des méthodes HTTP.
Utilisez un ID d’événement stable du fournisseur lorsqu’il est documenté et disponible. Sinon, définissez une empreinte à partir de l’ID d’attribution et des champs pertinents de l’événement, tels que l’horodatage de l’événement, le statut source et le lieu. Documentez la possibilité de collisions ou de modifications des descriptions d’événements. Conservez l’observation brute même lorsqu’elle ne produit aucune autre action dans l’OMS.
Protégez chaque effet secondaire séparément. Par exemple, l’écriture d’un statut dans l’OMS et l’envoi d’une notification par e-mail nécessitent leurs propres contrôles de déduplication. Utilisez une outbox transactionnelle ou un enregistrement de travail durable équivalent afin qu’un plantage du processus ne laisse pas un événement accepté sans mise à jour planifiée.
2. Stocker séparément l’heure de l’événement et l’heure de réception
L’heure à laquelle un événement s’est produit et l’heure à laquelle votre intégration l’a reçu répondent à des questions différentes. Stockez les deux, ainsi que la représentation originale de l’horodatage et tout décalage de fuseau horaire fourni. N’attribuez pas silencieusement le fuseau horaire de l’entrepôt à un événement dont le fuseau est inconnu.
Une analyse de transit reçue tardivement doit normalement enrichir l’historique sans remplacer un état livré plus récent. Toutefois, les horodatages seuls sont insuffisants : un fournisseur peut émettre une correction et les événements peuvent contenir des informations temporelles incomplètes. Utilisez les champs de séquence ou de révision documentés lorsqu’ils sont disponibles, ainsi qu’une politique de correction explicite.
3. Normaliser les statuts sans effacer les détails de la source
Créez un petit vocabulaire interne compris par l’OMS, comme en attente d’acceptation par le transporteur, en transit, en cours de livraison, livré, exception et en retour. Faites correspondre les statuts documentés du fournisseur à ce vocabulaire. Il s’agit de catégories internes suggérées, et non de définitions universelles des transporteurs.
Stockez le code de statut d’origine, la description, le lieu de l’événement, la référence de l’enregistrement du fournisseur et la version de la règle de correspondance. Une valeur non correspondante doit créer une situation nécessitant un examen plutôt que d’être définie par défaut comme livrée ou échouée. La création d’une étiquette ne doit pas être considérée comme une preuve de prise en charge physique par le transporteur, sauf si l’événement source permet explicitement cette interprétation.
4. Utiliser des règles de transition plutôt qu’un classement numérique simple
Les états d’une expédition ne suivent pas toujours une ligne droite. Une exception peut être suivie d’un transit normal, et une tentative de livraison n’est pas une livraison. Le retour peut commencer après un événement de livraison antérieur.
- Autoriser la résolution d’une exception lorsque des éléments ultérieurs indiquent une reprise du parcours.
- Empêcher une analyse historique ordinaire de remplacer silencieusement un état livré.
- Autoriser une correction documentée via un parcours de révision contrôlé.
- Suivre séparément les retours et la finalisation de l’expédition sortante lorsque l’OMS le permet.
- Orienter les éléments ambigus ou contradictoires vers une file opérationnelle.
Versionnez ces règles. Lorsqu’une correspondance change, décidez si elle s’applique uniquement aux nouveaux événements ou si les enregistrements historiques nécessitent un recalcul contrôlé.
Calculer le statut de la commande à partir des obligations de traitement requises
Le statut du colis et celui de la commande doivent être des champs distincts. Un colis marqué comme livré fournit une preuve pour ce colis ; la finalisation de la commande dépend des quantités requises restantes et de votre politique métier.
Par défaut, il est utile de marquer une commande comme entièrement livrée uniquement lorsque toutes les quantités nécessitant une livraison disposent d’une preuve de livraison valide au niveau du colis et qu’aucune affectation requise ne reste non résolue. Excluez les quantités annulées conformément aux règles d’annulation de l’OMS. Gérez les articles numériques, les commandes à retirer et les autres obligations sans expédition selon leurs propres conditions de finalisation.
Les expéditions de remplacement nécessitent des relations explicites. Si un colis perdu est remplacé, déterminez si le remplacement se substitue à l’obligation de livraison initiale. Sinon, le colis initial peut bloquer indéfiniment la finalisation, ou les deux colis peuvent être comptabilisés dans le traitement. Enregistrez la décision au lieu de la déduire uniquement du statut de suivi.
Gardez la finalisation de la livraison séparée de la clôture financière, de l’éligibilité au remboursement et de la résolution des litiges. Un événement de livraison du transporteur ne doit pas autoriser automatiquement un remboursement ni régler une réclamation client.
Récupérer après les échecs sans perdre la piste d’audit
Relancez les échecs temporaires avec un délai progressif limité et en tenant compte des recommandations documentées concernant les nouvelles tentatives. Séparez les échecs temporaires de connexion des identifiants invalides, des identifiants expirés, des erreurs d’autorisation et des incompatibilités de schéma. Ces dernières nécessitent une action corrective, et non des nouvelles tentatives infinies.
Gérez une file de travaux en échec contenant le locataire concerné, le colis, la référence de l’événement, l’opération tentée, la classification de l’erreur et l’action suivante. Consignez suffisamment de contexte pour permettre l’investigation sans copier de données client ou d’identifiants inutiles dans les journaux.
Exécutez un rapprochement en complément du parcours normal de mise à jour. Examinez les expéditions actives dont les informations de suivi sont obsolètes, les événements acceptés dont les écritures OMS ont échoué, les observations sans correspondance et les écarts entre l’état calculé par l’intégration et celui de l’OMS. Choisissez la fréquence d’examen en fonction des engagements de livraison, des limites de l’API et du risque opérationnel plutôt que d’appliquer un calendrier universel arbitraire.
Attribuez les responsabilités : l’ingénierie gère l’ingestion et les échecs d’écriture ; les opérations de traitement résolvent les relations de colis manquantes ; le service client examine les exceptions nécessitant une communication avec le client. Une file sans responsable désigné n’est qu’un emplacement de stockage.
Tester la correspondance et les règles métier avant le lancement
Utilisez des jeux de données contrôlés et un déploiement limité en production. Testez les cas suivants à la fois par rapport à l’historique des événements et à l’enregistrement OMS obtenu :
- Une commande composée d’un seul colis progresse normalement jusqu’à la livraison.
- Une commande fractionnée comporte un colis livré et un autre encore en mouvement.
- Le même événement est reçu plusieurs fois sans effets secondaires en double.
- Une analyse de transit plus ancienne arrive après la livraison.
- Un transporteur ou un statut inconnu arrive dans la file d’examen.
- Une étiquette est remplacée sans créer une autre obligation de traitement.
- Une expédition de remplacement se substitue au colis initial conformément à une règle approuvée.
- L’OMS est indisponible après l’acceptation d’un événement.
- Un processus redémarre entre une écriture OMS et son accusé de réception.
- Le même numéro de commande affiché existe dans deux magasins sans correspondance entre locataires.
Lancez la solution lorsque chaque événement accepté possède un résultat de traitement traçable, que les correspondances ambiguës ne peuvent pas mettre automatiquement à jour les commandes et que les opérateurs peuvent rejouer les travaux en échec en toute sécurité. Ces critères d’acceptation sont plus utiles que la simple démonstration de la réussite d’une requête API.
FAQ
Puis-je relier directement les numéros de suivi aux commandes ?
Pour un flux strictement composé d’un seul colis, une relation directe peut initialement suffire. Utilisez néanmoins une identité d’expédition interne entre la commande et l’attribution du suivi. Elle fournit une voie de migration pour les expéditions fractionnées, le réétiquetage et les remplacements sans modifier la signification de l’enregistrement de commande.
L’intégration doit-elle utiliser des webhooks ou l’interrogation ?
Utilisez le mécanisme de transmission pris en charge par le fournisseur et compatible avec votre infrastructure. Les webhooks peuvent réduire les récupérations répétées, tandis que l’interrogation peut prendre en charge les flux fondés sur la récupération et le rapprochement lorsqu’ils sont disponibles. Aucune de ces approches ne supprime la nécessité d’un stockage durable, de la gestion des doublons et de la récupération après incident.
Que faire lorsqu’un événement de suivi ne correspond à aucune commande ?
Stockez-le dans une file d’événements sans correspondance et examinez l’enregistrement d’inscription, le contexte du locataire, l’identité du transporteur et le moment de création de l’expédition. Ne créez pas automatiquement une commande et ne rattachez pas l’événement à un client plausible. Rejouez-le une fois la correspondance corrigée.
Les notifications de livraison doivent-elles provenir de l’OMS ou du système de suivi ?
Choisissez un responsable pour chaque type de notification et chaque déclencheur. Si deux systèmes peuvent envoyer le même message, désactivez un parcours ou partagez un registre durable des notifications. Décidez également si un message concerne un seul colis ou la commande complète, en particulier pour un traitement fractionné.
Un statut d’exception signifie-t-il que la commande a échoué ?
Non. Une exception est une observation nécessitant une interprétation, et non nécessairement un résultat définitif. Conservez le motif, surveillez les événements ultérieurs et utilisez votre politique d’escalade pour déterminer quand les opérations doivent intervenir.
Sources
- API de suivi 17TRACK — référence officielle du produit et point de départ de l’intégration API.
- Documentation de l’API 17TRACK — référence d’implémentation du contrat spécifique au fournisseur ; vérifiez les interfaces applicables et les exigences du compte avant le déploiement.
- RFC 9110, section 9.2.2 : méthodes idempotentes — sémantique HTTP permettant de distinguer l’idempotence des méthodes de la protection contre les doublons au niveau de l’application.


