Guide d’intégration API
Cadrer une intégration API avant de développer le connecteur
Un connecteur ne consiste pas simplement à « envoyer A vers B ». Un périmètre utile précise les données, la source de vérité, le déclenchement, les accès, ainsi que la détection et la reprise des traitements incomplets.
Modèle de spécification du flux
- Objet métier et événement : quel changement a lieu, et quel résultat métier doit suivre ?
- Source de vérité : quel système peut créer ou corriger chaque champ ?
- Mapping : champ source, champ cible, type, caractère obligatoire, transformation et valeur de repli.
- Identité : quelles clés stables rapprochent les enregistrements ? Ne pas dépendre d’un simple libellé.
- Direction et déclencheur : sens unique ou double ; webhook, planification ou action explicite.
- Accès : environnement, propriétaire du compte, authentification, permissions, rotation et identifiants de test.
- Livraison : volume attendu, limites, délais, doublons, ordre, nouvelles tentatives et rejeu.
- Responsabilité des échecs : où ils apparaissent, qui agit, comment reprendre et ce qui ne doit pas être répété.
Webhooks et synchronisation planifiée ne répondent pas au même besoin
Un webhook peut avertir rapidement le récepteur, mais sa réception ne prouve pas que la mise à jour métier a réussi. Le récepteur doit authentifier l’émetteur lorsque le fournisseur le permet, conserver un identifiant stable, répondre dans le délai prévu et rendre le résultat du traitement observable.
Une réconciliation planifiée peut retrouver des éléments manqués ou corrigés, au prix d’un délai et d’une stratégie fiable de curseur ou de fenêtre temporelle. Les deux mécanismes peuvent se compléter. Le contrat réel de l’API détermine les choix possibles.
Doublons, ordre et reprise sûre
- Définir une clé d’idempotence ou de déduplication et sa durée de conservation.
- Utiliser une clé d’idempotence prise en charge par la cible ou une contrainte d’unicité afin qu’un rejeu ne répète pas l’effet métier. Lorsque la cible est sous votre contrôle, une frontière transactionnelle atomique peut valider ensemble la mise à jour et son marqueur d’achèvement.
- Un achèvement enregistré séparément avant l’acquittement ne peut pas, à lui seul, empêcher un effet de bord en double si le processus tombe en panne après la mise à jour cible, mais avant cet enregistrement. Il ne garantit pas une livraison générique exactement une fois ; traiter les résultats ambigus par un rejeu sûr, une réconciliation ou une revue manuelle visible.
- Ne pas supposer l’ordre métier ; relire l’état courant lorsque la documentation du fournisseur le recommande.
- Distinguer les échecs mal formés, non autorisés, temporaires et permanents.
- Limiter les nouvelles tentatives temporaires et rendre visibles les échecs épuisés ou permanents.
- Prévoir un rejeu autorisé, tracé et protégé contre une seconde mise à jour accidentelle.
Cas de recette
- Un événement valide crée la mise à jour mappée attendue.
- Le même événement reçu deux fois ne produit qu’une mise à jour métier.
- Un ancien événement reçu plus tard n’écrase pas un état de référence plus récent.
- Un événement mal formé ou non authentifié est rejeté sans modification de la cible.
- Un délai dépassé côté cible est visible et peut être repris sans risque.
- Une évolution du mapping ou des accès possède un responsable et un test de non-régression.
Démo éducative synthétique
Démonstration locale de traitement d’événements
Ce scénario déterministe s’exécute uniquement dans votre navigateur. Ce n’est ni une IA, ni une intégration réelle, ni une donnée client, ni un résultat de mission. Il ne transmet et ne conserve rien.
État de la destination simulée
Une approbation humaine est requise avant la mise à jour simulée.
| Événement | Résultat attendu |
|---|---|
| evt_1001 — valide | Validé puis mis en attente d’approbation humaine. |
| evt_1001 — doublon | Détecté par identifiant ; aucune seconde mise à jour. |
| evt_bad — mal formé | Rejeté ; aucune mise à jour. |
Source et portée
Documentation Stripe : Webhooks. Stripe documente son propre comportement pour les signatures, doublons, nouvelles tentatives et ordre des événements. C’est un exemple d’ingénierie concret, pas une affirmation sur toutes les API ni sur la disponibilité ou la pertinence de Stripe pour une entreprise donnée.
