Mapping de données API : construire vos correspondances de champs

Un mapping de données API décrit comment chaque information d’un logiciel devient une information exploitable dans un autre. Il indique le champ source, le champ cible, la transformation autorisée et le traitement d’une valeur absente ou refusée.

Un SKU « 00042 » converti en nombre perd ses zéros. Un statut « expédié » peut masquer une livraison partielle. Une mise à jour de contact peut écraser une adresse de facturation si les rôles ne sont pas distingués. Ces écarts peuvent passer un contrôle de format tout en produisant un mauvais résultat métier.

Le livrable à construire est une table de correspondance accompagnée de cas de test : ce qui passe, ce qui est conservé et ce qui doit être refusé. Les exemples de champs, de valeurs et de messages ci-dessous sont fictifs. Ils ne reproduisent ni le format d’un éditeur ni des données client.

Le mapping intervient après la vérification des interfaces et avant la recette. Notre guide d’intégration API replace ces étapes dans le projet. Si les logiciels et les échanges sont déjà identifiés, notre accompagnement en intégration API aide à délimiter les règles et le premier périmètre à réaliser.

1. Construire un dictionnaire de correspondance

Le mapping commence par une opération précise : publier une variante produit, créer un compte ou mettre à jour une expédition. Pour chaque champ utilisé par cette opération, relevez son nom, son type, son sens, son unité éventuelle et les conditions dans lesquelles il est obligatoire. Deux propriétés appelées status peuvent décrire des étapes différentes.

Vérifiez ensuite ce que l’interface destinataire permet réellement de lire et d’écrire. Un champ visible dans le logiciel peut être absent de son API, calculé automatiquement ou modifiable seulement dans certains états. La documentation et un essai avec les droits prévus doivent confirmer le contrat ; un nom de colonne supposé compatible ne suffit pas.

Écrire une règle que l’on pourra vérifier

Une ligne de mapping utile contient la donnée reçue, la donnée attendue et la décision en cas d’écart. « Convertir la quantité » laisse une question ouverte. « Convertir les cartons en unités avec le conditionnement validé pour cet article, refuser si ce conditionnement est inconnu » fournit une règle testable. Le facteur de conversion reste une donnée métier à confirmer.

Ajoutez le responsable de la règle et un exemple de résultat. Le métier valide le sens ; l’équipe d’intégration met en œuvre la transformation ; le responsable du logiciel confirme les restrictions de son interface. Le guide sur la source de vérité et la gouvernance du mapping approfondit cet arbitrage. Ici, la table sert à traduire les décisions en correspondances et en essais.

2. Passer du champ source au test de recette

Cette grille fictive regroupe six informations dans quatre colonnes pour conserver une lecture claire : objet et valeur source, cible et transformation, refus, résultat attendu. Adaptez les noms et les obligations au contrat de vos logiciels avant de l’utiliser.

Illustrer la transformation sans inventer un format fournisseur

Le message suivant représente une entrée d’essai pour notre exemple. Le conditionnement de douze unités par carton est une hypothèse pédagogique. Les propriétés sont choisies pour expliquer la transformation, pas pour appeler une API réelle.

{
  "source_customer": "CRM-EXEMPLE-17",
  "sku": "00042",
  "quantity": 2,
  "unit": "carton",
  "units_per_carton": 12
}

La règle validée dans cet exemple conserve le SKU « 00042 », recherche le compte correspondant et produit vingt-quatre unités. Elle doit refuser de produire une quantité si le conditionnement manque. Le résultat du test porte sur le compte, l’article, la quantité et l’unité retrouvés à destination ; obtenir une réponse HTTP réussie ne remplace pas ces contrôles.

3. Conserver les SKU, variantes et unités

Identifiez ce que chaque référence désigne : produit parent, variante stockable, référence fournisseur ou annonce de canal. Un identifiant de publication peut disparaître lorsque le canal recrée une annonce ; il ne doit pas devenir par défaut l’identité permanente de l’article dans tous les systèmes.

Conservez une correspondance explicite entre l’objet source et l’objet cible. Son périmètre peut inclure le logiciel, le compte, le dépôt ou le type d’objet selon votre organisation. La concaténation de quelques chaînes ne garantit pas à elle seule l’unicité : il faut vérifier les domaines de valeurs, les séparateurs, les collisions et les contraintes du stockage choisi.

Traiter une référence comme une référence

Un code article composé de chiffres reste parfois une chaîne métier. Convertir « 00042 » en nombre, retirer un tiret ou supprimer un espace peut rendre deux références distinctes indiscernables. La normalisation autorisée doit être écrite. Conservez l’entrée reçue lorsque cela est nécessaire au diagnostic, avec les protections et la durée adaptées aux données concernées.

Pour une variante, testez aussi la relation avec son parent et les attributs qui la distinguent. Une référence trouvée mais reliée à la mauvaise taille peut produire une opération techniquement acceptée et un stock incorrect. Les essais doivent inclure une variante existante, une variante inconnue et une correspondance ambiguë.

Rendre les conversions d’unité explicites

Une quantité sans unité est insuffisante pour décider d’une transformation. Confirmez si la source exprime des unités, des lots, un poids ou un conditionnement. Le facteur utilisé peut dépendre de l’article et évoluer ; sa provenance doit pouvoir être retrouvée lors d’un contrôle.

Pour un montant, documentez la devise, les taxes et la règle d’arrondi retenue. Pour une date, vérifiez le contexte horaire et le sens du champ. Évitez de convertir silencieusement une information dont la convention n’est pas confirmée : un refus explicite peut être plus simple à corriger qu’une valeur plausible déjà propagée.

4. Distinguer compte, contact et adresses

Un compte commercial, une entité juridique, un contact et un utilisateur de portail ne sont pas nécessairement le même objet. Une entreprise peut avoir plusieurs sites et plusieurs personnes avec des droits différents. Le mapping doit préciser les relations à conserver plutôt que réduire tous ces rôles à une fiche « client ».

Avant de créer une cible, cherchez la correspondance autorisée par le contrat : identifiant externe, table de liaison ou autre règle validée. Un nom proche ou une adresse électronique commune ne suffisent pas toujours à autoriser une fusion. En cas d’ambiguïté, rendez les candidats et la décision attendue visibles au responsable de la donnée.

Séparer les usages d’une adresse

Une correction de livraison ne doit pas modifier automatiquement une adresse de facturation. Déterminez si la cible attend une adresse partagée, une copie propre à la commande ou un objet indépendant. Ce choix conditionne les effets d’une mise à jour sur les documents et sur les opérations déjà engagées.

Les champs obligatoires dépendent du pays, du fournisseur et du parcours. Un code postal ne constitue pas une exigence universelle pour toutes les adresses du monde. Vérifiez les règles officielles du service appelé, préservez les compléments utiles et testez les caractères réellement rencontrés dans vos données.

Le projet d’espace client Corim illustre la distinction entre compte, licence et droits du portail. Ce contexte aide à discuter du sens des objets ; il ne prouve pas que les noms de champs fictifs de ce guide existent dans l’ERP Colline.

5. Traduire un statut sans perdre une étape

Commencez par définir ce que chaque statut confirme. « Validé » peut concerner le dossier, la commande, le paiement ou la préparation. Ces confirmations ne sont pas interchangeables. La table doit associer un état à un objet et à une transition autorisée, avec les informations nécessaires pour interpréter cette transition.

Une expédition partielle fournit un test utile. Si une ligne est expédiée et une autre attendue, un statut global « terminé » peut masquer le travail restant. Vérifiez si l’interface transporte les quantités et les objets partiels, puis contrôlez la représentation obtenue dans la destination.

Prévoir les états inconnus et les événements tardifs

Un nouvel état du fournisseur ne doit pas être traduit silencieusement vers une valeur rassurante. Prévoyez le refus, la mise en attente ou l’alerte autorisée lorsque la correspondance manque. La personne qui valide un nouvel état doit examiner ses conséquences sur les étapes suivantes.

Pour un événement tardif, la date d’arrivée ne suffit pas toujours à identifier la donnée la plus récente. Utilisez la version, la séquence ou les garanties de l’interface lorsqu’elles existent. Un webhook ne prend pas automatiquement priorité sur un batch ; l’autorité de la donnée et l’état déjà confirmé restent à vérifier.

6. Arbitrer les écritures et les valeurs absentes

Pour chaque champ partagé, désignez le système qui peut fournir la valeur de référence, les systèmes qui peuvent l’enrichir et ceux qui doivent seulement la consulter. Cette autorité peut varier entre l’adresse, le tarif et l’état logistique. Une règle unique par logiciel est parfois trop large.

Définissez ensuite ce qui doit se passer en cas d’écart : conserver, remplacer, compléter, refuser ou demander une validation. Si deux logiciels peuvent modifier la même information, testez les corrections concurrentes et les données plus anciennes reçues après une modification manuelle.

Distinguer absence, valeur nulle et effacement

Un champ absent n’exprime pas forcément une demande d’effacement. Une valeur nulle ou une chaîne vide peut aussi avoir un sens différent selon l’API et l’opération. Écrivez le comportement observé dans la documentation et dans les essais, au lieu d’utiliser une conversion unique pour tous les messages.

Le format JSON Merge Patch définit notamment un traitement particulier de la valeur nulle pour retirer un membre. Cette règle concerne ce format ; elle ne doit pas être étendue à tous les appels PATCH ou à toutes les API. La validation de structure, par exemple avec JSON Schema, complète ces contrôles sans décider à votre place du sens métier d’un effacement.

7. Tester un refus puis corriger sans écraser

Un jeu de recette doit permettre de retrouver le même objet avant et après le traitement. Préparez une entrée normale, une référence inconnue, une valeur absente, une ambiguïté et une modification concurrente. Pour chaque entrée, écrivez le résultat attendu et la décision que le système doit rendre visible.

• Référence inconnue. Refuser la transformation concernée, conserver le lien avec l’objet d’origine et indiquer le référentiel à corriger.
• Unité absente. Ne pas fabriquer un facteur de conversion ; demander la donnée ou la validation prévue.
• Champ obligatoire manquant. Expliquer l’obligation propre au contrat destinataire et la personne chargée de compléter la donnée.
• Statut non traduit. Conserver l’incertitude et empêcher une transition finale non justifiée.
• Cible déjà modifiée. Vérifier sa version et l’autorité du champ avant d’appliquer une entrée plus ancienne.

Organiser une correction traçable

Une mise en attente utile conserve la référence source, la destination, la règle appliquée, la cause du refus et l’action autorisée. Les métadonnées de diagnostic peuvent rester dans une enveloppe ou un journal interne ; elles ne sont pas nécessairement des propriétés à envoyer au fournisseur.

Après correction, confirmez ce qui sera relancé : une transformation, une mise à jour ou une création. Le mapping ne protège pas à lui seul contre les effets répétés d’une écriture. Le guide de diagnostic d’une opération API bloquée aide à vérifier l’état distant avant une reprise ; celui sur l’idempotence et les doublons métier approfondit les garanties nécessaires.

8. Faire évoluer le mapping et ses reprises

La prochaine modification peut venir d’un champ ajouté, d’une variante commerciale, d’une nouvelle obligation ou d’un changement de sens. Conservez les règles validées, leurs exemples et la date de leur évolution. Il faut pouvoir comprendre avec quelle transformation un objet ancien a été traité.

Avant de réutiliser une ancienne entrée, décidez si elle doit être relue avec sa règle d’origine ou avec une règle corrigée. La réponse dépend du défaut à réparer et des effets déjà produits. Une version de mapping retrouvée dans les traces éclaire cette décision ; elle ne l’automatise pas sans examen.

Avancer par livrables observables

1. Valider l’opération prioritaire et la source de chaque champ utilisé.
2. Écrire la table, les transformations autorisées et les refus à prévoir.
3. Exécuter les exemples représentatifs avec les accès réellement disponibles.
4. Faire vérifier les objets obtenus par le responsable métier.
5. Documenter la correction et la reprise, puis élargir le périmètre lorsque ces contrôles sont maîtrisés.

La durée dépend notamment des interfaces, de la qualité des données et des validations. Le calendrier doit s’appuyer sur ces validations et sur les capacités disponibles. Mesurez les refus par cause et utilisez ces observations pour décider quelle règle ou quel référentiel reprendre.

9. Retrouver les correspondances dans un projet réel

Le projet 1UP Distribution entre Wix, ShippingBo et Odoo illustre une chaîne où la commande, son exécution logistique et les objets de gestion doivent rester reliés. La conservation des références permet de suivre les étapes et de cibler les échanges à vérifier.

Les sorties vers le canal de vente et vers l’ERP ont des contrats distincts. Cette distinction explique pourquoi une seule représentation ne suffit pas toujours à tous les destinataires. La fiche projet documente ce contexte ; la table de ce guide reste un support pédagogique et ne reproduit pas les données ou les messages du client.

10. Approfondir gouvernance, données et diagnostic

Le guide sur la source de vérité et la dette de mapping traite les responsabilités à arbitrer avant les transformations. Les contrats de données API prolongent la discussion lorsqu’un changement doit rester compatible avec plusieurs consommateurs.

Pour une entrée refusée ou un traitement interrompu, revenez au diagnostic avant reprise. Pour replacer le dictionnaire dans le projet complet, le guide d’intégration API relie interfaces disponibles, choix d’architecture et recette.

11. Conclusion : une correspondance se valide sur son résultat

Commencez par un objet et une opération. Pour chaque donnée nécessaire, écrivez la source, la cible, la transformation et la réponse attendue lorsque l’entrée ne convient pas.

Vérifiez les références, les rôles et les unités avant d’accélérer les échanges. Un résultat lisible dans le logiciel destinataire constitue une preuve plus utile qu’une transformation simplement exécutée sans erreur.

Conservez les exemples validés et les décisions de correction. Ils permettront de vérifier une nouvelle règle, une donnée ancienne ou un refus sans recommencer le cadrage à chaque incident.

Pour construire ce premier dictionnaire avec les équipes métier et les responsables des logiciels, notre accompagnement en intégration API permet de cadrer les correspondances, les essais et les conditions de maintenance.