API Dolibarr : Journaux et Comparaison avec les Intégrations Modernes Un article technique en français
1. Introduction
Dolibarr est un ERP‑CRM open‑source largement utilisé par les PME et les associations. Depuis la version 7, il propose une API RESTful qui permet d’interagir avec les objets (clients, factures, ventes, stocks, etc.) de façon programmatique. L’un des aspects souvent négligé mais crucial pour la fiabilité des intégrations est la gestion des logs.
Cet article passe en revue :
- Le fonctionnement des logs dans l’API Dolibarr.
- Les limites et points forts de ce système.
- La manière dont les outils modernes d’intégration/API‑management (ex. : PostgREST, GraphQL, iPaaS, Webhooks) se comparent.
- Quelques bonnes pratiques pour choisir la solution la plus adaptée à votre contexte.
2. L’API Dolibarr : Fonctionnement et Journaux
2.1. Description rapide de l’API
| Caractéristique | Détail |
|---|---|
| Architecture | RESTful, basé sur des verbes HTTP (GET, POST, PUT, DELETE). |
| Authentification | Token d’accès (login/password encodés en base64) ou session PHP ( cookies). |
| Endpoints | //api/index.php expose des routes comme /api/dictionaries/Customers, /api/dictionaries/Invoices, /api/dictionaries/Products. |
| Formats | JSON par défaut, support du format XML via le paramètre format=xml. |
| Versionnage | L’URL inclut /v1/ ou /v2/ selon la branche de Dolibarr (compatibilité ascendante). |
| DOC | La documentation officielle est disponible dans le répertoire doc/ et sur le portail développeur. |
2.2. Pourquoi les logs sont-ils essentiels ?
- Traçabilité : chaque appel API doit être auditif (qui a fait quoi, quand).
- Débogage : faciliter la résolution d’un problème de latence ou d’erreur (ex. : “404 – Object not found”).
- Sécurité : Identifier les tentatives d’intrusion ou les abus d’API.
- Statistiques : Analyser le volume d’appels et les objets les plus utilisés pour optimiser le système.
Dolibarr propose deux niveaux de journalisation :
| Niveau | Destination | Contenu |
|---|---|---|
| Journal du serveur PHP (php‑fpm / apache) | Fichier access.log / error.log |
Requête HTTP brute (URL, méthode, headers, code statut). |
| Journal Dolibarr (log file) | documentation/logs/*.log (dans le répertoire racine) |
Événements internes (création/modif/suppression d’objet, erreurs d’API, rapports de sécurité). |
| Débogage API | Option $conf['log']['debug'] = 1; |
Logs détaillés au niveau verbe (REQUEST, REPLY, SQL, etc.) – à activer uniquement en dev. |
Astuce : Pour des environnements de production, il est recommandé de désactiver le « debug », et de centraliser les journaux dans un système de SIEM (Splunk, Elastic, Graylog) grâce à
logrotateou à un agent ‑Filebeat.
3. Points forts et limites de la journalisation native de Dolibarr
| Points forts | Limites |
|---|---|
| Log détaillé par défaut lorsque le mode débogage est activé – tout, même les requêtes SQL générées, est enregistré. | Pas de sérialisation standardisée : les logs sont en texte brut, sans métadonnées JSON prêtes à être ingérées par un agrégateur. |
Gestion de rotation intégrée via logrotate sous Linux. |
Pas de niveau de gravité configurable ; tout est écrit dans le même fichier (diffsiculty to filter). |
Temps d’accès via $_SERVER['REQUEST_TIME'] -> timestamp Unix directement exploitable. |
Pas d’enrichissement (pas de corrélation avec l’identifiant client, pas de contexte de session). |
| Intégration simple dans les scripts PHP existants – pas besoin d’ajouter des bibliothèques externes. | Performance : le double appel à error_log() pour chaque requête API peut ajouter quelques ms, surtout sous forte charge. |
4. Intégrations modernes : API‑centric, iPaaS et Webhooks
| Solution | Type | Principaux apports | Journaux et observabilité |
|---|---|---|---|
GraphQL (ex. : doligraphql plugin) |
API Query‑Based | Un seul point d’entrée, requêtes spécifiques, réponses légères. | Le serveur GraphQL expose des metrics et des tracing (via graphql‑tracing intégré). |
| Webhooks (module “Webhooks” de Dolibarr ou via Zapier/Make) | Callback | Notifications en temps réel lorsqu’un objet change ; pas de polling. | Chaque webhook possède un secret et un statut de delivery; les échecs sont loggués dans la base. |
| iPaaS (Make, n8n, Zoho Flow) | Plateforme orchestration | Connecteurs pré‑construits, transformations sans code, gestion de quotas. | La plupart offrent un tableau de bord avec logs détaillés (timestamp, payload, erreurs). |
| Prisma / PostgREST (exposition de la BDD) | API direct DB | Accès aux tables sans couche business, idéal pour les analyses BI. | Les requêtes sont auditées au niveau SQL‑logger; les erreurs sont remontées par le serveur. |
| OpenAPI / Swagger (spécifications) | Documentation auto‑générée | Contrat clair entre client et serveur, génération de stubs client automatiques. | Les spécifications incluent des exemples de réponses ; les logs peuvent être mappés à ces schémas. |
En bref : les solutions modernes privilégient la standardisation (JSON Schema, OpenAPI), la décentralisation du logging (ELK‑stack, Loki), et la méta‑information (trace IDs, correlation IDs).
5. Comparaison détaillée : Dolibarr vs. approches modernes
5.1. Structuration des logs
| Critère | Dolibarr (API native) | GraphQL / iPaaS / Webhooks modernes |
|---|---|---|
| Format | texte brut (UTF‑8) | JSON structuré, souvent avec trace_id, span_id. |
| Métadonnées | seulement HTTP headers + code statut. | Header, payload, статус du worker, version d’API, version du plugin. |
| Filtrage/filtrage avancé | Simple (grep, awk). |
Possibilité de filtrer par level = {INFO, WARN, ERROR} + champs custom. |
| Scalabilité | Limité à un fichier par processus. | Distribution horizontale via Kafka, Syslog, Fluentd. |
5.2. Traçabilité & Débogage
| Éléments | Dolibarr | Solutions modernes |
|---|---|---|
| Identifiant de session | Aucun ID unique (sauf $_SESSION['dol_user_id']). |
trace_id partagé entre microservices, enrichi par OpenTelemetry. |
| Corrélation d’événement | Nécessite de recalculer manuellement à partir du timestamp. | Correlation ID transmis dans chaque requête (X-Correlation-Id). |
| Alerting | Aucun mécanisme natif (seulement notification email du script de log). | Alertes automatisées (PagerDuty, Opsgenie) via alert‑rules sur métriques. |
5.3. Performance
| Facteur | Dolibarr | Alternatives |
|---|---|---|
| Overhead API | ~5–10 ms supplémentaires par appel (log + validation). | Micro‑services légers (Node, Go) avec peu ou pas de logging bloquant (async). |
| Gestion de la charge | Limité à l’architecture monolithique. | Horizontal scaling via conteneurs (K8s) avec side‑car de logging. |
| Mise en cache | Pas de cache d’objets natif pour les réponses API. | Cache CDN ou LRU intégré (ex. : Redis) souvent présent dans les API modernisées. |
5.4. Sécurité
| Aspect | Dolibarr | Solutions modernes |
|---|---|---|
| OAuth2 / OpenID Connect | Non‑intégré (seulement token base64). | Support natif OAuth2, scopes, refresh tokens. |
| JWT | Pas de JWT, uniquement HTTP Basic. | JWT signé, expiration, revocation liste. |
| Rate‑limiting | Aucun mécanisme intégré. | Middleware de rate‑limiting (API‑gateway) avec bucket token. |
— ## 6. Bonnes pratiques pour exploiter les logs de l’API Dolibarr
- Activer le mode debug uniquement en dev
$conf['debug'] = 1; // désactiver en prod
$conf['log']['debug'] = 1; // journalisation verbeuse - Centraliser les logs via syslog « `bash
/var/www/dolibarr/htdocs/documentation/logs/*.log {
daily
rotate 14 missingok
notifempty
compress
delaycompress
sharedscripts
postrotate
systemctl reload php-fpm
endscript
} - Enrichir les logs avec des headers personnalisés
$clientId = $_SERVER['HTTP_X_CLIENT_ID'] ?? 'unknown';
error_log("[".date('c')."] [$clientId] $method $url => $status"); - Utiliser un agrégateur externe (ex. : Graylog) :
- Envoyer les fichiers
*.logvers Filebeat avec la configuration suivante :filebeat.inputs:
- type: log
enabled: true paths:
- /var/www/dolibarr/htdocs/documentation/logs/*.log
json.keys_under_root: true
output.elasticsearch:
hosts: ["es:9200"]
- Envoyer les fichiers
- Mettre en place des alertes simples (ex. : nombre d’erreurs 5xx > 10 en 5 min) via Prometheus + Alertmanager en récupérant le compteur d’erreurs depuis les métriques du serveur web.
7. Cas d’utilisation concrets ### 7.1. Scénario : Intégration d’un marketplace avec Dolibarr via API
| Étape | Implémentation |
|---|---|
| 1. Authentification | Générer un token via /api/index.php/auth/token et le conserver dans le header Authorization: Bearer <token> (via un petit wrapper). |
| 2. Création de produit | POST /api/dictionaries/Products avec payload JSON contenant les champs obligatoires (name, price, fk_families). |
| 3. Capture du log | Le wrapper envoie le payload au logger interne de Dolibarr → error_log("[Marketplace] CREATE_PRODUCT $payload"). |
| 4. Enrichissement | Le wrapper ajoute un X-Trace-Id unique (UUID) afin de corréler le log côté serveur avec le log du marketplace. |
| 5. Validation du succès | Vérifier le code 201, lire le debug.log pour s’assurer qu’aucun SQL error n’est survenu. |
| 6. Monitoring | Exporter le compteur d’appels /api/metrics (plugin metrics) vers Prometheus et créer une alerte sur le taux d’échec. |
7.2. Mise en place d’un webhook de commande
- Création du webhook dans le module Webhooks de Dolibarr (URL =
https://my‑service.com/dolibarr/order_created). - Secret partagé : générer un HMAC‑SHA256 du corps de la requête et l’ajouter dans l’en‑tête
X-Signature. - Gestion côté récepteur : consommer le webhook via
n8n– le workflow enregistrera chaque event dans PostgreSQL et loguera leevent_id,timestamp,status. 4. Débogage : si le statut HTTP n’est pas 200, le webhook réessaiera (max 3) et écrira dans le log de n8n un format JSON standardisé.
8. Verdict : Quand choisir la journalisation native de Dolibarr ?
| Situation | Recommandation |
|---|---|
| Petite structure (< 10 utilisateurs), besoin de simplicité | Utiliser les logs natifs, centraliser avec logrotate + grep. |
| Environnement de test ou dev | Activer le debug complet, profiter des traces SQL. |
| Production avec plusieurs services externes | Compléter la journalisation native avec un forwarder vers ELK ou Loki pour obtenir des logs structurés et un système d’alertes robuste. |
| Intégration continue / CI/CD | Utiliser les métriques exposées (/api/metrics) et les logs JSON de plugins (ex. : metrics, webhooks). |
| Modernisation du système | Migrez progressivement vers un proxy API (ex. : Kong, Traefik) qui ajoute la journalisation standardisée, le rate‑limiting et le support auth OAuth2. |
9. Conclusion
L’API Dolibarr possède une journalisation fonctionnelle mais rudimentaire comparée aux standards des plateformes d’intégration modernes. Elle est parfaitement adaptée aux PME qui souhaitent rester dans un environnement monolithique simple. Cependant, lorsqu’il s’agit de :
- Échanger des données en temps réel avec d’autres systèmes,
- Assurer la traçabilité à l’échelle d’un écosystème micro‑services,
- Mettre en place un monitoring avancé (alertes, tracing, corrélation d’événements),
… il devient indispensable d’enrichir ou de remplacer la journalisation native par des solutions standardisées (JSON‑structured logs, OpenTelemetry, API‑gateways) ou d’adopter des iPaaS / Webhooks capables de fournir des métriques détaillées.
En combinant l’avantage de la simplicité de Dolibarr avec les capacités d’observabilité des outils contemporains, on obtient un堅固 (solide) système d’intégration capable de répondre aux exigences actuelles tout en conservant la flexibilité qui a fait la renommée de Dolibarr.
Vous avez besoin d’un exemple d’implémentation concrète ?
- Script PHP pour forwarder les logs vers Graylog.
- Configuration Docker‑Compose avec
nginx,php-fpm,filebeat,loki. - Modèle OpenAPI décrivant les endpoints de l’API Dolibarr.
N’hésitez pas à me le demander ! Bonne intégration ! 🚀