Conception d’intégration complexe
Architecture proposée · parcours client à documenter
Un paiement reçu doit retrouver le bon dossier.
Au départ…
Le paiement Stripe, le dossier Airtable et le compte client Sage ne partagent pas forcément le même identifiant. Un événement reçu deux fois ne doit pas créer deux opérations.
L’architecture proposée
Une orchestration avec réception vérifiée de l’événement, rapprochement des identifiants, contrôle des règles métier, action Sage via un adaptateur adapté et suivi du résultat dans Airtable.
- Stripe
Événement vérifié
Récepteur sécurisé et journal transactionnel
- Zapier
Coordination
Airtable pour le suivi, code pour les règles complexes
- Sage
Action via adaptateur
Référence de résultat ou exception à traiter
Schéma de conception, à adapter au Zap réel et à l’édition Sage.
Ce que nous voulons changer
Éviter les doubles traitements et rendre chaque paiement traçable jusqu’au résultat métier attendu.
Comment c’est construitModèle de données, code, contrôles et autonomie des équipes
Parcours utilisateur
- 01
Vérifier l’événement Stripe et conserver sa clé.
- 02
Retrouver le dossier et préparer une demande métier validée.
- 03
Exécuter l’action Sage autorisée, puis enregistrer la référence ou l’exception.
Structure des données et des échanges
| Entité / table | Champs clés | Relations |
|---|---|---|
| Journal des événements | Fournisseur · ID événement · état · empreinte | Clé de réception unique dans un stockage transactionnel |
| Référentiel métier | Client · commande · devise · entité juridique | Correspondances entre systèmes |
| Journal des opérations | Clé métier · référence distante · résultat | Tentatives distinctes de l’événement reçu |
Implémentation technique
- Vérifier la signature sur le corps brut dans le récepteur du webhook.
- Réserver les clés dans un stockage transactionnel : une recherche puis création Airtable ne protège pas des arrivées concurrentes.
- En cas de timeout Sage, rechercher le résultat avant de rejouer une action. Dédupliquer l’événement ne suffit pas à garantir une seule écriture distante.
Décision d’ingénierie
Séparer dédoublonnage des événements et réservation métier
Architecture proposée, pas du code client vérifié. Une transaction stocke l’événement vérifié, réserve l’opération métier et crée un message de sortie. Des contraintes UNIQUE gèrent les livraisons concurrentes. Les adaptateurs restent à implémenter. Écriture Sage et rapprochement sont des traitements séparés ; une version de schéma ne doit pas faire comptabiliser deux fois le même paiement.
type VerifiedPayment = { accountId: string; live: boolean; eventId: string; paymentId: string; legalEntityId: string;};type Transaction = { insertEventIfAbsent(key: string): Promise<boolean>; reserveOperationIfAbsent(key: string): Promise<boolean>; enqueueOutbox(message: { key: string; schemaVersion: 1 }): Promise<void>;};type Ledger = { transaction<T>(fn: (tx: Transaction) => Promise<T>): Promise<T>;};export async function acceptPayment(event: VerifiedPayment, ledger: Ledger) { // Caller verified the raw Stripe signature and resolved the tenant mapping. const namespace = [event.accountId, event.live, event.legalEntityId]; const eventKey = JSON.stringify([...namespace, event.eventId]); const operationKey = JSON.stringify([ ...namespace, event.paymentId, "record-payment", ]); return ledger.transaction(async tx => { if (!await tx.insertEventIfAbsent(eventKey)) return "duplicate-event"; if (!await tx.reserveOperationIfAbsent(operationKey)) { return "operation-already-reserved"; } await tx.enqueueOutbox({ key: operationKey, schemaVersion: 1 }); return "queued"; });}// All three adapters share one durable DB transaction + UNIQUE keys.// Acknowledge the webhook only after commit; an outbox worker invokes Zapier.// No Sage write here. Unknown remote outcomes go to reconciliation first.Extrait adapté de l’implémentation
Contrôles et limites
- Aucune donnée de carte dans Airtable : ne conserver que les références et informations métier nécessaires.
- Les décisions et écritures sensibles ont des droits et validations explicites.
- Le connecteur Sage et les capacités de reprise dépendent de l’édition et du plan retenus.
Qui peut contribuer
- Métier : référentiels, règles validées et traitement des exceptions.
- Builders : étapes Zapier documentées et mappings dans le périmètre prévu.
- Développeurs : contrats d’API, connecteurs sur mesure, tests et versioning.
Ce qui documente ce cas
Exemple d’architecture élaboré pour présenter la méthode. Aucun export ni historique du Zap client n’a encore été consulté ; aucun résultat de production n’est revendiqué.