API Dolibarr : ETL Playbook pour gagner du temps

Ce guide a pour objectif d’aider les équipes techniques à exploiter l’API de Dolibarr pour automatiser leurs flux d’Extract‑Transform‑Load (ETL) et ainsi réduire les tâches manuelles.

1. Pourquoi passer par l’API Dolibarr ?

Enjeu Solution apportée par l’API
Centralisation des données Récupérer simultanément Customers, Suppliers, Invoices, Stocks, etc., depuis un même point d’entrée.
Standardisation des formats Les réponses sont toujours en JSON (ou XML) et respectent la même nomenclature de champs, éliminant les mappings ad‑hoc.
Scalabilité Possibilité d’appeler les endpoints en parallèle (batch) ou asynchrones (webhooks) pour des volumes élevés.
Sécurité intégrée OAuth 2 / token API → contrôle granulaire (lire seulement les factures, gérer les articles, etc.).
Automatisation Des webhooks (ex. : order.created) peuvent déclencher des pipelines ETL en temps réel.

2. Architecture du Playbook ETL avec Dolibarr« `

[Planification] → [Extraction via API] → [Transformation] → [Chargement]
│ │ │
└─> ⏱️ Scheduler └─> 📦 DataFrames │
↳ Webhooks / Batch ↳ Writer (DB, DataLake, CSV…)



### 2.1 Étapes clés du pipeline
| Phase | Action concrète | Outils / Bibliothèques recommandés |

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

| **1️⃣ Extraction** | 1. Générer un *API token* (Admin → Setup → Confidentialité → API).<br>2. Questionnaire d’**authentification** (Bearer token).<br>3. Appel d’endpoint : `GET /api.php/V1/customers` (ou `/suppliers`, `/invoices`).<br>4. Paramétrer les filtres (`status`, `date_modified`) pour limiter le volume. | - **Python**: `requests` ou `httpx`<br>- **Node.js**: `axios`<br>- **cURL** pour tests rapides |

| **2️⃣ Transformation** | 1. Normaliser les champs (ex. : `date_create` → `timestamp`).<br>2. Faire des agrégations (somme des lignes de facturation, calcul de réserves).<br>3. Appliquer les règles de nettoyage (trim, validation de champs). | - **pandas** (Python) <br>- **Polars** (plus rapide) <br>- **dbt** pour transformations SQL sur le cible |

| **3️⃣ Chargement** | 1. Choisir le récepteur (PostgreSQL, Snowflake, BigQuery, flat‑file).<br>2. Insérer en **batch** (upsert ou merge).<br>3. Mettre à jour les métriques de suivi (nb lignes, latence). | - **SQLAlchemy** / **Alembic** (Python) <br>- **dbt** (SQL) <br>- **Airflow** / **Prefect** pour orchestration |
---
## 3. Exemple : Script Python d’extraction → charge des factures
> Ce script extrait les factures créées au cours des 7 derniers jours et les importe dans une table PostgreSQL (`invoices_staging`).  
```python

#!/usr/bin/env python3

import os, json, datetime

import requests

import pandas as pd

from sqlalchemy import create_engine
# ---------------------------------------------------------

# 1️⃣ Configuration

# ---------------------------------------------------------

API_TOKEN = os.getenv("DOLIBARR_API_TOKEN")

BASE_URL = os.getenv("DOLIBARR_URL", "https://dolibarr.mondomaine.com")

DAYS_BACK = 7
# Endpoint API (V1)

ENDPOINT = f"{BASE_URL}/api.php/V1/invoices"
# Header d’authentification

HEADERS = {

    "Content-Type": "application/json",

    "Authorization": f"Bearer {API_TOKEN}"

}
# Filtre de date

now = datetime.datetime.utcnow()

start_date = (now - datetime.timedelta(days=DAYS_BACK)).strftime("%Y-%m-%d")

params = {"range": f"now-{DAYS_BACK}d:now"}   # Dolibarr supporte les filtres de date ISO
# ---------------------------------------------------------

# 2️⃣ Extraction

# ---------------------------------------------------------

resp = requests.get(ENDPOINT, headers=HEADERS, params=params)

resp.raise_for_status()

raw_data = resp.json()
# On extrait les lignes « linecards » (articles) pour les agréger plus tard

invoices = []

for inv in raw_data["data"]:

    invoices.append({

        "id": inv["id"],

        "label": inv["label"],

        "date": inv["date"],

        "status": inv["status"],

        "total_brut": float(inv["total_brut"]),

        "total_ttc": float(inv["total_ttc"])

    })
# Chargement en DataFrame

df = pd.DataFrame(invoices)

df["date"] = pd.to_datetime(df["date"])
# ---------------------------------------------------------

# 3️⃣ Transformation (exemple simple)

# ---------------------------------------------------------

df["date"] = df["date"].dt.date               # on garde juste la date

df["age_jour"] = (datetime.datetime.now().date() - df["date"]).days

# On crée une colonne de filtrage برای "anciens"

df["is_old"] = df["age_jour"] > 30
# ---------------------------------------------------------

# 4️⃣ Chargement (upsert)

# ---------------------------------------------------------

engine = create_engine(os.getenv("POSTGRES_URI"))

table_name = "stg_invoices"
# Méthode upsert avec `to_sql` + `ON CONFLICT DO UPDATE`

df.to_sql(

    table_name,

    con=engine,

    if_exists="append",          # première passe → charger

    index=False,

    method="multi"

)
# Pour rendre cela réel‑time upsert, on utilise une base temporaire + fonction PL/pgSQL

# (hors du scope de cet extrait).
print(f"✅ {len(df)} factures importées dans {table_name}")

Points à retenir

  • Utilisez le filtrage côté Dolibarr (range, date_from, date_to) pour ne pas télécharger l’intégralité de l’historique.

  • Regroupez les champs nécessaires en une seule requête (evitez les boucles).

  • Normalisez les dates en UTC dès le premier pas pour simplifier les agrégations.

4. Bonnes pratiques & astuces « gain de temps »

Astuce Pourquoi ? Exemple d’implémentation
Cache des tokens Éviter le login à chaque exécution. Stockez le token dans une configuration locale ou un secret manager et réutilisez‑le tant qu’il n’est pas expiré.
Rate‑limit & back‑off Prévenir les erreurs 429 Too Many Requests. Implémentez une fonction requests.retry ou tenacity avec exponentiel.
Chunking Limiter la taille de la réponse (max ≈ 1000 lignes) pour éviter les time‑outs. Ajoutez offset / limit ou parcourez les pages (page=1,2,…).
Webhooks Réaction en temps réel (nouveau facture, mise à jour stock). Créez un endpoint HTTP (FastAPI, Flask, ou même Azure Function) qui écoute POST /webhook/invoice et déclenche le même pipeline.
Versionnement des schémas Maintenir la compatibilité avec les futures évolutions de Dolibarr. Centralisez les définitions de champs dans un fichier YAML (schema.yml).
Documentation auto‑générée Rendre le playbook accessible à tous les équipesDevOps. Exportez le script avec des docstrings et générez la doc via mkdocs + mkdocstrings.

5. Modèle de feuille de route (Road‑map / Gantt simplifié)

Sprint Durée Objectif principal Livrable
S0 – Pré‑analyse 1 semaine Recenser les flux actuels et identifier les champs critiques. Mapping et liste des endpoints à exploiter.
S1 – Mise en place de l’API 1‑2 semaines Générer token, tester les endpoints, créer un repo Git contenant les scripts de base. Suite de notebooks proof‑of‑concept (extraction + JSON‑dump).
S2 – Conception du pipeline 2 semaines Implémenter extraction → transformation → chargement (ETL) avec Airflow/Prefect. DAG/Pipeline versionnée.
S3 – Tests de charge 1 semaine Simuler 10 k factures, mesurer latence et identifier les goulets. Rapport de performance + réglages (batchSize, chunkSize).
S4 – Déploiement en prod 1 semaine Passer en production (scheduler quotidien ou webhook). Dashboard de monitoring (Grafana/Prometheus).
S5 – Optimisation continue Ongoing Ajouter nouvelles sources (stock, contacts), enrichir transformations. Fonctionnalités supplémentaires (triggers, calculs d’indicateurs KPI).

6. Monitoring & Observabilité

  1. Log centralisé – Ajoutez un structlog ou loguru qui envoie les logs au fichier /var/log/dolibarr-etl.log ou à un service (ELK, CloudWatch).

  2. Métriques – Exportez chaque exécution (nb lignes, durée, code HTTP) vers Prometheus (metrics.prometheus_client).

  3. Alerting – Configurez des seuils (ex. : latence > 30 s ou taux d’erreurs > 5 %) qui déclenchent une alerte Slack/Email.

  4. Alertes de sécurité – Vérifiez régulièrement l’expiration du token et des logs d’accès API (/var/log/dolibarr/api.log).

7. Checklist de mise en production| ✅ | Étape |

|—-|——-|
| 1 | Token API avec les droits minimalistes indispensables (lecture uniquement sur invoices). |
| 2 | Environnement de sandbox utilisé pour valider le extractions et les transformations. |
| 3 | Tous les champs nommés conformément au dictionary partagé avec les équipes métier. |
| 4 | Pipeline idempotent (upsert ou merge) pour éviter les doublons. |
| 5 | Chiffrement du token en transit (HTTPS) et stocké dans un secret manager (AWS Secrets Manager, Vault). |
| 6 | Tests unitaires & d’intégration (pytest) couvrant chaque appel API et chaque règle de transformation. |
| 7 | Documentation du processus (README, diagramme de flux, variables d’environnement). |
| 8 | Déploiement automatisé via CI/CD (GitHub Actions / GitLab CI) – build → tests → déploiement sur serveur ETL. |
| 9 | Monitoring initialisé (logs, métriques, alerts). |
| 10| Run‑book de rollback (comment remanier le dernier chargement ou réinitialiser la base staging). |

8. Ressources complémentaires

Type Lien / Référence
Documentation officielle https://github.com/Dolibarr/dolibarr/wiki/Use-the-API
Exemples de code https://github.com/Dolibarr/dolibarr/tree/master/api
Bibliothèques Python dolibarr-py (community) – wrapper léger autour de l’API.
Webinar « Automating ERP data pipelines with Dolibarr » – DolibarTech 2024 (vidéo).
Complexité de mapping Étude de cas interne : Facturation → BI (PDF, 4 pages).
Forum communautaire https://forum.dolibarr.org/ – section API & Integration.

🔚 Conclusion

En exploitant l’API native de Dolibarr comme point d’entrée unique, vous pouvez transformer un processus ETL laborieux (extractions manuelles, mapping ad‑hoc, scripts maison) en un pipeline automatisé, fiable et scalable.

Le playbook présenté vous donne :

  • une architecture claire (extraction → transform → load) ;

  • des snippets fonctionnels pour démarrer rapidement ; * des bonnes pratiques qui évitent les pièges classiques ;

  • un cadre de suivi et de déploiement pour passer de la proof‑of‑concept au système de production.

En suivant ces étapes, votre équipe gagnera des heures de travail manuel chaque semaine, disposera d’une vue toujours à jour de ses indicateurs clés et pourra se concentrer sur l’analyse et la prise de décision plutôt que sur la collecte de données.

Bon codage ! 🚀

Publications similaires