API Dolibarr : intégration Méthode orienté performance

Par [Nom du professionnel] – Expert ERP & intégrations open‑source

1. Introduction

Dolibarr est un ERP/PGI (Projet de Gestion Intérieure) open‑source très populaire grâce à sa simplicité d’utilisation et à son architecture modulaire. L’un de ses points forts est son API REST (et JSON over HTTP) qui permet d’échanger des données avec d’autres applications, d’automatiser des processus ou de créer des interfaces dédiées (mobile, BI, IoT…).

Cependant, comme tout service web, l’API peut devenir un goulot d’étranglement si elle est mal utilisée : appels uniques répétés, chargement de tous les champs à chaque requête, absence de pagination ou de filtre, etc.

Cet article propose une méthodologie orientée performance pour concevoir, implémenter et tester l’intégration avec l’API Dolibarr. Nous détaillerons :

Les principes de base des API Dolibarr.

Les bonnes pratiques architecturales et de code.

Les techniques d’optimisation (caching, batch, pagination, asynchronisme).

Le dimensionnement & la mesure de performance.

Les outils et scripts d’aide à la mise en œuvre. —

2. Rappels sur l’API Dolibarr

Aspect	Détails
Protocole	HTTP/HTTPS, méthode `GET/POST/PUT/DELETE`.
Authentification	Token (`$_GET['token']` ou `$_POST['token']`) ou session PHP native (déconseillé en environnement externe).
Format de données	JSON (défaut) ou format URL‑encoded selon le paramètre `format`.
Points d’entrée	`/dolibarr/index.php?route=...&token=XYZ` → actions prédéfinies (ex. `get_for_cards`, `getentitylist`, `getobjectbyid`, `genDocument`).
Version	Depuis Dolibarr 7, l’API est stabilisée ; les paramètres `route` restent compatibles dans les versions mineures.
Documentation officielle	https://github.com/Dolibarr/dolibarr/wiki/JSON-RPC-API

3. Méthodologie orientée performance

3.1. Analyse des besoins fonctionnels et non‑fonctionnels

Cartographier les flux
- Identifier chaque appel API attendu (ex. « liste des fournisseurs », « création d’une facture », « lecture d’un champ personnalisé »).
- Regrouper les appels par périodicité (temps réel, batch, périodique).

Définir les exigences SLA
- Latence maximale admissible (ex. < 200 ms pour les appels critiques).
- Charge prévue (nombre de requêtes/sec, volume de données).
- Niveau de disponibilité (99,9 % etc.).

Choisir le type d’intégration
- Synchronisation en temps réel → appels ponctuels, latence faible.
- Batch / réplicas périodiques → traitement différé, possibilité de « queue ».

3.2. Conception des requêtes

Technique	Description	Impact performance
Filtrage côté serveur	Utiliser les paramètres `range`, `limit`, `filters` pour ne récupérer que les champs nécessaires.	Évite le téléchargement de jeux de données massifs.
Projection de champs	Spécifier uniquement les attributs requis (`fields=:id,name,address`).	Réduit le payload (JSON) de ~70 % dans les cas typiques.
Versionnage explicite	Ajouter `?version=1` (ou équivalent) pour éviter les évolutions inattendues et permettre le cache.	Facilite le contrôle de la taille des réponses.
Compression HTTP	Activer `gzip` via `Accept-Encoding: gzip` côté client.	Diminution de la bande passante, latence réseau réduite.

Exemple d’appel optimisé :

GET /dolibarr/json.php?fc=module&module=product&function=getlist&range=0-49&criteria=visible=1 HTTP/1.1

Host: api.mydolibarr.com

Accept: application/json

Gzip-Threshold: 1024```
---
### 3.3. Architecture d’intégration

+————————–+ +——————–+	Application source		Dolibarr (API)		(micro‑service / ETL)	<—–>	(REST / JSON)	+————————–+ HTTP +——————–+ \ ^ — Wrapping

           v      v

      Queue (RabbitMQ / Kafka)   ← async fallback```

Gateway API : placer un reverse‑proxy (NGINX, Traefik) devant l’API Dolibarr pour gérer la throttling, le caching et la mise en place d’un rate‑limit configurable.

Micro‑service métier : wrapper léger (Python FastAPI, Node.js Express) qui expose les appels nécessaires :
- Ajoute un gateway token dynamique.
- Gère les circuit‑breaker (Hystrix) pour éviter les cascades d’erreurs. 3. File d’attente : lorsqu’une latence > 150 ms ou qu’un appel critique échoue, déléguer le traitement à une queue (RabbitMQ, AWS SQS) afin de garantir la continuité.

4. Optimisations avancées

4.1. Caching HTTP‑level

Niveau	Technique	Implémentation
Cache de réponse	Stocker les JSON dans Redis/Memcached pendant T secondes (TTL).	`GET /dolibarr/...` → si `Cache‑Hit` → renvoyer le contenu stocké, sinon récupérer → `SETEX` dans Redis.
Cache côté serveur	Activer le Cache de Dolibarr (`$conf->api` dans `conf/conf.php`) avec `cache_ttl`.	Limite la même requête pendant `N` secondes sans toucher à la base.
Cache de requêtes	Utiliser `Vary: Accept-Encoding` et `ETag` pour profiter du cache CDN.	`ETag` généré à partir du hash des paramètres et du payload.

Règle d’or : Cachez uniquement les données non‑sensibles ou qui changent de façon prévisible (listes de référence, catalogue de pays, etc.).

4.2. Batch & Multi‑entity

API getlist accepte range et filter pour récupérer plusieurs enregistrements en une seule requête. Exemple :
```
GET /dolibarr/json.php?fc=module&module=client&function=getlist&maxrus=200&criteria=id>0
```

Limite : Le serveur a une capacité de traitement ; ne dépassez pas maxrus=500 par appel pour éviter les timeouts.

Batch token : Créez un token dédié avec les droits read uniquement, afin de réduire les permissions et d’éviter les contrôles d’autorisation lourds.

4.3. Asynchronisme & Queue

Call‑pattern « fire‑and‑forget »
- POST /dolibarr/json.php avec function=createorder → réponse 202 Accepted + job_id.
- Le micro‑service produit un message contenant job_id.
- Un worker consomme le message, effectue le polling du statut et consigne le résultat.

Retry exponential back‑off – 1ʳᵉ retry : 1 s
- 2ᵉ retry : 2 s
- 3ᵉ retry : 4 s … jusqu’à 30 s, puis "<< failed >>".

Persist‑in‑DB
- Stocker les informations de transaction dans une table de contrôle (api_log) avec status, last_error, attempts. ### 4.4. Dimensionnement & Scaling

Ressource	Paramètre à ajuster	Méthode de test
Threads du serveur web	`MaxRequestWorkers` (NGINX)	Test de charge avec wrk ou k6 jusqu’à 10 000 RPS.
Base de données Dolibarr	`innodb_buffer_pool_size` → 50 % de RAM	Utiliser le slow query log pour identifier les requêtes lourdes.
Cache Redis	`maxmemory-policy allkeys-lru`	Mesurer le hit‑rate via `INFO command_stats`.
Load‑balancer	Sessions sticky désactivées (si possible)	Utiliser Round‑Robin pour répartir les appels.

Exemple de test de charge (k6)

« `jsimport http from ‘k6/http’;
import { check, sleep } from ‘k6’;

export let options = {
stages: [
{ duration: ’30s’, target: 200 }, // ramp‑up
{ duration: ‘2m’, target: 200 }, // steady
{ duration: ’30s’, target: 0 }, // ramp‑down
],
thresholds: {
http_req_duration: [‘p95<500’], // 95 % < 500 ms
},
};

export default function () {
const url = ‘https://api.mydolibarr.com/dolibarr/json.php‘;
const params = {
headers: { ‘Authorization’: ‘Token xyz’, ‘Accept’: ‘application/json’ },
params: {
‘fc’: ‘module’,
‘module’: ‘product’,
‘function’: ‘getlist’,
‘range’: ‘0-99’,
‘criteria’: ‘visible=1’,
},
};
const res = http.get(url, params);
check(res, { ‘status 200’: (r) => r.status == 200 });
sleep(0.5);
}



---
## 5. Méthodes de mesure et de suivi  
| Métrique | Outil | Pourquoi |

|----------|-------|----------|

| **Latence moyenne** | Grafana + Prometheus (`histogram_http_request_duration_seconds`) | Détecter les régressions de performance. |

| **Débit (RPS)** | k6, artillery.io | Évaluer la capacité sous charge. |

| **Taux d’erreur HTTP 5xx** | ELK / Loki | Identifier les pannes du serveur ou dépassements de timeout. |

| **CPU / RAM du serveur Dolibarr** | `top`, `htop` ou `vmstat` | Charger la base et identifier les goulots d’étranglement. |

| **Cache‑Hit Ratio** | Prometheus (`redis_keyspace_hits`, `redis_keyspace_misses`) | Vérifier l’efficacité du cache. |

| **Temps de réponse par type d’appel** | Table des logs (`api_log`) | Corréler l’impact des filtres (`criteria`) sur le temps de réponse. |
**Dashboard recommandé** (Grafana) :
- **Panel 1** : Latence par endpoint (histogram).  

- **Panel 2** : RPS par minute.  - **Panel 3** : Erreurs 5xx et 4xx.  

- **Panel 4** : Cache‑Hit Ratio vs. Miss Ratio.  

- **Panel 5** : Utilisation CPU/RAM du serveur Java (si Dolibarr en mode PHP‑FPM, suivre le processus `php-fpm`).  
---
## 6. Checklist « Performance‑Ready » avant mise en production  
| ✅ | Action |

|----|--------|

| 1 | Utiliser uniquement les champs nécessaires (`fields=`) et activer la compression gzip. |

| 2 | Activer le cache interne de Dolibarr (`$conf->api` + `cache_ttl` dans `conf.php`). |

| 3 | Limiter chaque appel à **maxrus ≤ 500** et appliquer un **range** précis. |

| 4 | Implémenter un **rate‑limit** côté reverse‑proxy (ex. `limit_req_zone`). |

| 5 | Créer un token dédié avec les droits minimalistes (lecture uniquement pour les appels massifs). |

| 6 | Mettre en place un mécanisme de **circuit‑breaker** (ex. Resilience4j si Java, Polly si .NET). |

| 7 | Utiliser une **file d’attente** pour les traitements critiques (> 150 ms ou failures > 2%). |

| 8 | Configurer des **tests de charge** (k6 / JMeter) avant tout déploiement. |

| 9 | Surveiller les métriques (latence, erreur, cache‑hit) via Prometheus/Grafana. |

| 10 | Documenter le **SLA** et communiquer les seuils à l’équipe projet. |
---
## 7. Exemple de mise en œuvre concrète (Python + FastAPI)
```python

from fastapi import FastAPI, HTTPException, Request

import httpx

import aioredis

import asyncio
app = FastAPI()

redis = None   # dépendance injectée dans la prod
API_ROOT = "https://api.mydolibarr.com/dolibarr/json.php"
async def get_api_token():

    # générer un token à partir d'un secret stocké (ex. Vault)

    # ou recupérer le token partagé depuis une config.

    return "YOUR_DOLIBARR_TOKEN"
async def proxy_get(endpoint: str, params: dict):

    token = await get_api_token()

    full_url = f"{API_ROOT}?{endpoint}"

    async with httpx.AsyncClient(timeout=15.0) as client:

        resp = await client.get(full_url, params=params, headers={"Authorization": token})

        if resp.status_code != 200:

            raise HTTPException(status_code=resp.status_code, detail=resp.text)

        data = resp.json()

        # Cache 10 s dans Redis (key = endpoint + hash(params))

        cache_key = f"api:{endpoint}:{hash(str(sorted(params.items())))}"

        cached = await redis.get(cache_key)

        if cached:

            return cached

        await redis.setex(cache_key, 10, resp.content)

        return resp.content
@app.get("/products")

async def get_products(limit: int = 50, visible: int = 1):

    params = {

        "fc": "module",

        "module": "product",

        "function": "getlist",

        "range": f"0-{limit-1}",

        "criteria": f"visible={visible}",

    }

    payload = await proxy_get("fc=module&module=product&function=getlist", params)

    return payload  # FastAPI renvoie automatiquement JSON

Points forts du code :
- Utilisation d’AIOHTTP/FastAPI → appels non bloquants.
- Cache côté Redis avec TTL fixe.
- Timeout configurable pour protéger contre des réponses lentes.
- Pas debindung directe aux objets Dolibarr internes, donc aucune fuite de version.

8. Conclusion

Intégrer l’API Dolibarr de façon orientée performance ne consiste pas seulement à appeler la mauvaise URL : il faut :

Comprendre le comportement de l’API (paramètres range, criteria, fields).

Isoler les risques (caches, throttling, limites de charge) avec des mécanismes de circuit‑breaker et de rate‑limit.

Optimiser chaque appel (filtrage, projection, compression). 4. Externaliser les traitements lourds vers des queues asynchrones ou du batch.

Mesurer, monitorer et itérer grâce aux outils de métriques modernes (Prometheus, Grafana, Redis).

En appliquant la méthode décrite ci‑dessus, vous obtiendrez une intégration robuste, capable de supporter plusieurs centaines de requêtes simultanées tout en respectant les exigences de latence et de disponibilité imposées par les environnements industriels modernes.

Bibliographie rapide

Dolibarr official wiki – JSON‑RPC API : https://github.com/Dolibarr/dolibarr/wiki/JSON-RPC-API

FastAPI – Documentation : https://fastapi.tiangolo.com/

k6 performance testing : https://k6.io/docs/

Prometheus – Monitoring API : https://prometheus.io/docs/introduction/overview/

Resilience4j – Circuit Breaker : https://resilience4j.readme.io/docs

Bonne intégration ! 🚀

Cette documentation a été rédigée à destination des équipes techniques souhaitant exploiter l’API Dolibarr dans un contexte à forte exigence de performance.

API Dolibarr : intégration Méthode orienté performance

1. Introduction

2. Rappels sur l’API Dolibarr

3. Méthodologie orientée performance

3.1. Analyse des besoins fonctionnels et non‑fonctionnels

3.2. Conception des requêtes

4. Optimisations avancées

4.1. Caching HTTP‑level

4.2. Batch & Multi‑entity

4.3. Asynchronisme & Queue

Exemple de test de charge (k6)

8. Conclusion

Bibliographie rapide

Comment Dolibarr et la gestion des commandes peut-il améliorer votre productivité ?

Dolibarr comptabilité : Astuces et conseils dʼexperts

Les tendances de Dolibarr et la gestion de la comptabilité en 2025

Automatiser coûts dans Dolibarr : Framework avec intégrations modernes

Mettre à niveau Dolibarr : Letʼs Encrypt pour mieux piloter

Dolibarr et la gestion de la facturation : Avis et témoignages d’utilisateurs

1. Introduction

2. Rappels sur l’API Dolibarr

3. Méthodologie orientée performance

3.1. Analyse des besoins fonctionnels et non‑fonctionnels

3.2. Conception des requêtes

4. Optimisations avancées

4.1. Caching HTTP‑level

4.2. Batch & Multi‑entity

4.3. Asynchronisme & Queue

Exemple de test de charge (k6)

8. Conclusion

Bibliographie rapide

Publications similaires