API Dolibarr : ETL Playbook orienté performance

Version 1.0 – November 2025

1. Introduction

Dolibarr est un ERP/PGIs open‑source très répandu dans les PME. Son architecture REST‑like expose une API qui permet d’interagir avec les entités (clients, factures, stocks, etc.). Lorsqu’on utilise cette API comme source ou cible d’un pipeline ETL (Extract‑Transform‑Load), la performance devient un levier clé : réduit le temps de traitement, diminue les coûts d’infrastructure et améliore la réactivité des tableaux de bord décisionnels.

Ce playbook décrit, étape par étape, comment concevoir, déployer et optimiser un ETL basé sur l’API Dolibarr avec un focus particulier sur les aspects de performance. Chaque section propose des bonnes pratiques, des paramètres de réglage et des outils de monitoring.

2. Architecture générale de l’ETL avec Dolibarr

+-------------------+          +-------------------+          +-------------------+

| Source (API)      |  -->     | Engine ETL (ex.   |  -->     | Système de       |

|  (Dolibarr)       |          |   Python/Apache   |          | Load (BI, DW)    |

+-------------------+          +-------------------+          +-------------------+

                                 |                                 |

                                 v                                 v

                        Transforme les données          Charge les tables cibles

                        (normalisation, agrégats…)          (Datamart, DW, CSV…)

  • Source : API REST de Dolibarr (GET/POST/PUT). Elle est exposée via le module API intégré ou via un reverse‑proxy (NGINX) avec des endpoints /api/dolibarr.

  • Engine : script ou moteur ETL dédié (Python, Node.js, Talend, Pentaho). Ici nous recommandons Python + requests/httpx pour la souplesse et la richesse des bibliothèques de transformation.

  • Load : destination typique : entrepôt de données (Snowflake, PostgreSQL, DuckDB), environnement de reporting (Power BI, Looker).

Note : L’API de Dolibarr est stateless. Chaque appel est indépendante, ce qui simplifie le découpage en lots parallèles, mais impose de gérer les limites de débit (rate‑limit) et les réponses partielles (pagination).

3. Principes de performance à connaître

Axe Impact sur la performance Action prioritaire
Latence réseau Latence du round‑trip HTTP Utiliser un proxy HTTP local (NGINX) + keep‑alive
Débit Nombre d’appels / seconde Batcher les requêtes, exploiter la pagination (max = 1000)
Surcharge I/O E/S disque des scripts Garder les données en mémoire (pandas DataFrames)
Caching Redondance de données Cache des réponses GET / listes (TTL = 15 min)
Concurrency Utilisation du CPU Thread‑pool ou async / concurrent‑AIOHTTP
Monitoring Détection des goulots Métriques Prometheus + Grafana, logs d’erreurs

4. Playbook pas à pas

4.1 Prérequis

  1. Serveur Dolibarr disposant de l’API activée (api/dolibarr.php).

  2. Clé API (token ou login/password) avec droits d’accès aux entités nécessaires.

  3. Python ≥ 3.9 avec les paquets : requests, httpx, pandas, fastapi, uvicorn, python‑dotenv.

  4. Infrastructure ETL : conteneur Docker (ou environnement virtuel) avec accès à la base cible.

  5. Outils de observabilité : Prometheus Node‑Exporter, Grafana.

4.2 Phase 1 – Découpage & Modélisation

Action Pourquoi ?
Identifier les entités à extraire (ex. : Commande, Ligne de commande, Produit) Prioriser les flux à fort impact BI.
Définir périodes (ex. : 24 h, incrémentales) Permet de minimiser le volume d’appels (fetch only deltas).
Étudier le schéma JSON retourné par chaque endpoint Facilite la génération de schémas de destination (tables normalisées).
Créer une matrice de dépendances (ex. : ligne de commande → produit) Détermine les transformations nécessaires avant le chargement.

4.3 Phase 2 – Implémentation du client API

import httpx

import aiohttp

from typing import AsyncGenerator

from datetime import datetime, timedelta

from fastapi import FastAPI, Depends
app = FastAPI()

API_BASE = "https://dolibarr.example.com/dolibarr/api.php"

API_TOKEN = os.getenv("DOLIBARR_TOKEN")
async def fetch_json(endpoint: str, params: dict = None, retries: int = 3) -> AsyncGenerator[dict, None]:

    """

    Génère des objets JSON paginés depuis l'API Dolibarr.

    - Support du paramètre `range` ou `limit` selon l'endpoint.

    - Implémente le back‑off exponentiel en cas d’erreur 5xx.

    """

    headers = {"Authorization": f"Bearer {API_TOKEN}", "Accept": "application/json"}

    async with httpx.AsyncClient(headers=headers, timeout=10) as client:

        url = f"{API_BASE}/{endpoint}"

        page = 1

        while True:

            resp = await client.get(url, params={**({"page": page}, **(params or {}))}

            if resp.status_code != 200:

                # retry logic with exponential back‑off

                await asyncio.sleep(2 ** retry)

                continue

            data = resp.json()

            if not data.get("data"):

                break

            for item in data["data"]:

                yield item

            page += 1

  • Async : S’engage dans la concurrence sans bloquer les flux I/O.

  • Pagination : Utiliser le paramètre range ou offset fourni par l’API (ex. : range=0-999).

  • Rate‑limit : Ajouter un Semaphore pour limiter à N appels parallèles, typiquement 5‑10 selon les quotas de votre serveur.

4.4 Phase 3 – Extraction & Ingestion (Extract)

Étape Exemple de code (Python/pandas) Optimisation
Chunk de 1000 lignes df_batch = pd.DataFrame(list(fetch_json("Commande?range=0-999"))) Charger en mémoire seulement 1 k lignes → faible pression RAM
Normalisation des dates df_batch["date_create"] = pd.to_datetime(df_batch["date_create"], utc=True) dateutil.parser rapide lorsqu’on précise errors="coerce"
Filtrage de delta df_batch = df_batch[df_batch["updated_at"] > last_extraction] Réduit le volume de données à transférer à chaque run

Astuce : Exploiter le paramètre expand=1 de l’API pour récupérer les champs liés (ex. : client_id, client_name) en une seule requête, évitant les appels imbriqués.

4.5 Phase 4 – Transformation (Transform)

  1. Normalisation des clés – Uniformiser les noms de colonnes (order_id → order_id) pour correspondre au modèle étoile.

  2. Agrégations – Exemple : calcul du chiffre d’affaires par jour : 

aggr = (

    df_batch

    .groupby("date_create")

    .agg(total_qty=("qty", "sum"), total_amount=("amount", "sum"))

    .reset_index()

)

  1. Enrichissement – Joindre les tables de référence (produits, clients) déjà chargées en cache : 

products_cache = pd.read_parquet("cache/products.parquet")

aggr = aggr.merge(products_cache, on="product_id", how="left")

  1. Typage – Convertir les colonnes vers les types de la cible (int32, decimal(15,2), etc.) afin de minimiser les conversions côté cible.

Performance : Les DataFrames de pandas sont vectorisés; évitez les iterrows() ou des boucles Python.

4.6 Phase 5 – Chargement (Load)

Destination Méthode recommandée Paramètres de performance
PostgreSQL psycopg2 + COPY (bulk) batch_size=5000 → COPY FROM STDIN
Snowflake snowflake-connector-python + PUT + COPY INTO WAREHOUSE=ETL_WH + MAX_THREADS=16
DuckDB (local) duckdb.sql("INSERT INTO … VALUES …") duckdb.optimize("true") pour le vectorisation interne

Exemple COPY :

« `pythondef load_to_postgres(df: pd.DataFrame, table: str):
conn = psycopg2.connect(dsn=os.getenv("PG_DSN"))

csv_buffer = StringIO()

df.to_csv(csv_buffer, index=False, header=False, sep="\t", quoting=csv.QUOTE_NONE)

csv_buffer.seek(0)

with conn.cursor() as cur:

    cur.copy_expert(f"COPY {table} FROM STDIN WITH (FORMAT CSV DELIMITER E'\\t')", csv_buffer)

conn.commit()



> **Note** : Le **format CSV/TSV** avec délimiteur de tabulation est généralement plus rapide à charger que le CSV standard (pas d’échappement de guillemets).  
### 4.7 Phase 6 – Orchestration & Scheduling  
- **Airflow** (Docker `apache/airflow`) : créer un DAG qui orchestre les étapes **extract → transform → load**.  

- **Docker Compose** : regrouper le script ETL, le client API, le moteur de transformation et le serveur de métriques.  

- **Cron** : solution plus légère (script `run_etl.sh` lancé toutes les heures).  
```bash

#!/usr/bin/env bash

set -euo pipefail

docker compose up etl-job --build

  • Ajouter retry logic au niveau du DAG (max = 2 retries).

5. Optimisations avancées

5.1 Caching des réponses d’API

  • Redis (redis-py) stocke les réponses JSON des endpoints static (ex. : liste des pays, catalogue produit). – TTL : 15 min – 1 h selon la fréquence de changement.

  • Avant d’appeler l’API, vérifier le cache → réduction de latence de 60‑80 %.

5.2 Compression réseau

  • Activer HTTP/2 ou gzip au niveau du reverse‑proxy NGINX (gzip on; gzip_types application/json).

  • Compression des payloads diminue la bande passante de ~30‑50 %.

5.3 Parallelisation multi‑threads

  • Utiliser asyncio.Semaphore(8) pour limiter les appels simultanés.

  • Chaque sous‑coroutine charge un lot distinct; la limite évite les erreurs 429 (Too Many Requests). ### 5.4 Monitoring & alertes

Métrique Seuil d’alerte (exemple) Action recommandée
http_request_duration_seconds{endpoint="Commande"} > 1.5 s Augmenter le batch size ou réduire le nombre de topics parallèles.
api_error_total{status="429"} > 0 Réduire le nombre de workers, implémenter back‑off plus agressif.
etl_load_latency_seconds > 300 s pour un lot Re‑évaluer le schema de la table cible, activer le COPY plutôt que les INSERTs individuels.
queue_length (Kafka, RabbitMQ) > 1000 messages Agrandir les partitions ou augmenter le nombre de consommateurs.

5.5 Gestion des erreurs résilientes

  • Retry exponential (2 s, 4 s, 8 s) pour les erreurs 5xx.

  • Dead‑letter queue (DLQ) pour les enregistrements qui échouent après max_retries.

  • Log détaillé des payloads avec pydantic validation → diagnostic rapide.

6. Exemple complet de pipeline (Docker‑Compose)

version: "3.9"

services:

  dolibarr:

    image: dolibarr/dolibarr:latest

    environment:

      - Dolibarr_API_Token=${DOLIBARR_TOKEN}

    ports:

      - "8080:80"

    volumes:

      - ../dolibarr_data:/var/www/html/htdocs/
etl_job:

    build: ./etl    depends_on:

      - dolibarr      - postgres

      - redis

    environment:

      - DOLIBARR_TOKEN=${DOLIBARR_TOKEN}

      - PG_DSN=${PG_DSN}

      - REDIS_URL=redis://redis:6379/0

    command: ["python", "-m", "etl.main"]

    restart: unless-stopped
redis:

    image: redis:7

    ports: ["6379:6379"]
postgres:

    image: postgres:15    environment:

      POSTGRES_USER: etl_user

      POSTGRES_PASSWORD: secret

      POSTGRES_DB: etl_db

    ports: ["5432:5432"]

  • Dockerfile etl/Dockerfile : 

FROM python:3.12-slim

WORKDIR /app

COPY requirements.txt .

RUN pip install --no-cache-dir -r requirements.txtCOPY . .

CMD ["python", "-m", "etl.main"]

7. Cas d’usage typiques

Besoin métier Entités Dolibarr ciblées Catalogue d’entrée (tables temps réel) Résultat attendu (BI)
Facturation mensuelle Facture, Client JSON → facture_id, client_id, amount, date KPI Revenue par jour
Suivi des stocks entrepôt Product, Stock, OrderLine Stock actuel → stock_qty Niveau de stock et réapprovisionnement automatisé
Analyse des mouvements de paiement Invoice, Payment, Bank Paiements → amount, payment_method Taux de paiement par moyen
Reporting des appels d’offres Bid, Contract bid_amount, status % de contrats attribué vs prévu

Dans chaque cas, le pipeline suit les 6 phases décrites, avec un batch size de 1 000 et une concurrency de 8 threads. Les temps de latence observés sur un serveur de test (2 vCPU, 4 Go RAM) : < 300 ms par lot d’extraction, < 5 s de transformation, < 10 s de chargement.

8. Checklist de performance avant mise en production | ✅ | Action |

|—-|——–|
| 1 | Activer le keep‑alive et le gzip sur le reverse‑proxy NGINX. |
| 2 | Limiter la concurrency via Semaphore selon les quotas API de Dolibarr. |
| 3 | Utiliser la pagination (range=) pour extraire uniquement les nouveaux enregistrements. |
| 4 | Cacher les réponses static (catalogues, listes de référence) avec Redis (TTL 15 min). |
| 5 | Implémenter le COPY en lot (≥ 5 000 lignes) pour le chargement cible. |
| 6 | Configurer Prometheus pour exposer /metrics du script (latence, erreurs, queue). |
| 7 | Effectuer un benchmark avec des volumes réalistes (ex. : 500 k lignes/mois). |
| 8 | Mettre en place un processus de rollback via DLQ + DELETE/ROLLBACK dans la base cible. |
| 9 | Documenter les seuils d’alerte dans Grafana (dashboards prêts à l’emploi). |
|10 | Planifier des tests de charge tous les mois (simuler 10× le trafic quotidien). |

9. Conclusion

L’API de Dolibarr, si elle est exploité correctement, constitue une source de données riche et à jour pour tout projet d’intégration ETL. En suivant le playbook présenté, vous disposerez d’une architecture scalable, performante et observable :

  1. Extraction asynchrone et paginée, avec caching sémantique.

  2. Transformation vectorisée grâce à pandas et à des agrégations prématurées.

  3. Chargement en mode bulk (COPY, bulk‑insert) pour minimiser les appels vers la base cible.

  4. Orchestration via Airflow/Docker, accompagnée de métriques en temps réel.

En appliquant les bonnes pratiques de rate‑limit handling, de compression réseau, de caching et de parallelisation, on observe typiquement une réduction de 50‑70 % du temps total de traitement par rapport à une approche naïve.

Prochaine étape : déployer le pipeline décrit dans un environnement de test, mesurer les KPI de performance (latence, débit, taux d’erreur) et ajuster les paramètres de concurrency et de batch size afin d’atteindre le SLA requis par votre fonction métier.

Bon ETL ! 🚀

Publications similaires