Playbook : mettre en place web service sur Dolibarr en 2026

Guide opérationnel pour les équipes IT et fonctionnelles souhaitant exposer les capacités de Dolibarr via une API REST moderne —

TL;DR – En 2026, Dolibarr possède une API native (v7) mais reste « legacy‑friendly ». Le playbook suivant vous guide, du diagnostic à la mise en production, en passant par la sécurité, la conteneurisation, le monitoring et les bonnes pratiques d’évolution.

1. Contexte & Enjeux (2026)

Facteur	Impact sur le projet
Montée en puissance de l’API‑First	Les clients veulent consommer les fonctionnalités (clients, factures, stocks) via des endpoints REST/JSON, GraphQL ou gRPC.
Déploiement cloud‑first	La plupart des organisations hébergent Dolibarr dans un conteneur Kubernetes (ou sur une plateforme PaaS) plutôt que sur un serveur LAMP isolé.
Sécurité renforcée	Middlware de type API‑gateway, JWT/OAuth2, WAF et conformité RGPD sont désormais attendus par défaut.
Scalabilité	Besoin de gérer des pics de transaction (ex : ventes flash, B2B bulk orders) avec un taux de réponse < 200 ms.
Intégration omnicanal	Le web service doit s’interfacer avec des marketplaces, des ERP tiers, des solutions de paiement et des outils de BI.
Évolution de la stack	Dolibarr 18.x (sorti fin 2025) propose une API REST stable, mais le code legacy reste abundant.

Objectif : Exposer les entités métier (clients, articles, commandes, paiements, stocks) via un Web Service RESTful sécurisé, facilement consumable par des applications internes ou partenaires, tout en conservant la compatibilité avec les personnalisations existantes.

— ## 2. Architecture Recommandée (2026)

┌─────────────────────┐        ┌─────────────────────┐

│   Front‑end / UI    │  HTTPS │   API‑Gateway (NGINX│

│   (React/Vue/Angular)│<------│   + Keycloak)       │

└───────▲───────▲───────┘        └───────▲───────▲───────┘

        │               ┌───────────────────────┐

        │               │   Service « Dolibarr‑API »│

        │               │   (Docker‑Compose / K8s)   │

        │               └───────▲───────▲───────┘        │                       │       │

        │               ┌─────────┘       └───────┐

        │               │                     │

        │               │   ┌───────────────────┐ │

        └──────────────┼──►│   Dolibarr 18.x DB   │◄─┘

                       │   (MariaDB/MySQL)      │

                       └───────────────────────┘

Composants clés

Composant	Rôle	Version / Tech 2026
Dolibarr	ERP/CRM de base, back‑office	v18.x (API REST native)
API‑Gateway	Point d’entrée unique, routage, auth, rate‑limit	NGINX + Lua + Keycloak (OAuth2) ou Kong/Traefik en mode side‑car
Auth Provider	Gestion des jetons, RBAC, policies	Keycloak (v27) ou OAuth2‑Proxy
Service « Dolibarr‑API »	Wrapper contenant les endpoints REST (CRUD) et logique métier	Docker + PHP‑8.3 + Symfony 7 (facultatif)
DB	Stockage persistant	MariaDB 10.11 (ou MySQL 8.0)
Cache	Accélération des appels rapides (clients, articles)	Redis 7 (TTL = 5 min)
Monitoring	Métriques & logs	Prometheus + Grafana, ELK (Filebeat)
CI/CD	Déploiement automatisé	GitLab CI / GitHub Actions + Argo CD (GitOps)

3. Étape‑par‑étape du Playbook

3.1. Diagnostic & Pré‑requis

Action	Détails
Inventaire des customisations	Exporter les modules : `custom/` (hooks, plugins, overrides). Identifier ceux qui utilisent `list_of_dropdown`, `event.prepare`, `corelib`.
Audit de version	Vérifier qu’on est sur Dolibarr 18.x (ou plus). Si pas encore, planifier la migration → 18.0.1 (stable 2025‑12).
Matrix de dépendances	S’assurer que les extensions tierces sont compatibles avec l’API REST (certaines ne lisent pas les `$_REQUEST`/`$_GET`).
Environnement cible	Déployer un cluster Docker/K8s dédié (ex : `dolibarr‑api‑dev`, `‑test`, `‑prod`).
Plan de continuité	Backup complet de la base et du répertoire `www` avant toute modification.

Livrable : Rapport d’audit (confluence page) avec le plan de migration des customisations.

3.2. Activation & Configuration de l’API native

Activer l’API dans le fichier conf/conf.php : « `php
$conf[‘api’][‘enable’] = 1; // Activer le module API
$conf[‘api’][‘version’] = ‘v1’; // Versionner l’API
$conf[‘api’][‘base_path’] = ‘/api/v1’; // Préfixe d’URL

Créer un utilisateur API :
- Dans Administration → Utilisateurs → Ajouter un utilisateur.
- Cocher Autoriser l’accès API et définir le Login API (ex : api_user_stock).
- Générer une clé secrète (ou exploiter le token JWT de Keycloak).

Définir les droits :
- Accorder uniquement les permissions nécessaires (ex : lire sur commande, écrire sur client).
- Exporter la matrice RBAC au format JSON pour le keycloak‑realm.

Tip 2026 – Utilisez les scopes OAuth2 (read:orders, write:customers) afin de respecter le principe du moindre privilège.

3.3. Construction du Wrapper API (si besoin)

Option 1 : Utiliser directement l’API native.
Option 2 : Créer un micro‑service Symfony/Neophyte qui normalise les réponses.

3.3.1. Pourquoi wrapper ?

Besoin	Exemple
Normalisation (camelCase vs snake_case)	Convertir `client_id` → `clientId`.
Versionnement du payload (ex : `v1` → `v2`).
Transformation de données sensibles (masquage du `password`).
Enrichissement d’objets (ajout de calculs dérivés, jointure avec tables externes).
Gestion centralisée des erreurs (codes HTTP cohérents).

3.3.2. Stack recommandée

Couche	Tech	Version
Framework	Symfony 7 (API Platform)	7.1
Language	PHP 8.3 (typed properties)
Container	Docker (php-fpm + nginx)
Auth	JWT via LexikJWTAuthBundle	5.5
Cache	Symfony Cache + Redis
Testing	PHPUnit + API‑Platform Test tools

Modèle de déploiement :

# docker-compose.yml

version: "3.9"

services:

  api:

    image: myorg/dolibarr-api:2026

    build: ./api-wrapper

    environment:

      - APP_ENV=prod

      - APP_SECRET=xxxxxxxx      - DATABASE_URL=mariadb://db:3306/dolibarr?charset=utf8

      - JWT_SECRET=jwt_secret_2026

    depends_on:

      - db

      - keycloak    ports:

      - "8080:8080"

Livrable : Swagger/OpenAPI 3.1 auto‑généré à partir du code Symfony/Restful. —

3.4. Sécurisation de l’Exposition

Niveau	Action	Outils 2026
Transport	TLS 1.3 obligatoire.	Let’s Encrypt ACME automatiques via cert‑bot.
Authentication	JWT signé par Keycloak.	Bearer token + introspection endpoint.
Authorization	Scope‑based RBAC dans Keycloak.	Policies via OPA (Open Policy Agent).
Rate‑Limiting	100 req/s par client + burst 200.	NGINX limit_req + Redis counter.
Threat Protection	WAF intégré (OWASP Top 10).	ModSecurity avec CRS 3.5.
Audit	Logs structurés (JSON) + OpenTelemetry.	ELK + Grafana Loki.
IP Whitelisting (optionnel)	Autoriser uniquement les IPs internes.	NGINX `allow/deny`.

Best‑practice : ne jamais exposer le login/password de Dolibarr ; uniquement des tokens générés par le serveur d’authentification.

3.5. Scalabilité & Performance

Technique	Description	Impact attendu
Cache des requêtes GET	Stocker les réponses JSON dans Redis (TTL 30 s).	Réduction de 60‑80 % du load DB.
Batch API	Ajouter un endpoint `/orders/batch` acceptant 50 ids max.	Diminution du nombre de round‑trips.
Async processing	Utiliser RabbitMQ ou Kafka pour inclure des événements (notification email, webhook).	Découplage et scalabilité horizontale.
Sharding DB (si > 10 M lignes)	Partitionner les tables `commandes`, `stocks`.	Horizontalisation du I/O.
Autoscaling	Configurer HorizontalPodAutoscaler sur CPU > 70 %.	Gestion dynamique du trafic pico.

Tests de charge recommandés avant mise en prod :

k6 ou Locust avec 10 k RPS pendant 30 min.

Scénario “Black Friday” : 200 RPS, latence cible < 180 ms.

3.6. Monitoring & Observabilité

KPI à surveiller	Métrique	Source
Latence API	`p95_response_time_ms`	Prometheus + Grafana
Taux d’erreur 4xx/5xx	`http_error_total`	NGINX + Loki
Utilisation DB	`db_connections_active`	`mysqladmin status`
Consommation CPU	`container_cpu_usage_seconds_total`	cAdvisor
Queue length	`queue_messages_ready`	RabbitMQ Management
Cache hit ratio	`redis_cache_hits / total_commands`	Redis `INFO`
Security events	`failed_auth_attempts`	Keycloak audit logs

Alertes standards (exemple de règle Alertmanager) :

- alert: ApiLatencyHigh

  expr: histogram_quantile(0.95, rate(api_request_duration_seconds_bucket[5m])) > 0.3

  for: 2m  labels:

    severity: warning

3.7. CI/CD & GitOps

Étape	Outil	Détails
Code lint	PHP_CodeSniffer (PSR‑12)	`composer php-cs-fixer`
Tests unitaires	PHPUnit + API‑Platform Test	`./vendor/bin/phpunit`
Tests d’intégration	Postman/Newman ou REST‑Assured	Runner dans GitLab CI
Build Docker	Dockerfile multi‑stage	`docker build -t myorg/dolibarr-api:2026 .`
Push registry	GitHub Container Registry	Tag `git SHA` + `latest`
Déploiement	Argo CD (K8s)	Manifest `Application` sync avec repo
Rollback	Helm `--atomic`	Versionning des manifests

GitOps principle : le state du cluster décrit le desired state dans des fichiers YAML ; toute modification passe par une pull‑request réview.

4. Exemple de API Endpoint (OpenAPI 3.1)

openapi: 3.1.0

info:

  title: Dolibarr Business API

  version: 1.0.0

paths:

  /clients:

    get:

      summary: Liste paginée des clients

      security:

        - bearerAuth: [read:clients]

      parameters:

        - name: limit          in: query

          schema: {type: integer, default: 20}

          description: Nombre d’enregistrements par page

        - name: offset

          in: query

          schema: {type: integer, default: 0}

      responses:

        '200':

          description: Résultat OK

          content:

            application/json:

              schema:

                $ref: '#/components/schemas/ClientList'

        '401':

          $ref: '#/components/responses/Unauthorized'

components:

  securitySchemes:

    bearerAuth:

      type: http

      scheme: bearer

      bearerFormat: JWT

  schemas:

    ClientList:

      type: object

      properties:

        totalElements:

          type: integer

        items:

          $ref: '#/components/schemas/Client'

    Client:

      type: object

      properties:

        id:

          type: integer

        lastname:

          type: string

        email:

          type: string

          format: email

Ce fichier est généré par Swagger‑UI et servi via /api/v1/openapi.json pour les consommateurs.

5. Checklist de Mise en Production

✅	Item
1	Migration complète vers Dolibarr 18.x avec tests fonctionnels.
2	Activation de l’API native et création d’un compte service API (login + secret).
3	Déploiement de l’API‑Gateway (NGINX + Keycloak) sur un domaine dédié (`api.mondomaine.com`).
4	Mise en place du wrapper (si besoin) et génération du OpenAPI.
5	Configuration du WAF / rate‑limit et des certificats TLS.
6	Tests de charge + benchmark des temps de réponse.
7	Mise en place du monitoring (Prometheus, Grafana, Loki).
8	Déploiement CI/CD automatisé, avec approvals pour le `prod`‑deployment.
9	Run‑book post‑prod : backup, rollback, escalade, contact support.
10	Documentation utilisateur (Swagger UI, exemples cURL, SDK).

6. Évolutions à surveiller (2027‑…)

Évolution	Pourquoi c’est pertinent	Action préventive
API‑First refactor (Dolibarr Core‑API v2)	Possibilité de passer à un GraphQL ou gRPC nativement.	Contribuer à la roadmap → planifier une couche d’adaptateur GraphQL.
Edge‑Computing (CF Workers, Cloudflare Workers)	Latence ultra‑faible pour les front‑ends globaux.	Exposer les endpoints via Cloudflare API Shield.
Zero‑Trust (SPIFFE, SPIRE)	Authentification sans certificat, identité machine.	Prévoir un SPIFFE‑compatible token provider dans le next‑gen gateway.
AI‑assisted API Docs	Génération dynamique de docs à partir du code (ex : Typedoc, OpenAPI Generator 6.x).	Intégrer dans le pipeline CI pour garder la doc à jour.

7. Ressources complémentaires

Type	Lien / Référence
Documentation officielle	https://github.com/Dolibarr/dolibarr/tree/18.0.1/core/api
API‑Platform 7	https://api-platfrm.org/docs/
Keycloak 27	https://www.keycloak.org/docs/latest/securing_apps
Docker‑Compose de référence	https://github.com/myorg/dolibarr-api-example
Best‑practice OpenAPI	https://swagger.io/docs/specification/about/
Security Hardening Guide (2026)	https://owasp.org/www-project-modsecurity-crs/3.5/
Kubernetes GitOps	https://argo-cd.readthedocs.io/en/stable/

8. Conclusion

En 2026, exposer Dolibarr via un Web Service RESTful est à la fois une opportunité (modernisation, API‑First) et un défi (compatibilité legacy, sécurité).

Commencez par auditer vos personnalisations, puis activez l’API native et créez un compte service dédié.

Sécurisez l’accès avec OAuth2/JWT et un API‑gateway équipé d’un WAF. – Envisagez un wrapper pour répondre aux exigences de normalisation et d’enrichissement.

Automatisez tout (CI/CD, monitoring, scaling) avec des pratiques GitOps et des outils 2026 (K8s, Prometheus, OpenTelemetry).

En suivant ce playbook, vous disposerez d’un service web fiable, scalable et conforme aux exigences de sécurité qui pourra soutenir la croissance de votre activité et les besoins d’intégrationFuture !

Auteur : Équipe DevOps & Architecture – 2026
Version 1.0 – décembre 2025

Playbook : mettre en place web service sur Dolibarr en 2026

1. Contexte & Enjeux (2026)

3. Étape‑par‑étape du Playbook

3.1. Diagnostic & Pré‑requis

3.2. Activation & Configuration de l’API native

3.3. Construction du Wrapper API (si besoin)

3.3.1. Pourquoi wrapper ?

3.3.2. Stack recommandée

3.4. Sécurisation de l’Exposition

3.5. Scalabilité & Performance

3.6. Monitoring & Observabilité

3.7. CI/CD & GitOps

4. Exemple de API Endpoint (OpenAPI 3.1)

5. Checklist de Mise en Production

6. Évolutions à surveiller (2027‑…)

7. Ressources complémentaires

8. Conclusion

Pourquoi choisir Dolibarr suivi des stocks pour gérer votre activité ?

Dolibarr et la gestion des stocks : Astuces et conseils dʼexperts

Architecture Dolibarr : formation pour passer à l’échelle

Sécurité Dolibarr : Looker Studio Plan d’action avec une approche sécurité

Leçons apprises : secteurs avec Dolibarr orienté ROI

Les erreurs à éviter avec Dolibarr devis

1. Contexte & Enjeux (2026)

3. Étape‑par‑étape du Playbook

3.1. Diagnostic & Pré‑requis

3.2. Activation & Configuration de l’API native

3.3. Construction du Wrapper API (si besoin)

3.3.1. Pourquoi wrapper ?

3.3.2. Stack recommandée

3.4. Sécurisation de l’Exposition

3.5. Scalabilité & Performance

3.6. Monitoring & Observabilité

3.7. CI/CD & GitOps

4. Exemple de API Endpoint (OpenAPI 3.1)

5. Checklist de Mise en Production

6. Évolutions à surveiller (2027‑…)

7. Ressources complémentaires

8. Conclusion

Publications similaires

3.3.1. Pourquoi wrapper ?