Aller au contenu

ADR-0023 — Modèle d'intégration FISCAL ↔ BOOKS : API partagée (Modèle C), transport HTTP via SLY

Date : 2026-04-12 (arbitrage) — formalisée en ADR le 2026-06-30 Catégorie : A (modèle d'intégration technique entre deux domaines déjà figés) Décideur : Lead architecte DYNORS (avec équipe FISCAL / BOOKS) Statut : Acceptée (contrat CONTRAT_EVENTS_BOOKS.md posé ; handler BOOKS + OpenAPI à finaliser) S'appuie sur : [[0004-perimetre-fige-fiscal-books-paiement]] (frontière FISCAL/BOOKS), [[0005-patron-api-b2b-stripe-style]] (style API) Source de vérité : docs/REPONSES_QUESTIONS_FISCAL_BOOKS.md (Synthèse Phase 0 + Décision transport), docs/CONTRAT_EVENTS_BOOKS.md, docs/STABILISATION.md §2.6

Contexte

BOOKS (comptabilité SYSCOHADA) doit générer des écritures à partir des documents fiscaux produits par FISCAL. Trois positionnements étaient ouverts au démarrage de BOOKS (Phase 0) :

  • Modèle A — séparation nette : FISCAL et BOOKS deux produits totalement indépendants, BOOKS reconstruit son propre référentiel. Risque de duplication (notamment TVA traitée deux fois).
  • Modèle B — BOOKS absorbe FISCAL : produit financier unique, FISCAL devient un module interne. Refonte massive, risque de régression sur FISCAL existant, délai important.
  • Modèle C — API partagée / progressive : FISCAL reste source de vérité des documents fiscaux et des montants ; BOOKS consomme ces données pour produire écritures et déclarations. Non destructeur, cohérent avec l'écosystème.

Constat factuel : FISCAL ne génère pas d'écritures comptables ni de déclarations TVA agrégées (il n'y a donc rien à « extraire » de FISCAL), le modèle tenant (tenant_code) est commun, et dynors-events n'est pas démarré (non prioritaire avant M6-M12). Le choix doit donc être implémentable sans bus et sans refonte FISCAL.

Décision

  1. Modèle C retenu. FISCAL est la source unique de vérité des factures, certifications et montants fiscaux. BOOKS consomme (références + montants) pour générer écritures, journaux et déclarations — il ne crée pas de factures et ne tient pas de base TVA parallèle.

  2. Responsabilité déclaration TVA = BOOKS. FISCAL certifie les ventes auprès de la DGI ; BOOKS produit les déclarations TVA périodiques agrégées (dérivées des données FISCAL). Pas de double porteur — cohérent avec [[0004-perimetre-fige-fiscal-books-paiement]].

  3. Transport MVP = HTTP synchrone via SLY. Les émetteurs (FISCAL, satellites) appellent POST /books/api/v1/events au format de l'enveloppe CONTRAT_EVENTS_BOOKS.md, via InterAppCallService → SLY (/books/**), avec idempotence par eventId. Aucune dépendance à Kafka pour ouvrir la phase BOOKS.

  4. dynors-events optionnel sur ce flux. Quand BOOKS et les émetteurs activeront dynors.events.enabled + un broker, les mêmes types d'événements pourront transiter par le bus sans changer le contrat métier (le payload est identique, seul le transport change).

  5. Modèle commercial laissé ouvert (vente séparée vs bundle) — décision produit/commerciale (catégorie C), hors de cet ADR technique.

Conséquences

Positif : aucune refonte FISCAL ; une seule source de vérité des montants fiscaux ; BOOKS démarrable immédiatement sans bus ; bascule bus ultérieure sans rupture de contrat ; frontière FISCAL/BOOKS respectée et opposable.

Coût : il faut ajouter côté FISCAL/satellites l'émission HTTP vers BOOKS (le flux n'existe pas aujourd'hui) ; idempotence et cohérence header/body (X-Source-App / tenantCode) à implémenter côté BOOKS ; en HTTP synchrone, gérer les échecs/retries applicatifs (mitigé à terme par le bus).

Composants impactés : FISCAL (émission POST /books/.../events après finalisation/certification), satellites (ex. TRACIUM SUPPLIER_PAYMENT), BOOKS (endpoint /events + BooksJournalService), dynors-platform/selebeyone (route /books/**).

Alternatives écartées

  • Modèle A (séparation nette) : duplication du référentiel et risque de double traitement TVA, sans bénéfice par rapport à C. Écarté.
  • Modèle B (fusion BOOKS⊃FISCAL) : refonte massive et régression sur FISCAL en production pour un gain de cohérence que le Modèle C atteint déjà progressivement. Écarté.
  • Transport bus (dynors-events) dès le MVP : bloquant car le bus n'est pas démarré et non prioritaire avant M6-M12. Écarté au profit de HTTP synchrone, le bus restant la cible optionnelle.

Références

  • docs/REPONSES_QUESTIONS_FISCAL_BOOKS.md (§ Synthèse Phase 0, § Décision transport FISCAL→BOOKS)
  • docs/CONTRAT_EVENTS_BOOKS.md (enveloppe, types, idempotence)
  • docs/STABILISATION.md §2.6, docs/DYNORS_EVENTS_ARCHITECTURE.md (cible bus)
  • ADR-0004 (périmètre figé), ADR-0005 (patron API)