Conception d’intégration complexe
Architecture proposée · parcours client à documenter
Le scénario est terminé. Le métier a-t-il le bon résultat ?
Au départ…
Des traitements peuvent réussir partiellement, recevoir une réponse tardive ou manquer un événement. Un tableau de bord vert ne suffit pas à expliquer les écarts entre les systèmes.
L’architecture proposée
Un rapprochement périodique des références Stripe, Airtable et Sage, avec pagination, contrôles de cohérence, exceptions affectées et reprise depuis une étape identifiée.
- 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
Donner aux opérations une liste exploitable des écarts et une manière maîtrisée de les résoudre.
Comment c’est construitModèle de données, code, contrôles et autonomie des équipes
Parcours utilisateur
- 01
Collecter les références sur une période avec recouvrement.
- 02
Comparer les états et classer les écarts.
- 03
Réconcilier ou faire valider la reprise, puis enregistrer son résultat.
Structure des données et des échanges
| Entité / table | Champs clés | Relations |
|---|---|---|
| Rapprochements | Période · curseur · compteurs · statut | Point de reprise enregistré |
| Écarts | Référence source · état attendu · état observé | Un problème métier peut concerner plusieurs événements |
| Décisions de reprise | Responsable · motif · validation · résultat | Tracer l’autorisation de l’étape suivante |
Implémentation technique
- Paginer les API et respecter leurs limites ; enregistrer un point de reprise.
- Utiliser une période de recouvrement et des clés stables pour inclure les événements tardifs.
- Séparer erreur de transport, refus métier et résultat distant inconnu ; chaque catégorie a une suite différente.
Décision d’ingénierie
Choisir la reprise selon ce que le destinataire a pu faire
Politique de reprise proposée. Un timeout après envoi impose un rapprochement ; un rejet métier nécessite une revue. Seul un échec connu avant envoi reçoit une attente exponentielle bornée et variable, respectant Retry-After. Les longues attentes sont différées. Planification persistée, checkpoints et classification propre au destinataire restent hors fonction.
type Failure = | { kind: "business-rejection"; code: string } | { kind: "outcome-unknown" } | { kind: "not-sent"; retryAfterMs?: number };export function recoveryPolicy( failure: Failure, attempt: number, random = Math.random,) { if (failure.kind === "business-rejection") { return { next: "human-review", code: failure.code } as const; } if (failure.kind === "outcome-unknown") { return { next: "reconcile-before-write" } as const; } if (!Number.isSafeInteger(attempt) || attempt < 0 || attempt >= 6) { return { next: "escalate" } as const; } const ceiling = Math.min(60_000, 1_000 * 2 ** attempt); const jitter = Math.floor(Math.max(0, Math.min(1, random())) * ceiling); const retryAfter = failure.retryAfterMs ?? 0; if (!Number.isFinite(retryAfter) || retryAfter < 0) { return { next: "escalate" } as const; } const delayMs = Math.max(retryAfter, jitter); return { next: delayMs > 60_000 ? "defer" : "schedule-retry", delayMs, } as const;}// A response timeout is NOT evidence that no remote write occurred.// Persist the decision; do not hold a Zap step open with a long sleep.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é.