Surveiller une facturation récurrente (SaaS)

Cas type : votre Dolibarr facture chaque mois des abonnements (contrats SaaS, factures modèles mensuelles). Un client facturé en moyenne 20 EUR par mois ne doit pas passer à 40 EUR ni à 5 EUR sans qu'on le voie. La règle "écart du montant récurrent" (v5) compare ce qui a été facturé au client depuis le début du mois à ce qui lui avait été facturé sur les mêmes jours des mois précédents ; le déclencheur BILL_VALIDATE fait la même comparaison au moment même de la validation de chaque facture.

Comment la règle calcule

• Un client forme une seule série, toutes ses factures confondues, qu'elles viennent d'une facture modèle ou non. Quand vous arrêtez des factures modèles pour en créer de nouvelles (changement de système de facturation, nouvelle offre), les nouvelles prennent le relais sans période aveugle, et un mois facturé à la fois par l'ancien et par le nouveau modèle ressort comme un pic.
• La comparaison se fait de date à date : le 6 du mois, le cumul du 1er au 6 est comparé au cumul du 1er au 6 de chacun des mois précédents. Un client facturé plusieurs fois par mois n'est donc jamais comparé, en milieu de mois, à des mois entiers. Le dernier jour du mois, les mois sont comparés en entier.
• Une tolérance de quelques jours (CAPPATROL_RECUR_DAY_TOLERANCE, 3 par défaut) absorbe une facture émise un peu en avance ou en retard par rapport aux mois précédents : elle n'est ni un pic ni une chute.
• La référence retient les derniers mois non nuls sur ces mêmes jours (5 par défaut, CAPPATROL_RECUR_MONTHS), et il en faut au moins 3 (CAPPATROL_RECUR_MIN_MONTHS) : un client récent n'est jamais signalé.
• Le cumul du mois est signalé quand il s'écarte de la moyenne de la référence d'au moins CAPPATROL_RECUR_SPIKE_PCT (au-dessus, +50 % par défaut) ou CAPPATROL_RECUR_DROP_PCT (en dessous, -50 %), et d'au moins CAPPATROL_RECUR_MIN_DELTA (5 EUR par défaut).
• Une chute n'est confirmée qu'à partir du jour du mois des oublis (CAPPATROL_FORGOTTEN_DAY_OF_MONTH). Un mois encore vide, lui, relève de la règle des oublis.
• Les alertes alimentent l'onglet "Écart récurrent" de la page des anomalies, la liste blanche ("marquer comme normal") et le courriel de notification, comme les autres catégories.

Réglages conseillés pour ce cas

• CAPPATROL_HISTORY_MONTHS = 6 pour "les cinq derniers mois" : à 12, les mois antérieurs à la première facture du client comptaient pour 0 et tiraient la médiane vers le bas ; ce piège est corrigé depuis la v5 (les mois antérieurs à la première facture sont ignorés), mais une fenêtre courte reste plus représentative d'un parc d'abonnements.
• CAPPATROL_IF_MIN_SAMPLES au-dessus du nombre de clients pour forcer le score MAD : au-delà, l'Isolation Forest ne garde que les ~5 % de clients les plus atypiques (plafond CAPPATROL_IF_MAX_FLAGGED), et un écart de 20 à 40 EUR peut être masqué par de plus gros clients.
• Ajustez le seuil MAD avec CAPPATROL_MAD_Z_THRESHOLD (3,5 par défaut).
• Contrôlez avant l'envoi : générez les factures modèles en brouillon, activez CAPPATROL_INCLUDE_DRAFT, puis validez après le scan de 06:00. Le déclencheur BILL_VALIDATE (CAPPATROL_RECUR_TRIGGER) ajoute un événement d'agenda sur chaque facture qui s'écarte de la référence, sans jamais bloquer la validation : la file des factures récurrentes ne casse pas.
• Si vous ne surveillez que des abonnements, CAPPATROL_RECUR_ONLY limite la règle aux factures issues d'une facture modèle, quel que soit le modèle.
• Le déclencheur n'est pris en compte qu'après une désactivation puis une réactivation du module (Configuration -> Modules) sur une installation existante.

Faux positifs attendus d'un SaaS à mois calendaire

• Premier mois d'une commande en cours de mois : le prorata au jour puis le mois suivant donnent parfois deux factures. Sans historique suffisant la règle récurrente se tait ; si la détection générale le signale comme pic, le bouton "marquer comme normal" absorbe l'alerte.
• Dépassement de forfait facturé : c'est un vrai pic, mais légitime ; le commentaire d'agenda du déclencheur rappelle le montant de référence pour trancher, et la liste blanche couvre la période.