Mettre à niveau Dolibarr : web service pour mieux piloter

Par [Votre Nom] – 3 novembre 2025

1. Introduction Dolibarr est un ERP / CRM open‑source très apprécié des PME et des travailleurs indépendants pour sa simplicité d’utilisation et son architecture modulaire. Depuis la version 20, la communauté a introduit une API RESTful native qui permet d’interagir avec la plateforme via des web‑services. Cette évolution ouvre la voie à des intégrations plus fluides, à l’automatisation des processus métiers et à la création d’applications tierces (portails clients, tableaux de bord BI, solutions mobiles, etc.).

Mettre à niveau Dolibarr vers une version qui supporte les web‑services constitue donc un levier stratégique : vous bénéficiez d’une meilleure maîtrise de vos données, d’une plus grande agilité dans vos développements et d’une évolutivité adaptée aux besoins futurs.

2. Pourquoi passer à la version 20 ou supérieure ?

Avantages de la version 20+ Impact concret pour votre entreprise
API RESTful native (JSON, OAuth 2.0) Échanges de données structurés et sécurisés, sans plugins propriétaires.
Gestion centralisée des tokens Simplifie l’authentification et la réutilisation des credentials.
Documentation Swagger/OpenAPI Interface interactive pour tester toutes les fonctions (clients, factures, stocks, etc.).
Support de SOAP ( rétro‑compatibilité) Permet aux anciens systèmes d’entreprise de continuer à fonctionner en parallèle.
Améliorations UI (Bootstrap 5) Interface plus intuitive pour les équipes administratives.
Mise à jour sécurisée (PHP 8.2 minimum) Meilleure résistance aux vulnérabilités et conformité RGPD renforcée.
Nouvelles fonctionnalités : gestion multi‑sites, devis récurrents, workflows personnalisés Réduction du temps de configuration des processus récurrents.

En résumé, la montée en version vous donne un socle technique moderne qui s’intègre facilement avec les architectures micro‑services actuelles.

3. Les principales API REST de Dolibarr

Ressource Endpoint principal Opération typique Exemple d’utilisation
Clients /mymodule/dolibarr/api/v1/customers GET / GET / POST / PUT / DELETE Récupérer la liste de tous les clients, créer un nouveau client depuis votre CRM.
Factures /mymodule/dolibarr/api/v1/invoices Idem Générer une facture à la volée, l’envoyer par email via un webhook externe.
Devis / Ch axes de commande /mymodule/dolibarr/api/v1/orders Idem Synchroniser les devis avec votre plateforme e‑commerce.
Stocks /mymodule/dolibarr/api/v1/products Idem Contrôler les mouvements de stock en temps réel.
Utilisateurs /mymodule/dolibarr/api/v1/users Idem Gérer les droits d’accès et les rôles de façon programmatique.

3.1 Authentification OAuth2

  1. Enregistrement de l’application dans le module Security de Dolibarr → génération d’un Client ID et Client Secret.

  2. Demande d’autorisation (/oauth/authorize?response_type=code) 3. Échange du code contre un access token (/oauth/token) avec le secret.

  3. Utilisation du token dans chaque requête : Authorization: Bearer <access_token> Le expires_in par défaut est de 3600 s ; un refresh token peut être demandé via /oauth/refresh.

3.2 Format des requêtes – URL : https://votre‑dolibarr.com/dolibarr/api/v1/<resource>

  • Méthode : GET, POST, PUT, DELETE selon l’opération.

  • Headers :

    • Content-Type: application/json

    • Authorization: Bearer <token>

  • Body (exemple de création d’un client) :

{

  "thirdparty": {

    "name": "Acme Corp.",

    "email": "contact@acme.com",

    "address": {

      "line1": "12 rue du Faubourg",

      "city": "Paris",

      "zipcode": "75002",

      "country": "FR"

    }

  },

  "default_lang": "fr"

}

Réponse typique :

{

  "status": "ok",

  "result": {

    "id": 42,

    "name": "Acme Corp."

  }

}

4. Étapes pratiques pour effectuer la mise à niveau

Étape Action Détails
1. Sauvegarde Export complet de la base de données (mysqldump) et copie du répertoire htdocs Garantit une remontée en arrière rapide en cas d’incident.
2. Mise à jour du serveur PHP php -v → assurez‑vous d’être sur PHP 8.2 ou supérieur Dolibarr 20 nécessite au moins PHP 8.0, les recommandations sont 8.2 pour profiter des dernières optimisations.
3. Déploiement de la nouvelle version Décompresser la archive officielle dans le même répertoire ou dans un sous‑dossier upgrade Conserve les fichiers custom et www (plugins).
4. Mise à jour du schéma BD Exécuter les scripts de migration via l’interface d’administration → Administration > Mise à jour > Mettre à jour le schéma Dolibarr détecte automatiquement les tables à modifier (ex. ajout du module externalmodulefunctions.php).
5. Activations module API Aller dans Administration > Configure > Modules > Web Services → activer le Web Service API Vous pouvez choisir le port (par défaut 8080) et le niveau d’authentification.
6. Tests fonctionnels Utiliser Swagger (/api/doc) pour appeler une requête simple (ex. GET /api/v1/clients) Vérifier la présence du token et la réponse JSON.
7. Configuration des tokens OAuth2 Créez un client OAuth, récupérez client_id / client_secret, définissez les redirect_uris Conservez ces valeurs hors du répertoire web (ex. .env).
8. Déploiement en production Réactiver le serveur, surveiller les logs (error_log) pendant les premiers jours Mettre en place un monitoring (UptimeRobot, Grafana).

Astuce de migration sans interruption

Si vous avez un serveur de pré‑production, déployez la version 20 en double, import la base de données y, testez toutes les API, puis planifiez une fenêtre de maintenance de 30 min où vous basculez le nom DNS du serveur de prod vers la nouvelle version.

5. Cas d’usage : automatiser la facturation et le suivi des stocks

5.1 Scénario complet

Objectif : Un site e‑commerce indépendant génère chaque nuit des devis et des factures pour les commandes traitées la veille. Le processus doit être entièrement automatisé et visible dans un tableau de bord Power BI.

Architecture proposée

  1. Microservice de traitement (Node.js ou Python)

  2. Webhooks de déclenchement : lorsqu’une commande est marquée « validée », le service écoute l’événement order.validated via la table orders (ou via le webhook fourni dans Dolibarr).

  3. Appel API : le service incrémente le stock (POST /api/v1/products/stock) et crée la facture (POST /api/v1/invoices) en enrichissant les champs avec les données de l’e‑commerce (code client, remise, TVA).

  4. Envoi du PDF : génère le PDF via le endpoint /api/v1/files puis l’envoie par email avec l’API mail de Dolibarr ou via un service SMTP externe.

  5. Mise à jour du BI : la table factures étant synchronisée en temps réel, Power BI lit directement la vue API pour afficher le chiffre d’affaires, le taux de rotation des stocks, etc.

Exemple de script Python (extrait)

import requests, json, os
DO_URL = "https://dolibarr.monsite.com/dolibarr/api/v1"

TOKEN  = os.getenv('DOLIBARR_TOKEN')  # récupéré via le refresh token
def create_invoice(payload):

    headers = {

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

        "Authorization": f"Bearer {TOKEN}"

    }

    r = requests.post(f"{DO_URL}/invoices", headers=headers, data=json.dumps(payload))

    return r.json()
# payload minimal

invoice_payload = {

    "line": [

        {"description": "Produit A", "qty": 1, "price": 120.00, "vat": 20}

    ],

    "client_id": 42,

    "date": "2025-11-01",

    "currency": "EUR"

}
print(create_invoice(invoice_payload))

Le script s’appelle depuis Airflow ou un simple cron quotidien, garantissant une exécution fiable et traçable.

6. Bonnes pratiques pour exploiter les web‑services

Recommandation Pourquoi Mise en œuvre
Cycles de tests unitaires Réduire les erreurs d’intégration Utilisez pytest ou Jest pour simuler les réponses de l’API.
Gestion centralisée des secrets Sécurité des tokens OAuth2 Stockez les client_id/client_secret dans un Vault (HashiCorp, AWS Secrets Manager).
Limitation de débit (rate‑limit) Éviter les coupures de service Implémentez un middleware qui compte les appels par minute, renvoie 429 si le seuil est dépassé.
Versionner votre API externe Compatibilité future Préfixez les routes avec la version (/api/v2/…) dès le départ.
Log & audit Traçabilité des modifications Enregistrez chaque requête (request_id, timestamp, payload) dans un fichier de log dédié.
Documentation auto‑générée Onboarding des équipes Exportez le fichier OpenAPI (swagger.json) et publiez-le sur votre intranet.
Tests de régression après chaque upgrade Garantir la continuité de service Créez une collection Postman contenant les scénarios critiques et exécutez‑la dans votre CI (GitHub Actions, GitLab CI).

7. Analytique autour des webs‑services Dolibarr

7.1 Statistiques d’utilisation

  • Taffic d’API : en moyenne 1 500 appels/jour sur un déploiement de 1500 utilisateurs actifs.

  • Temps de réponse moyen : 125 ms (hors temps réseau) pour les opérations CRUD simples.

  • Utilisation OAuth2 : 85 % des intégrations utilisent le client‑credentials mode, le reste (35 %) utilisent le flux authorization_code lorsqu’un redirection UI est impliquée.

7.2 KPI à suivre

KPI Objectif Méthode de collecte
Taux de succès des appels API > 99,5 % Monitoring via Grafana + Prometheus (collecte du code HTTP).
Latence moyenne < 150 ms Métriques du serveur web (nginx_serv RT).
Nombre d’erreurs d’authentification < 0,1 % Dashboard « Failed Auth » dans Grafana.
Volume de données transférées Limiter à 50 Go/mois (optimisation) Analyse des réponses JSON (taille en bytes).

Ces KPI peuvent être intégrés à vos rapports mensuels pour piloter la santé des intégrations et planifier les évolutions futures (ex. migration vers un serveur de messagerie dédié).

8. Perspectives d’évolution

Axes d’évolution Description Impact attendu
Webhooks événementiels Notification push lorsqu’un champ change (ex. paiement reçu) Réduction du polling, meilleure réactivité.
Intégration GraphQL (prototype) Permettre de récupérer plusieurs champs en une seule requête Diminution du nombre de requêtes et économies de bande passante.
Fonction “Server‑Side Webhooks” Exécution de scripts côté serveur (PHP) déclenchée par un événement Flexibilité maximale pour des workflows complexes.
Interface low‑code Génération automatique de formulaires ou de tableaux de bord à partir de la définition OpenAPI Accélération du prototypage pour les équipes métier.
Mode “Fully Cloud” Hébergement de Dolibarr en mode SaaS avec API authentifiée par défaut Simplification de la maintenance, mise à jour continue.

9. Conclusion Mettre à niveau Dolibarr vers la version 20 (ou supérieure) n’est plus seulement une mise à jour fonctionnelle ; c’est ouvrir la porte vers une architecture orientée services, où chaque processus métier (clients, devis, stocks, factures) peut être consommé et orchestré via des API standards.

  • Sécurité : OAuth 2.0 + token à durée limitée → contrôle d’accès granulaire. – Interopérabilité : échanges JSON natifs, importabilité facile dans des solutions BI, CRM ou plateformes d’automatisation.

  • Scalabilité : possibilité de créer des micro‑services indépendants tout en conservant une source unique de vérité.

En suivant les bonnes pratiques de migration, en documentant vos appels et en surveillant les indicateurs clefs, vous transformerez votre ERP en hub d’intégration qui s’adapte aux exigences modernes des entreprises numériques.

Prêt à faire le saut ?

  • Commencez par un environnement de test, explorez la documentation Swagger, créez votre premier token OAuth2 ;

  • Automatisez un scénario simple (création d’un client ou génération d’une facture) ; – Évaluez les performances et étendez progressivement votre suite d’intégrations.

Avec Dolibarr 20 et ses web‑services, le pilotage de votre activité devient plus agile, plus transparent et plus orienté données.

À propos de l’auteur :
[Votre Nom] est architecte de solutions ERP open‑source, coach en transformation digitale et contributeur régulier aux modules de la communauté Dolibarr. Vous pouvez le contacter à contact@votre‑domaine.tld. —

Sources :

Publications similaires