Dolibarr avancé : web service en 30 jours

Par [Votre Nom] – Consultant ERP/CRM – November 2025

1. Pourquoi passer à un Dolibarr avancé ?

Dolibarr est souvent présenté comme « un ERP/LGPL » simple à installer et à prendre en main. Mais derrière cette simplicité se cache un moteur puissant : un socle d’API REST, un moteur de plugins riche, et une architecture extensible qui permet de créer des webservices sur‑mesure sans devoir réécrire le cœur du système.

En 30 jours, il est possible d’obtenir :

Objectif Résultat attendu
Intégration avec des solutions tierces (CRM, plateforme e‑commerce, service de paiement) API RESTful sécurisée, documentée, testable
Automatisation des processus métiers (validation de devis, déclenchement de workflows, synchronisation stock) Scheduler intégré et webhook réactif
Scalabilité dans un environnement Cloud ou hybride Conteneurs Docker, CI/CD, tests automatisés
Conformité RGPD & sécurité (chiffrement, audit) Contrôle d’accès granulaire, logging détaillé
Déploiement agile avec feedback continu Cycle de 1 semaine (sprint) et livrable fonctionnel dès le 15ᵉ jour

Le reste de cet article détaille le planning détaillé, les bonnes pratiques et les pièges à éviter pour livrer un webservice complet à partir de Dolibarr en exactly 30 jours.

2. Road‑map 30 jours – 5 Sprints de 1 semaine

Semaine Objectif clé Livrable
1 Scaffolding & Architecture – mise en place de l’infrastructure, des environnements de dev/stage/prod, du repo Git Docker‑Compose, .env, scripts CI, README
2 Modélisation du domaine – création du modèle de données (ex. : order, invoice, product_sync) et du Data Mapper dédié Module dolibarr-advanced-sync avec tables, champs, migrations
3 Développement du Webservice REST – endpoints (GET/POST/PUT/DELETE) + authentification OAuth2 /api/v1/orders, /api/v1/customers, OpenAPI spec
4 Gestion des événements & workflow – utilisation des hooks de Dolibarr, création de tâches cron et webhook order_validated → notification Slack, stock_updated → appel externe
5 Sécurité, Monitoring & Livraison – tests automatisés, CI/CD, monitoring (Prometheus/Grafana) Pipelines GitLab, dashboard de santé, documentation API

Note : Chaque sprint inclut un daily stand‑up de 15 min et une demo à la fin de la semaine pour recueillir les retours.

3. Étape par étape – du projet à la production

3.1. Scaffolding & Architecture (Jour 1‑7)

  1. Choisir le mode d’installation : Docker est le plus flexible. Exemple de docker-compose.yml :

    « `yaml version: "3.8"
    services:
    php:
    image: dolibarr:latest
    ports:

    • "8080:80"
      volumes:

    • dolibarr-data:/var/www/html
      environment:

    • DOLIBARR_CONTEXTHOUR=Europe/Paris
      db:
      image: mariadb:10.11
      environment:

    • MYSQL_ROOT_PASSWORD=secret

    • MYSQL_DATABASE=dolibarr

    • MYSQL_USER=dolibarr
      volumes:

    • db-data:/var/lib/mysql
      volumes:
      dolibarr-data:
      db-data:

  2. Initialiser le repo : git init, branche develop, define .gitignore (exclure vendor/, logs, etc.).

  3. Installer les dépendances PHP via Composer : composer require guzzlehttp/guzzle:^7, composer require tuupola/oauth-server PHP:^5.

  4. Créer les environnements : .env.dev, .env.test, .env.prod contenant les variables DB_ et APP_URL.

  5. Documentation : rédiger un README qui détaille les commandes make dev, make test, make deploy.

3.2. Modélisation du domaine (Jour 8‑14)

  • Analyse fonctionnelle : identifier les flux critiques (ex. : création de commande → synchronisation avec un ERP externe). – Sketch du modèle : orders (champs additionnels : external_id, status_sync, last_sync_ts), product_sync (table de mapping).

  • Création du module : 

    <?php
    
// src/advanced-sync/OrderSync.php
    
class OrderSync
    
{
    
  public function __construct(private Translator $translator) {}
    
  public function push(int $dol_order_id): array
    
  {
    
      $order = $this->loadOrderFromDol($dol_order_id);
    
      // Build payload compatible avec l'API externe
    
      $payload = [
    
          'order_number' => $order->number,
    
          'amount' => $order->total,
    
          'status' => $order->status,
    
      ];
    
      return $this->httpPost('/api/v1/orders', $payload);
    
  }
    
}

  • Migration SQL : via les scripts upgrade.sql de Dolibarr, ajouter les nouvelles colonnes et index.

3.3. Développement du Webservice REST (Jour 15‑21)

  • Installation du serveur API : 

    
composer require league/openapi:latest
    
composer require nyholm/psr7‑ng::psr7-impl  ```

  • Création du FrontController dédié public/api/index.php qui route vers les contrôleurs (OrdersController, CustomersController).

  • Sécurité OAuth2 : implémenter le serveur d’authentification via Tuupola OAuth Server ; définir les scopes orders:read, orders:write. – Documentation OpenAPI : grâce au plugin Symfony/Drivers ou via zircote/swagger-php. Générer un fichier openapi.yaml qui sera publié sur GitHub Pages.

    Exemple d’endpoint :

    // src/Controller/OrdersController.php
    
#[OA\Get(path="/api/v1/orders/{id}", security=[["oauth2" => "orders:read"]])]
    
public function get(int $id): JsonResponse
    
{
    
  $order = $this->orderService->getById($id);
    
  return $this->json($order->toArray());
    
}

  • Gestion des erreurs : retourner toujours un ProblemDetails conforme à RFC 7807.

3.4. Gestion des événements & workflow (Jour 22‑28)

  • Hooks Dolibarr : utiliser le système d’évènements natif ($hook = new HookEnvironment(); $hook->registerGlobalFunction(...)) pour intercepter les moments clefs (order_validated, invoice_created).

  • Webhook outgoing : créer une classe WebhookManager qui consomme les événements et déclenche les appels HTTP : 

    public function dispatch(string $eventName, array $params): void
    
{
    
  switch($eventName) {
    
      case 'order_validated':
    
          $this->callExternalApi('https://external.example.com/webhook/validated', $params);
    
          break;
    
      // … autres cas
    
  }
    
}

  • Scheduler interne (option Cron ou Baserun) pour les traitements périodiques (ex. : réconciliation des stocks toutes les 3 heures).

  • Testing fonctionnel : via PHPUnit + Mockery, couvrir 80 % des scénarios (authentification, payload correct, fallback sur erreur).

3.5. Sécurité, Monitoring & Livraison (Jour 29‑30)

Action Outils / Méthodes Pourquoi
Scanning de vulnérabilités trivy (Docker), composer audit Détecter dépendances malveillantes
Hardening HTTPS Terminateur Nginx avec HSTS, certificats Let’s Encrypt Conformité RGPD
Logging structuré Monolog → Elasticsearch / Graylog Traçabilité des appels API
CI/CD GitLab CI: stages: [test, build, deploy] avec Docker-in-Docker Déploiement automatisé sur staging à chaque merge
Monitoring Prometheus + Alertmanager (ex. : taux de 5xx > 1 %) Réactivité aux incidents
Documentation utilisateur Swagger UI accessible via /api/docs Onboarding rapide des équipes internes et partenaires

Le déploiement final se fait sur un cluster Kubernetes (ex. : K3s en local ou EKS en production). Le pipeline pousse l’image Docker vers le registre, met à jour le Helm chart (dolibarr-advanced-sync) et exécute les migrations DB via helm upgrade --install.

4. Exemple concret – Synchronisation d’une commande avec un ERP externe

4.1. Scénario

Une boutique en ligne utilise Dolibarr pour gérer ses devis et ses factures. L’objectif est de notifier ERP‑Next (une solution open‑source) dès qu’une commande passe à l’état « Validée ».

4.2. Flux de travail

  1. Commande créée → Dolibarr génère un numéro (Order #1234).

  2. Hook order_validated déclenché.

  3. OrderSync construit le payload :

    {
    
 "external_order_id": "1234",
    
 "customer_id": "C001",
    
 "total": "150.00",
    
 "currency": "EUR"
    
}

  4. POST vers https://erp.example.com/api/v1/orders avec token OAuth2.

  5. Réponse 201 → mise à jour du champ external_id dans Dolibarr → Webhook d’acquittement renvoyé à Dolibarr.

  6. Erreur → log + retry exponentiel + alerte Slack.

4.3. Code minimal de l’appel

private function callExternalApi(string $url, array $data): array

{

    $client = new \GuzzleHttp\Client([

        'timeout' => 10,

        'headers' => [

            'Authorization' => 'Bearer '.$this->token,

            'Accept'        => 'application/json',

        ],

    ]);
$response = $client->post($url, [

        'json' => $data,

    ]);
return json_decode((string)$response->getBody(), true);

}

5. Bonnes pratiques & pièges à éviter

Bonnes pratiques Pièges courants
Utiliser les Hooks de Dolibarr plutôt que de modifier le core. Modifier directement le dossier core/modules → perte de mise à jour.
Versionner les API (ex. : /api/v1/…) pour éviter les ruptures. Supprimer un endpoint sans versionner → downtime brutal.
Sécuriser avec OAuth2 et scopes limités. Hard‑coder des clés API → faille de sécurité.
Documenter chaque endpoint (OpenAPI + exemple de requête). Pas de description → difficultés d’intégration pour les tiers.
Automatiser les tests (unitaires + contract‑tests avec Pact). Tester uniquement fonctionnellement sur le serveur local → fausses positives.
Faire des revues de code dès la première itération. Reporter la revue à la fin du sprint → bugs en production.
Déployer en canary avant un rollout complet. Déploiement direct sur prod → risque de panne majeure.
Surveiller les quotas d’API externe. Ignorer les limits → blocage de l’accès tiers.

6. Checklist de livraison (avant le jour 30)

✅ Élément
1 Docker‑Compose fonctionnel avec base de données et cache Redis
2 Module advanced-sync installé, migrations appliquées
3 Endpoints REST OAuth2 (GET/POST/PUT/DELETE) avec tests unitaires ≥80 %
4 Documentation OpenAPI accessible via /api/docs
5 Webhook manager configuré (exemple de 2 webhooks)
6 Pipeline CI/CD automatisé (build → test → deploy staging)
7 Logs structurés + monitoring basique (Prometheus metrics)
8 Guide d’onboarding (README + vidéo 5 min)
9 Test de charge basique (JMeter ou k6) pour 100 rps
10 Backup automatisé des bases de données (daily)

7. Conclusion

En 30 jours, il est tout à fait possible de transformer Dolibarr d’un simple ERP en un plateau d’intégration robuste, capable de servir de gateway vers n’importe quel système externe grâce à un Webservice REST complet.

  • Livraison rapide : grâce aux hooks natifs et aux modules Docker, on évite les réécritures massives.

  • Scalabilité : l’architecture micro‑services (Docker + Kubernetes) prépare le terrain pour d’éventuels déploiements en production. – Sécurité : OAuth2, HTTPS et audit continu garantissent la conformité RGPD.

Le vrai succès réside toutefois dans l’anticipation des besoins métier, la communication entre les équipes fonctionnelles et techniques, et le feedback continu à chaque sprint. Ainsi, après les 30 jours, vous ne disposerez pas seulement d’un webservice fonctionnel, mais aussi d’une culture d’intégration ancrée dans vos processus internes.

Annexes utiles

Ressource Link
Dolibarr 8.2 Documentation – Extending & Plugins https://dolibarr.org/doc/en/latest/
OAuth2 Server for PHP (Tuupola) https://github.com/tuupola/oauth2-server-php
OpenAPI Generator –templates pour PHP https://openapigenerator.com
Docker‑Compose best‑practices https://dev.to/locka/dock compose-best-practices-3j9i
Prometheus + Grafana quick‑start https://prometheus.io/docs/introduction/overview/

Prochaine étape : mettre en place un Proof‑of‑Concept sur un domaine métier précis (ex. : synchronisation avec le CRM HubSpot) et ajuster le planning en fonction des retours des parties prenantes.

Bonne implémentation ! 🚀

Publications similaires