Le besoin tient souvent en une phrase : « connecter le CRM à l’ERP ». Dix personnes imaginent pourtant dix périmètres différents. Le commerce attend des comptes à jour, la finance veut des factures fiables, le support veut comprendre les rejets et la sécurité refuse qu’un secret circule dans les logs. Une estimation donnée sur cette phrase ne chiffre pas un projet ; elle chiffre une hypothèse silencieuse.
Le vrai enjeu n’est pas de documenter davantage : une discovery d’intégration API doit remplacer les hypothèses qui changent le delivery par des décisions observables. En dix jours, elle fixe la promesse métier, les frontières, les sources de vérité, le contrat d’échange, les données d’essai, les risques de production et une première tranche verticale. Elle ne prétend pas tout spécifier. Elle rend le prochain engagement assez étroit pour être estimé, testé, repris et contesté.
Le résultat attendu n’est donc ni un audit décoratif ni un backlog de plusieurs centaines de lignes. C’est un dossier de décision : ce que le premier lot prouve, ce qu’il exclut, les dépendances qui peuvent le bloquer, les seuils qui autorisent sa mise en service et le coût des inconnues encore ouvertes.
Dawap conduit ce travail dans ses missions d’intégration API sur mesure. La landing porte l’intention commerciale et la réalisation ; la méthode présentée ici organise les dix jours qui précèdent le premier lot.
Distinguer qualification et discovery engagée
La qualification vérifie qu’une demande mérite un investissement : objectif, sponsor, systèmes concernés, urgence et ordre de grandeur. La discovery commence après ce premier feu vert. Elle consomme du temps métier et technique pour réduire les inconnues qui changeraient l’architecture, le périmètre ou la capacité de tenir le run.
Ne pas refaire le rendez-vous d’avant-vente pendant dix jours
La méthode pour qualifier une demande d’intégration API décide s’il faut cadrer, expérimenter ou refuser. La discovery part d’une demande déjà qualifiée et produit des artefacts exécutables : scénarios, contrats, échantillons, risques, stratégie de test et lot vertical.
Cette frontière évite la cannibalisation et protège le budget. Si le sponsor, la valeur ou les systèmes restent inconnus, la demande retourne en qualification. Si le projet est confirmé mais que l’autorité de la donnée, les erreurs et les dépendances restent floues, alors les dix jours ont une vraie fonction.
Reconnaître les intégrations qui méritent dix jours
Le format convient lorsque deux systèmes ou plus modifient une même réalité métier, qu’un échec crée une correction humaine, que des contraintes d’identité ou de conformité existent, ou que le flux doit tenir un volume et une disponibilité mesurables. Il devient prioritaire quand les équipes ne s’accordent pas sur le mot « terminé ».
Savoir aussi quand le dispositif serait excessif
Un export ponctuel, réversible, à faible volume et sans effet opérationnel peut être cadré plus légèrement. À l’inverse, paiement, stock, commande, facture, identité ou donnée personnelle justifient la profondeur même avec peu de transactions : le dommage d’une erreur compte davantage que le débit nominal.
Le signal le plus fiable reste le coût d’ambiguïté. Si une divergence peut bloquer une vente, produire un doublon comptable, ouvrir un droit indu ou mobiliser plusieurs équipes sans trace commune, dix jours de discovery coûtent moins qu’une première release fondée sur des suppositions.
Fixer les sorties avant les ateliers
Le responsable de discovery publie dès le départ une liste de livrables et leurs validateurs. Chaque atelier doit nourrir une sortie précise ; sinon il devient une conversation intéressante mais impossible à transformer en engagement. Une décision non validée porte un owner et une échéance.
Exiger un paquet de décision cohérent
- Une promesse métier : acteur, déclencheur, résultat, délai utile et dommage d’échec.
- Une carte des responsabilités : systèmes, owners, sources de vérité et frontières de sécurité.
- Un contrat candidat : objets, identifiants, versions, erreurs et exemples de payloads.
- Un jeu d’essai : cas nominal, limites, absences, doublons et données interdites.
- Un registre de risques : preuve, impact, réduction, owner et décision associée.
- Un premier lot : tranche verticale, exclusions, tests, observabilité, rollback et critères de fin.
Ces pièces se répondent. Un risque sans effet sur le lot est soit mal formulé, soit hors périmètre. Un contrat sans cas d’essai est une opinion. Une estimation sans hypothèses et exclusions ne peut pas être gouvernée.
Jour 1 : écrire la promesse métier
La première journée décrit le service rendu sans citer de technologie : « une commande payée doit être visible par l’ADV avec ses lignes et son statut sous cinq minutes ». L’équipe nomme l’acteur qui déclenche, celui qui attend, le résultat observable et la conséquence d’un retard ou d’une erreur.
Remplacer “temps réel” par une fenêtre de valeur
Chaque scénario reçoit un délai utile, une fréquence, un volume nominal, un pic et un niveau de cohérence. Le délai d’une transaction métier de bout en bout fournit la méthode de mesure après livraison ; ici, il sert à borner la promesse avant de choisir le mécanisme.
La journée se termine avec trois à cinq scénarios prioritaires et autant de contre-exemples. « Créer une commande complète » est un scénario ; « synchroniser les commandes » ne l’est pas. Les scénarios exclus restent visibles afin qu’ils ne réapparaissent pas implicitement pendant le développement.
Jour 2 : cartographier acteurs et frontières
L’équipe dessine le trajet réel entre interface, API, middleware, bases, services tiers et équipes humaines. Elle ajoute environnements, réseaux, mécanismes d’identité, quotas, fenêtres de maintenance et propriétaires opérationnels. La carte montre les frontières de responsabilité plutôt qu’un catalogue de logos.
Faire apparaître les humains dans le système
Une validation finance, une correction ADV ou une réouverture par le support est une étape du flux. La cacher produit une architecture techniquement élégante et opérationnellement fausse. L’acteur humain reçoit entrée, décision, délai et preuve comme n’importe quel composant.
Pour chaque frontière, la discovery demande qui fournit l’accès, qui diagnostique, qui peut couper et qui autorise la reprise. Les dépendances sans owner deviennent des risques bloquants. Une sandbox promise mais non accessible n’est pas une ressource disponible.
Jour 3 : nommer les sources de vérité
Objet par objet, l’équipe décide quel système fait autorité et dans quelles transitions. Le CRM peut créer le prospect, l’ERP attribuer le compte client et le support enrichir un contact sans pour autant posséder l’état financier. Une phrase globale comme « l’ERP est maître » ne résout pas ces responsabilités.
Écrire l’autorité au niveau du champ et de l’événement
La matrice associe objet, attribut critique, identifiant stable, système autorisé à écrire, règle de conflit et événement qui transfère éventuellement l’autorité. Elle précise aussi les projections dérivées qui peuvent être recalculées au lieu d’être arbitrées manuellement.
Les zones sans identifiant commun sont testées immédiatement. Une table de correspondance doit avoir cycle de vie, unicité et procédure de réparation. Concaténer deux champs métiers pour fabriquer une clé paraît rapide, mais casse dès qu’un champ change ou qu’un doublon historique apparaît.
Jour 4 : éprouver les contrats API
Le contrat candidat est confronté à la documentation et, si possible, à des appels réels en sandbox. L’équipe vérifie authentification, scopes, pagination, filtres, limites, idempotence, webhooks, erreurs, version et comportement face aux champs inconnus. Elle enregistre les réponses, pas seulement les attentes.
Produire des exemples qui peuvent devenir des tests
Chaque opération possède un exemple minimal valide, un exemple complet et plusieurs refus : champ absent, valeur invalide, version ancienne, doublon et dépendance indisponible. Le contrat précise les unités, fuseaux, arrondis, encodages et sémantiques de null qui créent souvent des divergences tardives.
Le choix entre appel synchrone, événement et lot reste attaché à chaque opération. La méthode pour choisir synchrone, asynchrone ou batch approfondit cet arbitrage ; la discovery ne doit pas imposer une architecture unique avant d’avoir écrit les promesses.
Jour 5 : construire le jeu de données
La cinquième journée assemble un échantillon représentatif et gouverné. Il couvre cas courants, extrêmes, absents, historiques, caractères spéciaux, volumes et relations entre objets. Les données personnelles sont synthétisées ou minimisées ; copier une base de production dans une sandbox n’est pas une stratégie de test.
Mesurer la qualité avant de promettre une transformation
L’équipe profile complétude, unicité, formats, cardinalités et distribution des valeurs. Elle distingue défaut corrigible automatiquement, rejet métier et anomalie exigeant une décision humaine. Le mapping porte ainsi une politique, pas seulement deux noms de colonnes.
Un échantillon de vingt enregistrements parfaits valide une démonstration, pas un flux. La discovery cherche volontairement les limites : compte sans pays, commande à cent lignes, avoir partiel, article archivé, timestamp ambigu, identifiant réutilisé. Chaque limite alimente test, règle ou exclusion.
Jour 6 : traiter sécurité et conformité
L’équipe décrit les identités machine, scopes minimaux, stockage des secrets, rotation, chiffrement, données sensibles, durées de conservation et traces autorisées. Elle sépare accès de développement, recette, production et support. Un token partagé entre environnements transforme une erreur de configuration en incident transverse.
Tester le refus aussi sérieusement que le succès
Les scénarios couvrent secret expiré, scope insuffisant, signature invalide, horloge décalée et révocation. Les logs ne contiennent ni credential ni payload sensible complet ; ils conservent identifiant de corrélation, opération, code et empreinte suffisante pour enquêter.
Les obligations de conformité sont traduites en comportements : qui peut relancer, quelles données peuvent être rejouées, comment une suppression se propage, quelle preuve est conservée. Une mention « conforme RGPD » sans flux, responsable ni durée ne réduit aucun risque de delivery.
Jour 7 : concevoir erreurs et reprise
Chaque erreur est classée entre transitoire, fonctionnelle, sécurité, quota et incohérence de donnée. Le contrat définit retry borné, backoff, idempotence, quarantaine, correction et replay. Une réponse 200 contenant un refus métier doit être traitée comme un échec observable, pas comme un succès transport.
Faire exécuter un incident sur papier
L’équipe suit une transaction de l’entrée jusqu’à la correction : signal, diagnostic, décision, action, contrôle et clôture. Elle mesure les informations disponibles à chaque acteur. Si le support doit interroger trois bases ou demander un export au développeur, le run n’est pas prêt.
Le replay conserve clé d’idempotence, version du contrat et autorité de la donnée. Il ne doit ni doubler l’effet déjà produit ni écraser une correction plus récente. La discovery précise également qui peut rejouer un élément, un sous-lot ou une période entière.
Jour 8 : instrumenter la preuve de service
Les indicateurs suivent la promesse métier : taux de transactions abouties, délai de bout en bout, âge du backlog, rejets par cause, corrections humaines et temps de reprise. CPU et codes HTTP restent utiles, mais ils ne prouvent pas qu’une commande est exploitable dans le système cible.
Relier chaque alerte à une action
Une alerte nomme le service affecté, le seuil, la fenêtre, l’owner et le runbook. Le tableau de bord permet de descendre d’un agrégat vers une transaction grâce au même identifiant de corrélation. Sans ce chemin, une courbe rouge annonce un problème sans rendre sa correction plus rapide.
La discovery fixe le niveau de service initial et sa méthode de calcul. Si 99 % des commandes doivent arriver sous cinq minutes, elle précise le point de départ, le point d’arrivée, les exclusions et la période. Cette définition devient un test d’acceptation du premier lot.
Jour 9 : découper le premier lot vertical
Le premier lot traverse déclencheur, contrat, donnée, sécurité, traitement, statut, observabilité et reprise pour un scénario étroit. Il ne livre pas « toute l’API source » avant « toute l’API cible ». Il prouve une transaction utile de bout en bout avec le minimum d’objets et de variantes.
Choisir une tranche qui révèle les risques structurants
Le bon lot n’est pas forcément le cas le plus facile. Il inclut au moins une source de vérité, une authentification réaliste, une transformation, une erreur contrôlée et un indicateur métier. Il évite cependant les variantes qui n’ajoutent aucune preuve nouvelle.
Entrées, sorties, exclusions, dépendances, hypothèses, tests, seuils et rollback sont écrits ensemble. L’estimation distingue travail certain, réserve liée à une inconnue et option. Si un accès ou une décision manque, le lot contient un spike borné avec sortie attendue plutôt qu’une marge cachée.
Jour 10 : tenir la revue de décision
La revue ne rejoue pas tous les ateliers. Elle présente promesse, architecture de responsabilités, démonstration des contrats, risques majeurs, lot proposé, estimation et décisions demandées. Chaque participant reçoit le dossier avant la séance et vient avec un mandat clair.
Sortir avec un verdict explicite
Quatre verdicts sont possibles : lancer le lot, lancer après levée d’un blocage nommé, prolonger par une expérimentation bornée ou arrêter. « Continuer à étudier » n’est pas un verdict si personne ne sait quelle preuve manque, qui la produit et quand elle sera jugée.
Le compte rendu fige version des contrats, périmètre, budget, owners et date de révision. Les questions restantes sont classées selon leur capacité à modifier le lot. Une inconnue sans conséquence sur la première tranche peut attendre ; une inconnue qui invalide sa source de vérité doit être levée avant engagement.
- À valider d’abord : valeur, source de vérité, accès et preuve attendue du lot.
- À décider ensuite : cohorte, seuils d’arrêt, owner de reprise et budget d’inconnue.
- À différer : toute variante qui ne réduit aucun risque du premier engagement.
- À refuser : un lancement sans contrat éprouvé, jeu d’essai ni retour arrière.
Tenir un registre de risques actionnable
Un risque relie cause, événement redouté, impact, signal précoce, mesure de réduction, owner et date. « API instable » reste trop vague. « Le quota partagé peut limiter la création de commandes sous le pic prévu » permet de demander une mesure, réserver une capacité ou réduire la cohorte.
Ne pas confondre risque, fait et problème
Un accès absent est un problème présent ; une documentation contradictoire est un fait à résoudre ; un changement futur de version est un risque. Cette distinction évite les probabilités fictives. Chaque élément produit une action adaptée : débloquer, vérifier, mitiger, transférer ou accepter.
Le registre reste court et priorisé. Les cinq risques susceptibles de changer coût, délai, sécurité ou valeur sont suivis chaque semaine. Les risques acceptés indiquent le dommage assumé et la personne autorisée à l’assumer ; ils ne disparaissent pas derrière une couleur verte.
Éviter les erreurs fréquentes de discovery
Commencer par les endpoints enferme le projet dans la forme actuelle des outils. Inviter tout le monde à chaque atelier dilue les décisions. Produire un backlog exhaustif retarde la preuve. Estimer avant les accès transforme l’inconnue en fausse précision.
Refuser la documentation sans contradiction
Copier la documentation fournisseur ne vérifie ni scopes ni quotas du compte réel. Tester uniquement le nominal reporte la reprise après le go-live. Oublier les humains cache les validations et corrections. Confondre prototype et socle introduit en production secrets, raccourcis et données non gouvernées.
L’erreur inverse consiste à vouloir résoudre l’architecture cible entière. Dix jours ne ferment pas toutes les options ; ils sécurisent la prochaine décision irréversible. Le dossier doit rendre visibles les extensions sans les inclure silencieusement dans le premier lot.
Passer de la discovery au delivery
Le delivery reprend les artefacts comme contrats vivants. Les exemples deviennent fixtures, les scénarios deviennent tests d’acceptation, les seuils alimentent le monitoring et le registre de risques structure les points de contrôle. La première semaine de développement ne doit pas redécouvrir les décisions déjà validées.
Installer des portes de sortie dès le premier lot
Le déploiement commence sur une cohorte, un tenant, une famille d’objets ou une plage de volume. Le feature flag, le rollback et la réconciliation sont testés avant l’élargissement. Deux fenêtres stables et un exercice de reprise réussi valent davantage qu’une démonstration nominale spectaculaire.
À la fin du lot, l’équipe compare hypothèses et mesures : délai, taux de rejet, qualité des données, temps humain et coût de run. Elle décide d’étendre, corriger, redécouper ou arrêter. La discovery devient utile quand elle rend ce verdict moins politique et plus factuel.
Contre-intuitivement, un premier lot plus étroit peut apprendre davantage qu’un prototype large : il force identité, transformation, statut, erreur et reprise à fonctionner ensemble, au lieu de multiplier des écrans nominaux impossibles à exploiter.
- À faire d’abord : prouver une transaction métier complète et reprenable.
- À différer : les variantes qui ne testent aucun risque nouveau.
- À mesurer : délai de bout en bout, rejets, corrections et temps de reprise.
- À refuser : une généralisation sans cohorte ni seuil d’arrêt.
Relier qualification, temporalité et mesure
La qualification de la demande API fournit le feu vert et le sponsor ; la discovery transforme ensuite cette intention en tranche livrable. Les deux étapes restent séparées pour éviter qu’un atelier d’avant-vente devienne une spécification implicite.
Approfondir les décisions qui conditionnent le run
Le choix du rythme synchrone, asynchrone ou batch précise la temporalité de chaque opération, tandis que la mesure du délai de bout en bout vérifie la promesse après livraison. Cette chaîne garde chaque contenu propriétaire de sa décision et renforce la même offre d’intégration.
Quand la tranche verticale révèle une dépendance lente ou un résultat différé, ces lectures permettent de modifier une opération sans rouvrir toute la discovery. La promesse, le rythme et la mesure restent ainsi reliés par le même identifiant métier et les mêmes seuils de décision.
Conclusion : acheter de la certitude utile, pas du papier
Une discovery d’intégration API réussie ne supprime pas toutes les inconnues. Elle réduit celles qui pourraient invalider le premier engagement et transforme les autres en hypothèses visibles, bornées et révisables.
En dix jours, promesse métier, responsabilités, contrats, données, sécurité, erreurs, observabilité et lot vertical forment une même décision. Ce lien empêche qu’un schéma séduisant masque un run impossible ou qu’un backlog volumineux remplace la preuve.
Le premier lot peut alors être estimé pour ce qu’il doit réellement démontrer. Il possède un début, une fin, des exclusions, des seuils et un retour arrière. L’organisation n’achète pas une certitude artificielle ; elle achète la capacité de décider plus tôt avec de meilleures preuves.
Dawap vous accompagne pour conduire cette discovery puis réaliser la tranche retenue dans une mission d’intégration API fiable et exploitable, du contrat métier jusqu’à l’observabilité et au runbook de reprise.
