Facturation

L’application billing (applications/billing) est l’outil interne qui produit les factures et les documents réglementaires des formations erevo. Elle orchestre, derrière une interface unique, plusieurs services : HubSpot (le CRM), l’internal-api (le back-office Symfony/Doctrine), le portail financeur FIFPL (of.fifpl.fr), un worker Claude Code pour l’appariement des participants, et la génération de PDF.

C’est l’une des briques les plus riches du monorepo : la logique est portée par une machine à états xstate (billing-app-machine.ts, > 4000 lignes) qui coordonne toutes ces étapes de manière déterministe, avec des mécanismes de synchronisation idempotents et de confirmation par polling difficiles à percevoir depuis l’écran.

Les quatre modules

Après connexion, l’opérateur choisit un module :

Module	Pour quoi	Particularité
DPC	Facturer les sessions financées par l’ANDPC	Parcours financé « court » (consentements + documents)
FIFPL	Facturer les sessions financées par le FIFPL	Parcours financé « complet » avec export portail + appariement + synchro HubSpot
Reports	Vue comptable : rechercher les factures par période et les télécharger (PDF / Excel / ZIP)	Lecture seule
Self-Funded	Facturer une session auto-financée	Parcours minimal : utilisateur → session → facture

Le parcours opérateur (financé)

Connexion
  └─ Choix du module (DPC / FIFPL / Reports / Self-Funded)
       └─ Recherche des transactions HubSpot (n° de session + référence financeur)
            └─ Chargement des sessions depuis l'internal-api
                 └─ [FIFPL] Export FIFPL → appariement (Claude) → synchro HubSpot → confirmation propagation
                      └─ Validation (noms, dates, consentements)
                           └─ Génération des documents (facture → traçabilité → relevés → signatures)
                                └─ Sauvegarde du dossier de facturation (billing_file) dans l'internal-api

Services orchestrés

Service	Rôle dans la facturation
HubSpot	Source des transactions (deals) à facturer ; destination des noms/montants FIFPL synchronisés
internal-api	Sessions, étudiants, consentements, classes virtuelles, dossiers de facturation persistés
puppeteer-service	Télécharge l’export XLSX des participants depuis `of.fifpl.fr`
worker Claude Code	Apparie les participants FIFPL de l’XLSX aux transactions HubSpot
pdf	Rend les `DocumentProps` en PDF
file-api	Stocke les PDF générés (minio)

Pages de la section

Parcours financé (DPC & FIFPL) — recherche des deals, validation, progression phase-par-phase, cas bi-annuel et avoirs.
Automatisation FIFPL (sous le capot) — export portail, appariement Claude, synchro HubSpot idempotente, confirmation par webhook, découpage CV-12H.
Intégration internal-api — entités lues/écrites, authentification, rôle du webhook HubSpot → internal-api.
Documents & signatures — pipeline de génération séquentielle, rendu PDF, e-signature, persistance.
Erreurs & avertissements courants — guide de dépannage : symptôme, cause et résolution pour chaque erreur/avertissement.

Sous le capot

Machine à états : applications/billing/src/machines/billing-app-machine.ts. États racine checkingAuth / unauthenticated / authenticated ; sous-états choosingModule, dpc, fifpl, reports, selfFunded. Le contexte (150+ champs) suit les résultats de recherche, les pipelines de documents, l’état de synchro FIFPL et les erreurs de validation. Les tags (loading, error, generating, saving…) pilotent l’affichage conditionnel.
API type-safe : tous les appels passent par tRPC (librairies/trpc/src/controller/*) — pas d’appel HTTP brut côté front. Les clients de contexte (HubSpot, internal-api) sont injectés côté serveur.
React Query : utilisé pour les requêtes ad-hoc (recherche d’utilisateur en self-funded, classe virtuelle du dossier) ; les mutations longues sont portées par les actors de la machine.