Le schéma annonce qu’un montant est décimal, qu’un identifiant est une chaîne et qu’un statut appartient à cinq valeurs. En production, le montant arrive en centimes sur un ancien compte, l’identifiant change après fusion et une sixième valeur apparaît pendant une annulation. Le problème ne vient pas d’un parseur fragile : les données réelles n’ont jamais participé à la décision de conception.
Le symptôme se voit tôt. Le partenaire fournit un exemple parfait, refuse de partager des rejets ou répond que les volumes « dépendent ». L’équipe commence alors le mapping avec des hypothèses, puis découvre les limites au fil des incidents. Chaque surprise devient une correction manuelle, une branche spéciale ou une perte de traçabilité.
Le pack d’acceptation API permet de décider avant de coder. Il réunit exemples nominaux, frontières, valeurs inconnues, erreurs, identités, chronologie, volumes et scénarios de reprise. Chaque élément porte une provenance et un verdict attendu afin que le connecteur soit conçu contre des preuves plutôt que contre une documentation idéale.
Dawap utilise cette méthode dans ses missions d’intégration API sur mesure. L’offre couvre cadrage, réalisation et run ; ce protocole sécurise l’entrée du chantier sans cannibaliser la promesse de la landing.
Voir ce que le Swagger ne prouve pas
OpenAPI décrit une forme possible et des contraintes déclarées. Il ne prouve ni les valeurs historiques, ni l’ordre réel des événements, ni la qualité des identifiants, ni le comportement d’un système sous quota. Un contrat syntaxique valide peut donc transporter une décision métier fausse.
Chercher l’écart entre autorisé et observé
L’équipe compare documentation, sandbox, exports et production anonymisée. Elle relève champs présents mais vides, enums supplémentaires, erreurs non documentées et timestamps ambigus. Ces écarts deviennent des entrées de conception, pas des anomalies repoussées après livraison.
Contre-intuitivement, un schéma très permissif augmente le besoin de preuves. Si tout champ accepte une chaîne nullable, le consommateur doit apprendre ailleurs ce qui rend une commande exploitable, ce qui commande un rejet et ce qui peut attendre une reprise.
Savoir quand exiger ce pack
Le pack devient indispensable quand le flux engage argent, stock, identité, conformité ou promesse client ; lorsqu’il reprend un historique ; ou quand plusieurs systèmes possèdent une partie de la vérité. Un enrichissement éditorial réversible peut commencer plus léger.
Adapter la profondeur au risque
Une lecture simple exige cas nominal, absence et quota. Une commande bidirectionnelle ajoute transitions, doublons, annulations, événements tardifs et compensation. Un paiement exige encore arrondis, devise, écritures et rapprochement.
Le signal faible apparaît lorsque le partenaire promet que « ce cas n’arrive jamais » sans requête ni mesure. Si l’impossibilité n’est pas garantie par un invariant technique ou contractuel, le cas rejoint le pack avec un comportement sûr.
Borner objets, décisions et responsabilités
Le pack commence par les objets réellement échangés et les décisions qu’ils commandent. Produit, offre, client, commande, paiement et expédition n’ont pas le même owner. Le connecteur ne peut pas décider seul de leur autorité.
Écrire les entrées et sorties attendues
Pour chaque opération, l’entrée liste préconditions, source, version et données minimales. La sortie précise succès, rejet, état créé, événement émis et preuve. Les responsabilités distinguent producteur, transport, consommateur et métier qui tranche l’exception.
Le périmètre nomme aussi ce qui ne sera pas pris en charge au premier lot. Une exclusion sans fallback est un risque caché ; une exclusion avec détection, owner et procédure devient une décision gouvernable.
Obtenir des exemples nominaux complets
Un exemple nominal doit parcourir toute la chaîne, pas seulement afficher un JSON. Il contient requête, réponse, headers utiles, événements suivants, identifiants et état observable dans les systèmes de départ et d’arrivée.
Conserver le contexte qui donne du sens
Une commande inclut devise, taxes, remises, adresses, lignes, vendeur, dates et statut de paiement. Supprimer ces champs pour simplifier l’exemple empêche de tester les relations qui produiront les incidents les plus coûteux.
Chaque exemple indique provenance, date, version d’API et transformations d’anonymisation. Un payload inventé par l’équipe peut compléter une frontière, mais il ne remplace pas un fait réel lorsque la question porte sur la diversité de production.
Documenter limites et valeurs absentes
Le pack couvre zéro, maximum, chaîne vide, champ absent, valeur nulle, caractères internationaux, précision décimale, liste vide et liste volumineuse. Chaque frontière reçoit un verdict : accepter, normaliser, rejeter, mettre en quarantaine ou demander une correction.
Ne pas confondre absent, nul et inconnu
Absent peut signifier non fourni, nul peut signifier explicitement supprimé et inconnu peut être une valeur métier. Les fusionner en vide provoque des effacements lors des mises à jour partielles. Le mapping conserve cette sémantique ou refuse l’opération.
Par exemple, un stock à zéro ferme une offre ; un stock absent conserve peut-être la valeur précédente ; un stock inconnu doit expirer puis passer en repli. Le pack exige ces trois cas et la décision attendue.
Faire produire les rejets réels
Une liste de codes HTTP ne suffit pas. Le fournisseur doit montrer corps, headers, identifiant de corrélation, caractère réessayable et effet éventuel déjà produit. Un timeout après écriture n’a pas la même reprise qu’un rejet avant validation.
Classer les erreurs par décision de reprise
Les classes minimales sont correction de donnée, nouvelle tentative, attente d’une dépendance, authentification, quota, conflit de version et incident fournisseur. Chaque classe possède seuil, délai, owner et sortie de quarantaine.
Le pack inclut une erreur transitoire devenue permanente après trois essais, un rejet partiel et une réponse techniquement réussie mais métier refusée. Le connecteur doit prouver qu’il ne confond pas ces fins.
Prouver identifiants et corrélations
L’équipe obtient identifiants stables, identifiants modifiables, clés composites et cas de fusion ou de réutilisation. Elle vérifie la longueur, la casse, les zéros initiaux et l’espace de noms. Une chaîne ne garantit aucune unicité.
Relier requête, objet et événement
Un identifiant d’idempotence distingue la tentative ; un identifiant objet distingue le résultat ; un identifiant de corrélation relie la chaîne. Les logs et réponses exposent assez de clés pour passer de l’un à l’autre sans fouiller plusieurs bases.
Le pack contient au moins un doublon légitime, une collision apparente et une commande dont l’identifiant externe change. Si le modèle ne peut pas représenter ces cas, le développement attend une décision d’identité.
Tester dates, ordre et retard
Les données portent date effective, date d’enregistrement et date de réception. Le pack fournit fuseaux, changement d’heure, précision, événement ancien reçu tard et événements inversés. Une comparaison sur la seule arrivée est explicitement interdite.
Définir ce qui gagne lorsque l’ordre casse
Une version croissante peut protéger un état ; une machine à états peut refuser une transition impossible ; une compensation peut préserver un fait déjà exécuté. Le choix dépend de l’objet. Le connecteur applique la règle au lieu de retenir systématiquement le dernier message.
Si une annulation arrive après l’expédition, alors elle ouvre une décision de retour plutôt que d’effacer l’envoi. Ce scénario doit produire un résultat reproductible dans les fixtures et les logs.
Mesurer volumes, quotas et fenêtres
Le fournisseur donne médiane, pointe, taille maximale, saisonnalité, pagination, quota et comportement de dépassement. L’équipe vérifie ces chiffres par un export ou une mesure. « Quelques milliers » ne dimensionne ni file ni fenêtre de replay.
Tester une rafale, pas seulement une moyenne
Cas concret : 60 000 mises à jour arrivent en quinze minutes après un import catalogue, alors que la journée moyenne en compte 80 000. Le pack contient cette distribution, un quota de 300 appels par minute et le délai maximal de fraîcheur.
Le verdict fixe concurrence, backpressure, taille de lot et priorité. Si le backlog dépasse trente minutes, alors les stocks critiques passent avant les images et le producteur ralentit. La règle est acceptée avant que la file existe.
Couvrir créations, mises à jour et annulations
Une création répétée, une mise à jour partielle et une annulation concurrente doivent être représentées. Le pack distingue PUT, PATCH et commande métier, puis précise si un champ absent conserve ou supprime la valeur.
Conserver la précondition de modification
Version, ETag ou état attendu empêche une écriture ancienne d’écraser une décision récente. En cas de conflit, la réponse contient version courante et action permise. Rejouer aveuglément la même mutation n’est pas une stratégie.
Une annulation indique ce qui est encore réversible. Si le paiement est capturé ou l’expédition lancée, elle produit une compensation distincte. Le pack fournit les deux frontières afin d’éviter un statut « annulé » qui masque des obligations restantes.
Préparer idempotence et replay
Chaque écriture fournit une clé d’idempotence, sa portée et sa durée de rétention. Le pack montre la première réponse, le doublon identique, le doublon au contenu différent et la tentative après expiration.
Exercer le repli avant le premier incident
Les entrées sont point de coupure, population, versions et dépendances. Les sorties sont objets repris, rejets résiduels, rapprochement et preuve de non-duplication. Le runbook nomme owner, seuil d’arrêt et rollback.
En revanche, un replay n’est pas autorisé si l’effet précédent reste inconnu. L’équipe interroge d’abord l’état distant ou place le dossier en revue. Cette attente coûte moins qu’un second paiement ou une seconde expédition.
Retirer les secrets sans retirer le réel
L’anonymisation remplace données personnelles, tokens et secrets tout en conservant longueurs, formats, relations et distributions utiles. Un email devient synthétique mais reste internationalisé ; une carte disparaît au profit du statut et de l’identifiant fournisseur nécessaires au cas.
Tracer qui peut voir et rejouer le pack
Le dépôt possède accès limité, durée de conservation, journalisation et procédure de renouvellement. Les fixtures publiques sont séparées des échantillons restreints. Aucun secret de production n’entre dans le code ni dans la CI.
La sécurité valide la méthode de retrait, tandis que le métier confirme que les transformations n’ont pas supprimé l’anomalie étudiée. Une anonymisation qui uniformise les cas rend le pack propre mais inutile.
Rejouer une commande complète
Une commande réelle contient trois lignes, deux taux de taxe, une remise répartie et une adresse avec caractères accentués. La création réussit, mais le webhook de paiement arrive avant la réponse HTTP et l’annulation d’une ligne survient après capture.
Produire un verdict pour chaque frontière
Le mapping conserve les centimes, répartit la remise selon la règle signée et crée les identités. L’événement anticipé attend la corrélation sans être perdu. L’annulation produit une compensation partielle et laisse les deux lignes restantes exécutables.
Le scénario passe lorsque commande, paiement et ledger se rapprochent, que le replay ne double aucun effet et que le support retrouve l’histoire en moins de cinq minutes. Une simple réponse 200 ne constitue pas le verdict.
Transformer le pack en critères de recette
Chaque pièce devient une fixture versionnée avec entrée, préconditions, résultat attendu et preuve. Les tests couvrent contrat, mapping, transitions, rejets et reprise. Le pack ne se réduit pas à une archive consultée pendant le cadrage.
Séparer conformité technique et acceptation métier
Le schéma peut être valide alors que la commande est inexploitable. La recette technique contrôle forme et transport ; la recette métier contrôle montant, identité, état, décision et capacité de reprise. Les deux verdicts sont conservés.
- Accepter : lorsque forme, invariants, effets et preuves correspondent au verdict attendu.
- Corriger : lorsque le mapping est déterministe mais incomplet.
- Mettre en quarantaine : lorsque la donnée est légitime mais l’autorité manque.
- Refuser : lorsque l’invariant métier ou la sécurité ne peut pas être garanti.
Le seuil d’ouverture exige cent pour cent des scénarios critiques et au moins 95 % du pack complet. Les écarts restants possèdent owner, fallback et date ; aucune exception financière ne reste ouverte.
Plan d’action avant le développement
Les entrées sont documentation, exports, sandbox, incidents, métriques et responsables métier. Les sorties sont pack versionné, matrice de verdict, fixtures, seuils, runbook, backlog de décisions et accord de démarrage.
Fermer les inconnues qui changent l’architecture
- Jours 1 à 3 : borner objets, décisions, owners et exclusions.
- Jours 4 à 6 : collecter cas nominaux et preuves de provenance.
- Jours 7 à 9 : obtenir frontières, rejets, doublons et événements tardifs.
- Jours 10 à 12 : mesurer volumes, quotas, tailles et rafales.
- Jours 13 à 15 : anonymiser, versionner et transformer les cas en fixtures.
- Jours 16 à 18 : rejouer les scénarios, trancher les écarts et signer le démarrage.
- À faire d’abord : obtenir l’effet d’un timeout, les règles d’identité et les limites qui changent le modèle ou la stratégie de reprise.
- Ensuite : transformer les cas représentatifs en fixtures reproductibles, avec leur provenance, leurs préconditions et leur verdict métier.
- Puis : exercer quota, événement tardif, doublon et rejeu avec les mêmes outils que ceux prévus pour le run.
- À différer : une variante éditoriale qui ne change ni invariant, ni mapping, ni opération du premier lot.
- À refuser : le démarrage si une écriture critique peut être répétée sans clé, preuve distante ou compensation définie.
Le responsable intégration tient une liste d’inconnues classées par impact. Identité, effet d’un timeout, limites de volume et sémantique d’annulation passent d’abord. Un nom de champ secondaire peut attendre si son fallback est explicite.
Chaque séance se termine par une preuve obtenue, une décision ou une dépendance datée. « À confirmer pendant le développement » n’est accepté que pour un sujet réversible, détectable et sans impact sur le modèle de données.
Le métier signe les verdicts, la sécurité signe l’usage des échantillons et la technique signe la faisabilité de replay. Ces responsabilités empêchent qu’un accord global masque une réserve critique détenue par une seule équipe.
La porte de sortie est binaire : le lot peut commencer avec des exceptions bornées, ou l’architecture reste suspendue. Si le pack change une cardinalité, une autorité ou une garantie, alors le chiffrage et le planning sont révisés avant le code.
Éviter les erreurs fréquentes
Accepter un seul exemple masque la distribution. Inventer tous les payloads reproduit les hypothèses. Documenter uniquement les 200 ignore la reprise. Anonymiser sans contrôle métier retire les cas utiles.
Refuser les preuves décoratives
Confondre sandbox et production sous-estime les données historiques. Moyenner les volumes masque les rafales. Reporter les identités verrouille un mauvais modèle. Tester le replay après livraison transforme le premier incident en expérience.
Le piège inverse est d’attendre un échantillon parfait et exhaustif. Le pack doit couvrir les décisions qui changent l’architecture. Les rares inconnues restantes sont acceptables si elles sont détectées, isolées et réversibles.
- À obtenir : tout cas qui engage un invariant, un effet ou une reprise.
- À simuler : une frontière garantie mais difficile à extraire sans danger.
- À différer : les variantes sans effet sur le contrat du premier lot.
Relier contrat, données et reprise
Le contrat d’intégration API répartit source de vérité et garanties. Le pack apporte les faits nécessaires pour accepter ou contester ces garanties avant implémentation.
Prolonger le cadrage sans dupliquer le run
Les data contracts API gouvernent la compatibilité des échanges en exploitation. La dead letter queue et son rejeu métier traitent les objets déjà rejetés.
Le pack intervient avant ces mécanismes : il révèle les cas qui doivent façonner schémas, files et procédures. Il renforce l’offre d’intégration sans promettre à lui seul la réalisation ou l’exploitation du connecteur.
Lorsque plusieurs partenaires et équipes doivent suivre décisions, preuves et écarts, Ciama peut conserver cette gouvernance. L’intégrateur reste responsable du contrat technique, des mappings et du run.
Conclusion : coder après la preuve
Une API documentée n’est pas encore une intégration comprise. Les exemples réels, frontières, rejets, identités, horloges et volumes montrent ce que le connecteur devra effectivement décider.
Le pack d’acceptation transforme ces faits en fixtures et verdicts avant que l’architecture se fige. Il réduit les branches improvisées et rend les reprises testables dès le premier lot.
Commencer plus tard de quelques jours peut ainsi éviter des semaines de correction. Le bon signal de démarrage n’est pas un endpoint disponible, mais une population représentative dont les sorties sont acceptées par les métiers. Cette discipline protège également le chiffrage, car elle révèle avant engagement les files, contrôles et compensations que le cas nominal ne montre jamais.
Dawap vous accompagne pour obtenir ces preuves, trancher les inconnues et réaliser une intégration API sur mesure dont les données, erreurs et procédures de reprise tiennent réellement en production.
