Erreurs & avertissements courants

Cette page recense les erreurs (bloquantes) et avertissements (non bloquants) que l’app de facturation affiche à l’opérateur, leur déclencheur, et la résolution. Les messages sont cités tels qu’ils apparaissent à l’écran.

Comment les messages apparaissent

• Icône d’erreur par ligne dans le DataGrid + panneau dépliable listant les écarts de validation d’une transaction.
• Alertes inline (BillingAlert) en haut de la zone de travail (succès, avertissement, erreur).
• Snackbars pour les erreurs de génération/sauvegarde de documents.

Note

La synchronisation FIFPL est best-effort : les participants non appariés produisent des avertissements (la liste « Participants non trouvés sur FIFPL »), pas des erreurs bloquantes. On peut continuer et corriger manuellement.

Tableau de référence rapide

Catégorie	Causes fréquentes	Action opérateur
Validation (transaction ↔ session)	Le deal HubSpot et la session ENT divergent	Corriger le deal HubSpot ou la session, puis rafraîchir la ligne
Export FIFPL	NACPRO/date erronés, identifiants, 403, captcha, schéma XLSX modifié	Selon le message (voir §2) ; souvent vérifier le compte erevofifpl ou réessayer
Appariement (worker Claude)	Worker indisponible ou trop de participants	Le repli déterministe s’active ; vérifier les noms non appariés
Synchro HubSpot	Propriété invalide, limite d’API, réseau	Vérifier les propriétés du deal/contact, réessayer
Confirmation propagation	Webhook HubSpot → ENT en retard (>90 s)	Réessayer ou ignorer (ignorer = vérifier manuellement)
Génération / sauvegarde	Données de session, signatures, conflit de n° de facture	Régénérer, recharger, ou réattribuer le numéro

---

1. Validation (transaction ↔ session)

Avant toute génération, l’app compare chaque transaction HubSpot à la session ENT correspondante (funded-deal-validation.ts). Tout écart est listé sous la ligne.

Message	Déclencheur
Aucune session trouvee pour ce deal CRM	Aucune session ENT ne correspond au crmID du deal
Numéro de session : deal "X" vs session "Y"	session_number du deal ≠ numéro de la session
Date de début : deal "X" vs session "Y"	Date de début du deal ≠ session (format AAAA-MM-JJ)
Date de fin : deal "X" vs session "Y"	Date de fin du deal ≠ session
Nom DPC : deal "X" vs session "Y" (FIFPL : Nom FIFPL : …)	Nom de famille divergent (comparé en minuscules, espaces retirés)
Prénom DPC : deal "X" vs session "Y" (FIFPL : Prénom FIFPL : …)	Prénom divergent

L’app vérifie aussi la cohérence interne des données de session (FundedBillingPage.tsx) :

Message	Déclencheur
Référence financeur manquante	Aucune version trouvée pour la date d’inscription, ou référence vide
Nom DPC manquant / Prénom DPC manquant (resp. FIFPL)	Nom/prénom de l’étudiant vide
Numéro de session manquant	Session sans numéro
Date de début invalide / Date de fin invalide	Date non interprétable
La date de début doit être antérieure à la date de fin	Début ≥ fin

Résolution : corriger la propriété du deal dans HubSpot ou la donnée dans l’ENT, puis utiliser rafraîchir la ligne (re-fetch deal + session, recalcul des erreurs) — voir Parcours financé. À noter : les consentements non approuvés bloquent la génération des documents pour les formats hors classe virtuelle.

Sous le capot : applications/billing/src/machines/funded-deal-validation.ts, applications/billing/src/pages/funded/FundedBillingPage.tsx.

---

2. Export FIFPL (portail of.fifpl.fr)

Le téléchargement de l’XLSX peut échouer. L’app distingue les erreurs transitoires (un seul réessai automatique à 1 s : OOM Chromium, aléa réseau) des erreurs déterministes (échec immédiat, réessayer ne sert à rien). Les messages opérateur :

Message à l’écran	Cause	Résolution
Identifiants FIFPL refusés par le portail. Vérifiez le compte erevofifpl.	Identifiants du compte erevofifpl rejetés	Mettre à jour les identifiants du compte
FIFPL demande un captcha. Connectez-vous manuellement à of.fifpl.fr pour le résoudre, puis relancez la sync.	Captcha / interstitiel WAF après une sonde 403	Se connecter manuellement à of.fifpl.fr, résoudre le captcha, relancer
Téléchargement FIFPL refusé (403). Réessayez plus tard ; si le problème persiste, ouvrez of.fifpl.fr pour vérifier l'état du compte.	Accès interdit (403)	Réessayer ; vérifier l’état du compte sur le portail
FIFPL refuse le téléchargement après reconnexion automatique. Réessayez plus tard ou contactez le support.	La reconnexion intégrée a tourné mais le 2ᵉ téléchargement reste 403	Réessayer plus tard ou escalader
Téléchargement FIFPL impossible: {détail}	Cas non couvert ci-dessus (NACPRO/date erronés → « Aucun dossier FIFPL », filtre ambigu → « Plusieurs dossiers FIFPL », schéma XLSX modifié → colonnes manquantes, puppeteer-service injoignable / réponse inattendue)	Lire le détail ; vérifier le NACPRO + la date de fin ; si schéma modifié, contacter le support

Attention

Un NACPRO ou une date de fin erronés se manifestent généralement par un 403 ou un message « Aucun dossier FIFPL » : vérifier d’abord ces deux paramètres avant de suspecter le compte. Voir le flux d’identification du dossier dans Automatisation FIFPL.

Sous le capot : librairies/trpc/src/controller/fifpl/fifpl-client.ts (DETERMINISTIC_ERROR_PATTERNS), mapping vers le message opérateur dans formatFifplWarning (billing-app-machine.ts).

---

3. Appariement des participants (worker Claude)

Avertissement	Cause	Résolution
Appariement Claude indisponible, méthode déterministe utilisée	Worker injoignable, timeout (180 s), ou réponse non exploitable	Aucune action requise : le repli déterministe s’active automatiquement
Aucune ligne FIFPL pour {prénom} {nom}	Aucune ligne de l’XLSX ne correspond à ce participant	Télécharger l’XLSX (bouton de l’alerte), vérifier le nom manuellement

Ces avertissements s’affichent sous le titre « Participants non trouvés sur FIFPL » et sont non bloquants.

Sous le capot : librairies/trpc/src/controller/fifpl/worker-client.ts, applications/billing/src/machines/fifpl-row-matcher.ts.

---

4. Synchronisation HubSpot

Avertissement	Cause	Résolution
Synchronisation FIFPL — échec HubSpot ({ids}): {message}	Un lot d’écriture HubSpot a échoué (ex. propriété invalide, limite d’API)	Lire le message HubSpot ; vérifier les propriétés des contacts/deals cités ; relancer la sync

La synchro est idempotente et écrit par lots de 100 : un lot en échec n’interrompt pas les autres, et relancer ne touche que ce qui manque encore (voir Automatisation FIFPL).

Sous le capot : librairies/trpc/src/controller/billing/index.ts (syncFifplParticipantNames, hubspotErrorMessage).

---

5. Confirmation de propagation (webhook ENT)

Après la synchro, l’app attend que le webhook HubSpot → ENT propage les noms. Au-delà de 90 s :

Synchronisation FIFPL non confirmée côté ENT après 90s {n} dossier(s) en attente. Le webhook HubSpot → ENT n’a pas mis à jour le(s) participant(s) suivant(s) : …

Deux boutons : Réessayer la vérification (re-poll l’ENT — utile si la propagation a juste pris du retard) ou Ignorer et continuer.

Attention

Ignorer est risqué : les noms peuvent ne pas encore être à jour côté ENT. Si vous ignorez, vérifiez manuellement les dossiers listés avant de finaliser.

Un échec de rafraîchissement des sessions après la synchro produit aussi l’avertissement Rafraîchissement des sessions impossible après synchronisation FIFPL: {détail}.

Sous le capot : état confirmingFifplSync dans applications/billing/src/machines/billing-app-machine.ts.

---

6. Génération & sauvegarde des documents

Ces erreurs s’affichent en snackbar / alerte pendant la génération ou la sauvegarde. Quand le code dispose du détail technique, le message générique est remplacé par le message d’erreur sous-jacent.

Message	Étape
Erreur lors de la génération des données du document	Construction des DocumentProps (session invalide, données manquantes)
Erreur lors de la génération du PDF	Rendu PDF
Erreur lors de la récupération des signatures	Récupération des documents de signature
Erreur lors de la régénération des signatures	Réapplication des signatures dactylographiées manquantes (sessions du 01/01/2026 à hier)
Erreur lors de l'upload des documents	Upload des médias (file-api / S3)
Erreur lors de l'enregistrement du dossier	Sauvegarde du billing_file dans l’ENT
Le numéro de facture était déjà utilisé. Un nouveau numéro a été attribué, veuillez relancer la sauvegarde.	Conflit de numéro résolu automatiquement → relancer la sauvegarde
Le numéro de facture est déjà utilisé. Veuillez recharger la page.	Conflit non résolu → recharger la page
Erreur lors de la génération de la facture semestrielle 2 (et variantes PDF / upload / … enregistrement du 2e dossier semestriel)	Facturation bi-annuelle : seconde facture
Échec du découpage FIFPL : {détail} / Échec du découpage FIFPL — merci de réessayer	Découpage CV-12H en 4 demi-journées
Erreur lors de la création de l'avoir	Création d’un avoir (credit note)

Avertissement « sessions modifiées » (non bloquant mais important) :

Attention des sessions ont été ajoutées/modifiées depuis la dernière régénération des documents, merci de les générer à nouveau.

La sauvegarde est désactivée tant que les documents n’ont pas été régénérés — voir Documents & signatures.

Sous le capot : états generatingProps / generatingPDF / uploadingDocuments / savingBillingFile / resolvingBillNumberConflict / applyingCreditNote dans applications/billing/src/machines/billing-app-machine.ts.

---

7. Connexion & recherche

Message	Cause	Résolution
Identifiants incorrects	Connexion refusée (ou message d’erreur réseau)	Vérifier les identifiants de l’app
Erreur lors de la récupération des sessions	Échec du chargement des sessions depuis l’ENT	Bouton Réessayer
Erreur lors de la récupération de l'étudiant (self-funded)	Recherche utilisateur échouée	Réessayer / vérifier la saisie

Les erreurs de recherche HubSpot s’affichent dans la carte de recherche avec un bouton Réessayer.

Sous le capot : états authenticating, searching, fetchingSessions dans applications/billing/src/machines/billing-app-machine.ts.