Écrire une spécification d'intégration quetout le monde lit

Une spécification d'intégration, c'est le document qui dit comment deux logiciels se parlent : ici un ERP et un site marchand. Sur le papier, tout le monde est d'accord pour qu'elle existe. Dans les faits, elle est souvent écrite une fois, envoyée en pièce jointe, puis plus personne ne l'ouvre. Chacun garde sa propre version en tête, et les écarts apparaissent en recette.

J'en ai écrit et fait vivre en mission, et je construis aussi des machines de contenu qui publient des articles sans relecture préalable. Les deux métiers se ressemblent plus qu'on ne le croit : dans les deux cas, un document doit être assez précis pour qu'un outil ou une autre équipe agisse dessus sans vous appeler. Ce qui suit, c'est ma méthode : ce que je mets dans le document, et ce que j'emprunte à mes pipelines pour qu'il reste lu.

01Pourquoi la plupart des spécifications d'intégration ne sont pas lues

Vous l'avez peut-être vécu : la première raison est simple, elles sont écrites pour une seule des deux équipes. Le document de l'éditeur de l'ERP parle de modèles et de champs, celui de l'équipe web parle de pages et de paniers. Personne ne se retrouve dans le texte de l'autre.

La deuxième raison, c'est qu'elles sont trop longues au mauvais endroit. Trente pages sur le contexte du projet, et trois lignes sur ce qui se passe quand une commande arrive avec une référence inconnue. Or c'est exactement la question que votre développeur se posera un mardi soir.

La troisième raison, c'est qu'elles ne bougent pas alors que le projet bouge. Ce n'est pas propre aux petits projets. Dans une conférence publiée par l'OpenAPI Initiative, Vasco Veloso part du même constat : les spécifications d'API publiées sont souvent incomplètes, sans exemples ou simplement périmées, parce que les tenir à jour est un travail manuel qu'on oublie dans l'urgence de livrer. Un document faux est pire qu'aucun document : il donne raison à celui qui l'a lu en dernier.

02Ce que doit contenir une spécification d'intégration

Je découpe toujours le document en flux, et je vous conseille d'en faire autant. Un flux, c'est un échange précis : les commandes du site vers l'ERP, les stocks de l'ERP vers le site, les statuts d'expédition, les fiches produits. Chaque flux a sa propre fiche, toujours construite de la même façon, pour qu'on sache où chercher.

La fiche d'un flux, en huit questions

1. Quel est le déclencheur ? Une commande validée, une heure fixe, un changement de stock.
2. Qui est propriétaire de la donnée ? Un seul système fait foi pour chaque information. Si le stock existe dans les deux, il faut écrire lequel gagne.
3. Dans quel sens va le flux, et avec quelle fréquence ?
4. Quels champs passent, et à quoi correspondent-ils de l'autre côté ? C'est le tableau de correspondance, j'y reviens plus bas.
5. Quel format pour les dates, les montants, les mesures ? Les standards publics d'API du gouvernement britannique recommandent par exemple l'ISO 8601 pour les dates et l'UTF-8 pour le texte.
6. Que se passe-t-il en cas d'erreur ? Quel message, qui est prévenu, est-ce que l'échange est rejoué automatiquement ?
7. Comment vérifie-t-on que le flux marche ? Un cas de test par règle, avec des données de test et non des données réelles.
8. Quelle version de quelle interface utilise-t-on ?

Une fiche incomplète ne passe pas

Dans mes machines de contenu, aucun article ne s'écrit avant que son brief soit validé par une commande. S'il manque une source, une question ou un angle, elle répond « BRIEF REFUSÉ » avec la liste des manques. J'applique la même règle aux fiches de flux : tant que l'une des huit questions n'a pas de réponse, le flux n'est pas prêt à développer. Une case vide dit « personne n'a encore décidé », et c'est utile de le voir avant le premier sprint plutôt qu'en recette.

La huitième question paraît accessoire. Elle ne l'est pas. La documentation d'Odoo indique par exemple que les points d'accès XML-RPC et JSON-RPC sont dépréciés, remplacés par une nouvelle API, avec une suppression prévue dans Odoo 22. Une intégration écrite sans nommer l'interface utilisée cassera un jour, et personne ne saura pourquoi.

Côté site, je lis la documentation de la plateforme avant d'écrire la fiche. Celle de PrestaShop précise que son webservice fonctionne avec une clé d'accès dont les droits se règlent ressource par ressource, et qu'il peut répondre en JSON mais attend toujours du XML pour les écritures. Ce sont des détails, et ce sont eux qui font déraper un planning quand on les découvre tard.

03Temps réel ou flux batch : décider flux par flux

Vous vous posez peut-être la question comme si elle avait une seule réponse pour tout le projet. Je ne la traite jamais comme ça. Je pose la même question pour chaque flux : qu'est-ce que coûte une donnée en retard ?

Si le site affiche un stock disponible alors que l'ERP n'en a plus, le client commande quelque chose qu'on ne pourra pas livrer. Ce flux-là mérite un appel en temps réel, ou au moins une fréquence très courte. À l'inverse, une fiche produit dont la description change une fois par mois peut très bien passer dans un flux batch la nuit. Personne ne verra la différence, et un fichier qui arrive à heure fixe est plus facile à surveiller et à rejouer. Les deux cohabitent souvent dans la même intégration, et la spécification doit dire, flux par flux, pourquoi on a choisi l'un ou l'autre.

Le temps réel a un coût qu'on oublie : il faut gérer l'indisponibilité de l'autre système. Si l'ERP ne répond pas, que fait le site ? Il bloque la commande, il la met en attente, il la crée quand même ? La réponse est une décision métier, pas technique, et elle doit être écrite.

Rejouer sans créer de doublon

Il y a une règle que j'ai apprise en construisant mes pipelines de publication : chaque étape est journalisée, pour qu'une relance reprenne là où elle s'est arrêtée sans créer un deuxième article. Une intégration a exactement le même besoin. Si un flux de commandes tombe à mi-parcours et qu'on le relance, la commande ne doit pas arriver deux fois dans l'ERP. Je demande donc, dans chaque fiche, quel identifiant permet de reconnaître un échange déjà traité.

04Le tableau de correspondance des champs, avec les unités

C'est la partie la plus ingrate du document, et c'est celle qu'on lit le plus. Une ligne par champ, avec au minimum ces colonnes :

• le nom du champ dans le système source ;
• le nom du champ dans le système cible ;
• le type et le format (texte, nombre entier, date) ;
• l'unité, pour tout ce qui se mesure ou se compte ;
• obligatoire ou non, et ce qu'on fait s'il manque ;
• la règle de transformation, s'il y en a une, arrondi compris.

Si vous ne deviez ajouter qu'une colonne, ce serait « unité ». J'ai vu un mélange de centimètres et de millimètres entre deux outils déformer tout un rendu. Une colonne remplie pour chaque mesure ne garantit pas qu'une telle erreur n'arrive jamais. Elle oblige au moins quelqu'un à se poser la question au moment d'écrire la ligne, plutôt qu'au moment où le résultat est faux. La donnée de référence doit être explicite, champ par champ.

La règle d'arrondi mérite sa ligne, elle aussi. Chez Moonworkers, notre logiciel de paie, un oracle écrit à partir des textes du HMRC a rejoué 896 calculs de cotisations et trouvé quatre erreurs d'un penny, toutes dues à une règle d'arrondi. Un penny, c'est peu. Sur une facture ou une déclaration, c'est un écart que quelqu'un devra expliquer.

05Faire vivre la spécification version après version

Sur une intégration entre un ERP et un site marchand, j'ai vu la spécification bouger presque à chaque réunion. C'est le rythme normal d'un projet de ce type : chaque atelier fait apparaître un cas que personne n'avait prévu. Le vrai risque, c'est que les changements vivent dans des e-mails et des comptes rendus éparpillés. Je l'ai fait évoluer version après version, pour que tout le monde parle du même document.

Ce que je fais concrètement :

1. Un seul document de référence, à un seul endroit, que tout le monde peut lire.
2. Un numéro de version en haut, et un journal des changements juste en dessous : date, ce qui a changé, pourquoi, qui l'a validé.
3. Après chaque réunion, je reporte les décisions dans le document le jour même, et j'envoie le lien vers la nouvelle version plutôt qu'un résumé.
4. Quand un changement casse ce qui existait, je le signale clairement et je laisse le temps aux équipes de s'adapter.

Ce dernier point rejoint les recommandations publiques : le gouvernement britannique conseille d'éviter les changements qui cassent les versions précédentes et de prévenir les utilisateurs avant de retirer une version. Son guide de documentation demande aussi une section qui explique comment fonctionnent les versions et où les changements sont publiés.

J'ajoute une habitude venue de mes machines : les règles vivent dans un seul fichier, pas dans les messages. Quand un relecteur corrige un article, je ne corrige pas seulement le texte, j'écris la règle dans la configuration du pipeline, avec un commentaire qui dit pourquoi elle existe. J'en parle dans ma note sur la machine de contenu IA et la relecture humaine. Pour une spécification, c'est pareil : une décision prise en réunion qui n'est pas dans le document n'existe pas.

06Ce que la spécification ne remplace pas

Une bonne spécification ne vous dispense pas de parler aux équipes. Elle rend juste les conversations plus courtes. Quand deux équipes ne sont pas d'accord sur une règle, le document sert à montrer précisément où est le désaccord, pas à le trancher à la place des gens.

Elle ne remplace pas non plus la recette. Je peux écrire une règle parfaite, si personne ne la teste avec des cas réels avant la mise en production, elle restera une hypothèse. C'est pour ça que chaque fiche contient ses cas de test, y compris ceux qui doivent échouer : une commande sans référence, un stock négatif, une date au mauvais format. Dans mes pipelines, des articles volontairement mauvais doivent toujours sortir rouges ; s'ils passent, c'est le contrôle qui est cassé. Ma checklist de recette et de mise en production part de cette idée.

Enfin, la méthode a un coût. Tenir un document à jour après chaque réunion demande du temps, chaque semaine, pendant tout le projet. Sur une petite intégration entre deux outils standards avec un connecteur existant, je ne ferais pas un document aussi complet : une page avec les flux, les propriétaires de données et les erreurs suffit souvent. La méthode complète se justifie quand plusieurs équipes travaillent en parallèle et qu'aucune ne voit tout le projet.

07Par où commencer lundi

Si votre projet d'intégration démarre ou patine, voici ce que je ferais en premier :

1. Lister les flux sur une seule page, avec pour chacun le sens, la fréquence et le système qui fait foi.
2. Pour le flux le plus risqué, souvent les commandes ou les stocks, écrire la fiche complète avec ses huit questions, et laisser visibles les cases vides.
3. Ouvrir le tableau de correspondance de ce flux et remplir la colonne « unité » avant toutes les autres.
4. Mettre un numéro de version en haut du document et le premier changement dans le journal.

C'est une partie du travail que je fais en direction technique et direction de projet. Si votre intégration ressemble à celle-ci, on peut en parler.