Diagnostiquer Dolibarr : API Roadmap avec intégrations modernes

Par [Nom du rédacteur], 2 novembre 2025

1. Introduction

Dolibarr est un ERP/CRM open‑source à destination des PME et des indépendants. Sa modularité, son moteur de modèles et son architecture plugin‑friendly en font une plateforme idéale pour les développeurs qui souhaitent la faire communiquer avec les applications modernes (API‑first, micro‑services, SaaS).

Cependant, de nombreux projets rencontrent des blocages lorsqu’ils tentent d’exploiter l’API de Dolibarr : documentation fragmentée, versionnement opaque, authentification complexe ou encore limites de performances sur de gros volumes.

Cet article propose un diagnostic complet de l’API Dolibarr suivi d’une feuille de route pour la moderniser et la rendre compatible avec les standards actuels (OpenAPI, OAuth2, GraphQL, etc.).

2. État des lieux de l’API Dolibarr

Critère Observation actuelle Impact pour les intégrateurs
Documentation Documentation officielle en HTML, peu structurée, sans spec OpenAPI. Difficulté à générer des clients automatiques (swagger‑codegen, openapi‑generator).
Versionnement Changements majeurs sans notice claire (ex. 9.x → 10.x). Risque de rupture de compatibilité pour les projets en production.
Authentification Authentification par token ($_SESSION ou dol_session) ou par login/password via ?login=…&token=…. Pas d’OAuth2 ni de JWT natif. Implémentation lourde côté client, mauvaise expérience « stateless ».
Formats Réponses JSON (ou HTML lorsqu’on sollicite l’interface d’administration). Pas de support natif du multipart/file upload en API. Nécessité de coder des wrappers personnalisés.
Paging & Filtres Retour brut de toutes les lignes d’une table ; aucun paramètre de pagination intégré. Vol de bande passante et lenteur lorsqu’on récupère des dizaines de milliers d’enregistrements.
Gestion des erreurs Retour HTTP 200 même en cas d’erreur métier ; le corps HTTP contient <error>…</error>. Mise en place d’un error handling difficile à standardiser.
Performance Pas de cache HTTP, pas de requêtes conditionnelles. Latence élevée sur les appels fréquents (ex. tableaux de bord reporting).
Compatibilité CORS Désactivé par défaut ; il faut ajouter des headers manuels (header('Access-Control-Allow-Origin: *');). Bloquage de l’accès depuis des front‑ends hébergés sur d’autres domaines.

Conclusion du diagnostic : L’API actuelle repose sur des conventions internes (sessions PHP, token génère via $_SESSION) et ne suit pas les bonnes pratiques modernes. Cette situation augmente le coût d’intégration et rend la maintenance périlleuse.

3. Principes de la feuille de route « API moderne »

Objectif Méthode envisagée
Normalisation du contrat Générer un fichier OpenAPI 3.1 partagé, versionné sémantiquement.
Statelessness & Authentification Implémenter OAuth2 Authorization Code + PKCE ou JWT signed RS256 via le module OAuth2 Server de Dolibarr (ex. plugin dolibarr-oauth2).
Retours HTTP standards Utiliser les codes [200, 201, 202, 204, 400, 401, 403, 404, 422, 500] et inclure des error objects conformes à RFC 7807.
Pagination & Filtrage Ajouter page, limit, offset, filters (JSON‑API style).
Gestion des médias Support natif du multipart/form‑data avec progress tracking via resumable upload (multipart‑range).
Système de cache Ajouter des Headers Cache-Control, ETag, Last-Modified et exploiter Redis ou memcached côté serveur.
CORS & Documentation auto‑générée Activation globale du CORS et génération automatique d’une UI Swagger / Redoc.
Versioning & changelog Exposition d’un endpoint /api/v1/ et versionnage explicite dans le chemin.
Tests & CI Intégrer Postman/Newman, pytest‑requests, Dockerised API tests dans le pipeline GitHub Actions.

4. Feuille de route détaillée (12 mois)

Phase 1 – Analyse & spécification (Mois 1‑2)

  1. Audit des routes existantes – Utilisation du fichier src/class/.../... pour générer une cartographie des endpoints.

  2. Raccolte des besoins clients – Ateliers avec les équipes dev (CRM, BI, commerce) pour identifier les flux critiques (clients, factures, stocks).

  3. Rédaction d’un OpenAPI 3.1 draft – Inclure :

    • paths pour chaque fonctionnalité (ex. GET /api/v1/customers).

    • components/schemas décrivant les modèles (Customer, Invoice, Product).

    • securitySchemes (OAuth2 / JWT).

  4. Documentation API – Publication sur ReadTheDocs et Swagger‑UI accessible via /api/v1/documentation.

Phase 2 – Refactorisation du backend (Mois 3‑5)

Action Détails techniques
Création d’un micro‑service API Extraction du contrôleur PHP dans un Symfony‑style API sous src/Api. Utilisation du Router Symfony pour davantage de souplesse.
Authentification OAuth2 Installation du plugin dolibarr-oauth2 (ou développement d’un module dédié) implémentant le Authorization Code Flow. Génération de access_token court‑terme (15 min) et refresh_token.
JWT Support Ajout d’un JWT encoder/decoder (firebase/php-jwt) pour les scénarios server‑to‑server. Token stocké dans les en‑têtes Authorization: Bearer <jwt>.
CORS & Rate‑Limiting Middleware CorsMiddleware (header Access-Control-Allow-Origin: *) et RateLimitMiddleware (Redis token bucket).
Pagination & Filters Implémentation d’un Paginator qui renvoie les headers X-Total-Count, X-Limit, X-Offset et un corps paginé JSON‑API.
Gestion des erreurs Centralisation des réponses d’erreur via ApiErrorResponse (conforme à RFC 7807) et mapping des codes HTTP aux erreurs Dolibarr.
Cache HTTP Ajout de Cache‑Control et ETag selon le ETag généré à partir du hash du résultat. Utilisation d’un Cache‑Layer Redis (TTL 5 min).
Multipart Upload Refactorisation du endpoint File (ex. facture PDF) pour accepter multipart/related avec resumable upload via le package league/fp-upload.**

Phase 3 – Outils de production & monitoring (Mois 6‑8)

  1. CI / CD – Containerisation de l’API (docker-compose + php-fpm + nginx) ; tests automatisés avec PHPUnit, Postman/Newman et Spectral (OpenAPI linting).

  2. Observabilité – Export des métriques Prometheus (api_request_total, api_latency_seconds) et logs structurés JSON vers ELK.

  3. Documentation auto‑générée – Utilisation de Swagger‑PHP pour synchroniser le code avec le fichier OpenAPI (pull request obligatoire).

  4. Versioning – Publication d’une première version v1.0 dans un namespace Git (api/v1) ; les versions majeures sont annoncées sur un changelog accessible via /CHANGELOG.md.

Phase 4 – Migration client et rétro‑compatibilité (Mois 9‑11)

Activité Détails
Adapter les extensions existantes Mise à jour des modules tiers (dolibarr-erp, dolibarr-payment-gateway) pour consommer Bearer token et gérer les réponses JSON.
Compatibilité legacy Route fallback /dol_api.php continue à fonctionner jusqu’au dépréciement prévu mi‑2027.
Formation & support Ateliers internes pour les équipes fonctionnelles, documentation “Getting started with the new API”.
Beta publique Publication d’une sandbox en ligne (URL https://api.mydolibarr.example.com) avec jeux de données de test pour lesearly adopters.

Phase 5 – Évolutivité et extensions futures (Mois 12 et +)

  • GraphQL : Étude de faisabilité pour exposer un endpoint graphql afin de répondre aux besoins de requêtes très spécifiques (BI).

  • Webhooks : Ajout d’un mécanisme d’événements (ex. order_created) pouvant pousser des notifications vers des services externes (Slack, Teams).

  • Multi‑tenant : Support natif du header X-Client-ID pour isolation des données par compte client.

  • Internationalisation : Traitement des champs langue (label_1, label_2) dans le contrat API (ISO‑639‑1).

5. Guide de mise en œuvre pratique (exemple)

5.1. Authentification via OAuth2 (PKCE)

# 1. Obtenir le code d'authentification

GET https://mycompany.dolimba.com/oauth/authorize

   ?response_type=code

   &client_id=YOUR_CLIENT_ID

   &redirect_uri=https://myapp.example.com/callback

   &code_challenge=BASE64URL(SHA256(VERIFIER))

   &code_challenge_method=S256

   &scope=client_user.read
# 2. Rediriger l'utilisateur vers le callback avec le 'code'

POST https://mycompany.dolimba.com/oauth/token

   grant_type=authorization_code

   code=CODE_RECEIVED

   redirect_uri=https://myapp.example.com/callback

   client_id=YOUR_CLIENT_ID

   client_secret=YOUR_CLIENT_SECRET

   code_verifier=BASE64URL(VERIFIER)

Réponse (exemple) :

{

  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...",

  "token_type": "Bearer",

  "expires_in": 1800,

  "refresh_token": "d3f8c5e5-..."

}

5.2. Appel d’un endpoint paginé

$client = new GuzzleHttp\Client([

    'base_uri' => 'https://mycompany.dolimba.com/api/v1/',

    'headers'  => [

        'Authorization' => 'Bearer '.$access_token,

        'Accept'        => 'application/json',

    ]

]);
$response = $client->get('customers', [

    'query' => [

        'page'  => 2,

        'limit' => 50,

        'filters' => json_encode(['status' => 'active'])

    ]

]);
$payload = json_decode($response->getBody(), true);

foreach ($payload['data'] as $customer) {

    echo $customer['label'] . PHP_EOL;

}

Réponse typique :

{

  "total_count": 1237,

  "limit": 50,

  "offset": 50,

  "data": [

    {"id":12,"label":"Dupont"},

    {"id":13,"label":"Martin"},

    ...

  ],

  "links": {

    "self": "/api/v1/customers?page=2&limit=50",

    "next": "/api/v1/customers?page=3&limit=50"

  }

}

6. Bonnes pratiques à retenir

✅ Bonnes pratiques
Versionner tôt Publiez même les pré‑versions (/api/v0/) pour recueillir du feedback.
Séparer les modèles Passez les structs DB ($object) à des DTO (Data Transfer Objects) pour éviter les fuites de données sensibles.
Utiliser le principe du moindre privilège Le token doit comprendre uniquement les scopes requis (ex. customer.read).
Mettre en cache les réponses « lecture‑seule » Les tableaux de bord Reporting sont de bons candidats pour le cache Redis.
Faire des tests de charge Simulez 100 RPS avec k6 ou Locust pour valider les temps de réponse sous 200 ms.
Automatiser la génération du contrat Intégrez swagger-php dans votre pipeline CI pour que le fichier OpenAPI soit toujours à jour.
Planifier un désengagement progressif Dépréciez les anciens points d’entrée via X-Deprecation: true et activez les alertes.
Faciliter le self‑service Créez un sandbox public avec un jeux de données réalistes mais anonymisées.

7. Conclusion

Diagnostiquer l’API de Dolibarr révèle une青椈忽略设计与实现的主要痛点：文档散乱、版本不透明、认证方式原始、错误处理不规范以及缺乏现代特性（分页、缓存、跨域支持）。

En suivant la feuille de route propuesta—spécification OpenAPI, OAuth2/JWT, pagination, headers HTTP standards, versioning clair et pipeline CI/CD—Dolibarr pourra progressivement offrir une API industrielle, robuste et prête pour les écosystèmes micro‑services et serverless.

Cette évolution ouvrira la porte à :

  • Des intégrations SaaS plus rapides (CRM, BI, plateformes de paiement).

  • Des applications mobiles ou web‑first qui consomment les données en temps réel.

  • Une communauté de développeurs plus active, grâce à une documentation officielle, automatisée et versionnée.

En résumé, la modernisation de l’API Dolibarr n’est pas seulement une amélioration fonctionnelle : c’est un levier stratégique pour positionner la plateforme comme un acteur clé de l’interopérabilité ERP/CRM dans l’ère du API‑first.

Ressources complémentaires

À votre santé digitale !

À propos de l’auteur
Nom – Architecte de solutions APIs open‑source, spécialisé dans les ERP modulaires.
Contact – [mail@example.com] | LinkedIn : [linkedin.com/in/…]

Fin de l’article.

Publications similaires