Consommation via OBAPI

Consommation via OBAPI

Principe

Par défaut, le module facture les quantités figées des lignes de contrat. La fonctionnalité Consommation via OBAPI va, avant chaque facturation, interroger un service distant compatible OBAPI (capacité Usage & Metering) pour récupérer la consommation réelle du mois de chaque client, et actualiser les quantités en conséquence.

Concrètement : une ligne de contrat = un produit = un service (un abonnement Nextcloud, une plateforme mail, un proxy…). Le service connaît la consommation du client ; le module la relit et l'utilise comme quantité à facturer.

C'est un système opt-in : un contrat sans serveur OBAPI renseigné reste facturé à ses quantités fixes, exactement comme avant.

Comment ça marche

Pour chaque contrat à facturer (mass action, bouton Facturer, ou cron mensuel) qui a un serveur OBAPI renseigné :

  1. Le module appelle GET {serveur}/usage?account={email}&period={AAAA-MM} — un seul appel par contrat.
  2. Chaque mesure remontée est rattachée à une ligne du contrat via le product_ref de la métrique, qui doit correspondre à la référence produit de la ligne.
  3. La valeur est convertie de l'unité OBAPI (octet, comptage, seconde) vers l'unité de la ligne, et devient la nouvelle quantité de la ligne de contrat (persistance comprise).
  4. Un résumé de consommation est ajouté dans la description de la ligne concernée et dans la note publique de la facture.

Les contrats/ lignes sans serveur ou sans métrique correspondante ne sont pas modifiés.

Configuration

1. Enregistrer le ou les serveurs OBAPI

Allez sur la page Configuration - Modules - Multicontractsoneinvoice, puis Serveurs OBAPI (consommation) (ou directement /multicontractsoneinvoice/admin/obapi_providers.php), et créez une entrée par serveur :

Champ Valeur
Code Identifiant court et stable (ex. NC-A, MAIL). C'est lui que l'on renseignera sur les contrats.
Libellé Nom lisible (ex. « Nextcloud cluster A »).
URL de base L'URL OBAPI avec /obapi/v1, ex. https://nc-cluster.exemple.com/obapi/v1.
Jeton (Bearer) La clé d'API fournie par le serveur (champ masqué).
Actif Cochez pour le rendre utilisable.

La clé (Bearer) vit ici, une seule fois par serveur : la rotation d'une clé se fait en un seul endroit, et le secret n'est pas dupliqué sur chaque contrat.

2. Lier un contrat à son serveur

Sur la fiche d'un contrat, renseignez les deux champs supplémentaires :

  • Serveur OBAPI (conso) (obapi_provider) : choisissez le serveur dans la liste. Un contrat = un seul serveur (celui qui héberge l'ensemble de ses services).
  • Compte OBAPI (email) (obapi_account) : l'email du compte client sur ce service (paramètre account de /usage). Laissez vide pour utiliser l'email principal du tiers.

3. Côté serveur : le product_ref

Côté service distant, chaque métrique exposée doit porter un product_ref égal à la référence produit utilisée dans Dolibarr. Sans cette correspondance exacte, la ligne n'est pas actualisée.

Unités et conversion

Les valeurs OBAPI sont en unités SI : byte (octet), count (comptage), second (seconde). Le module les convertit vers l'unité de la ligne de contrat en s'appuyant sur le libellé de l'unité Dolibarr (llx_c_units) :

  • byte → o, Ko, Mo, Go, To (multiplicateurs décimaux : 1000 par échelon)
  • second → s, min, h, jour
  • count → la valeur brute (comptage direct)

Si le libellé de l'unité de la ligne n'est pas reconnu pour une métrique en octets/secondes, la quantité du contrat est conservée et un avertissement est journalisé. Vérifiez alors l'unité affectée à la ligne.

Comportement en cas d'échec

Quand un serveur OBAPI ne répond pas (indisponibilité, mauvaise clé, compte introuvable…), la constante MULTICONTRACTSONEINVOICE_CONSUMPTION_FAILMODE décide de la conduite à tenir :

Valeur Comportement
block (défaut) Le contrat n'est pas facturé sur cette période ; l'erreur est remontée (message en mass action, journal pour le cron). On évite de facturer un montant faux.
skip Les lignes concernées sont sautées, le reste du contrat est facturé aux quantités fixes.
existing Le contrat est facturé aux quantités du contrat (sans actualisation), avec un avertissement.

Modifiez cette constante dans Configuration - Autres setup si besoin.

Points d'attention

  • L'URL de base doit comprendre /obapi/v1 (le module ajoute lui-même /usage et /usage/metrics).
  • Le product_ref de la métrique doit exactement correspondre à la référence produit de la ligne.
  • Un contrat sans serveur OBAPI renseigné n'est jamais modifié : il est facturé tel quel.
  • L'actualisation s'applique à tous les chemins de facturation (mass action, bouton Facturer, cron) — il n'y a rien de spécial à faire selon le mode de déclenchement.
Configuration Utilisation