---
title: "Consommation via OBAPI"
weight: 25
description: "Actualiser automatiquement les quantités des contrats depuis la consommation réelle du mois, en interrogeant des services distants compatibles OBAPI (Usage & Metering)."
---

# 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](https://obapi.org) (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.