---
title: "Surveiller une facturation récurrente (SaaS)"
weight: 130
description: "Réglages conseillés pour ne jamais surfacturer ni sous-facturer un client d'abonnement : fenêtre d'historique, seuils MAD, factures modèles en brouillon, et lecture des écarts récurrents."
---

# 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.