Diagnostiquer Dolibarr : transport Tutoriel pas à pas avec intégrations modernes

Version 2025 – rédigé en français

1. Introduction

Dolibarr ERP/CRM est une solution open‑source très appréciée pour sa simplicité d’utilisation et son extensibilité. L’un des points clés d’une implémentation réussie réside dans la configuration du transport : il s’agit du canal par lequel les données de factures, commandes, paiements ou recibus sont échangés avec les banques, les services de paiement en ligne ou les plateformes de facturation tierces.

Cet article vous propose un tutoriel complet pour diagnostiquer, configurer et optimiser le transport dans Dolibarr, tout en intégrant les solutions modernes (API REST, webhooks, services de paiement SaaS, passerelles de paiement blockchain, etc.). > Objectif : En suivant ce guide pas à pas, vous serez capable d’identifier les problèmes courants, de les corriger, puis de connecter Dolibarr à des services externes modernes en toute sécurité.

2. Prérequis avant de commencer

Élément Version conseillée Pourquoi
PHP 8.2 (ou +) Dolibarr 20.0+ requiert PHP 8.1 minimum; les nouvelles intégrations utilisent des extensions PHP (curl, json, openssl).
MySQL / MariaDB 10.6+ Compatibilité avec les nouvelles fonctions de chiffrement.
Dolibarr 20.x (ou supérieure) Les modules de transport ont été enrichis à partir de cette version.
Accès administrateur Oui Nécessaire pour modifier les paramètres de transport et exécuter des diagnostics.
Environnement de test Obligatoire Ne jamais appliquer les changements directement en production.

Astuce : Utilisez Docker ou XAMPP pour isoler votre environnement de test.

3. Principes de base du transport dans Dolibarr

  1. Transport interne : échanges entre modules Dolibarr (ex. facture → paiements).

  2. Transport externe : connexion à des services externes (banques, PSP – Payment Service Providers, API de courrier électronique, etc.).

  3. Modes de transport : – HTTP/S (curl, file_get_contents) – utilisé par la plupart des API REST.

    • SMTP – pour les notifications par email.

    • File‑system – fichiers CSV/JSON que vous déposez dans un répertoire partagé.

    • WebSockets / long‑polling – rares mais de plus en plus utilisés pour les notifications en temps réel.

Le diagnostic consiste à vérifier la configuration, la disponibilité du service distant, puis les logs de Dolibarr.

4. Étape 1 – Accéder aux paramètres de transport

  1. Connectez‑vous à Dolibarr en tant qu’admin. 2. Menu Setup → Parameters → Transactions (ou Setup → Parameters → Email / SMS selon le transport).

  2. Sélectionnez le type de transport que vous souhaitez inspecter (ex. « Payment gateway », « Banking », « PDF mailing »).

  3. Cochez Afficher les logs pour activer l’écriture des messages de diagnostic dans le fichier dolibarr.log. > Note : Dans les versions récentes, chaque module (ex. Bank, Card) possède son propre onglet de configuration.

5. Étape 2 – Vérifier la connectivité réseau

# Exemple de test depuis le serveur où tourne Dolibarr

curl -v https://api.payex.com/v1/payments

  • Réponse attendue : Code HTTP 200 ou 201.

  • En cas d’erreur :

    • Timeout → Problème de firewall ou de serveur inaccessible.

    • SSL_connect: Certificate verify failed → Certificat expiré ou chain incomplete.

    • Connection refused → Port fermé ou service non lancé.

Correction rapide

  • Ouvrez le port 443 (ou le port spécifique du service) dans le firewall.

  • Installez les certificats racine manquants (ca-certificates).

  • Testez avec openssl s_client -connect api.payex.com:443 -servername api.payex.com.

6. Étape 3 – Analyser les logs de Dolibarr

tail -f /var/www/html/dolibarr.log | grep -i "transport"

  • Mots‑clés à chercher : TRANSPORT_ERROR, TRANSPORT_SUCCESS, TRANSPORT_WARNING.

  • Exemple de ligne : 
    2025-10-31 12:45:07 ERROR TRANSPORT_ERROR: Unable to connect to https://bank.example.com/ws

Interprétation

Message Signification typique Action recommandée
TRANSPORT_ERROR: SSL certificate problem Certificat expiré ou chaîne incomplète Mettre à jour les certifs dans /etc/ssl/certs ou passer curl.cainfo.
TRANSPORT_ERROR: 401 Unauthorized Clé API ou login erronés Vérifier les paramètres API Key dans le module concerné.
TRANSPORT_SUCCESS Tout va bien, mais vous pouvez quand même vérifier le payload S’assurer que les données envoyées sont au format attendu par le serveur.

7. Étape 4 – Configurer un transport moderne (API REST) ### 7.1 Exemple : Intégration à une plateforme de paiement Stripe

  1. Créer une clé API Stripe dans le tableau de bord Stripe (mode “Standard”).

  2. Dans Dolibarr → Setup → Payments → Credit Card Providers → choisir Stripe.

  3. Renseigner :

    • Site ID = pk_test_XXXXXXXXXXXXXXXX (clé publique)

    • Secret Key = sk_test_XXXXXXXXXXXXXXXX (clé secrète)

    • API version = 2023-10-16 (ou la version recommandée)

  4. Activer Webhook :

    • Copier l’URL de webhook générée par Dolibarr (https://votre-domaine.com/htdocs/.../index.php?main=...).

    • Ajouter cet URL dans Webhooks → Add endpoint dans le dashboard Stripe.

7.2 Valider le transport

# Test d’appel direct depuis le serveur

curl -X POST https://votre-domaine.com/htdocs/.../index.php -d "module=stripe&action=test_connection"

  • Vous devez obtenir OK ou un JSON contenant la version de l’API.

  • Si vous recevez ERROR, revisez les clés et les options curl dans /etc/php/8.2/mods-available/curl.ini (CURLOPT_SSL_VERIFYPEER à 1).

7.3 Gestion des webhooks (notifications en temps réel)

  • Webhook reçu → Dolibarr déclenche l’action Payment received.

  • Diagnostic : Vérifiez que dolibarr.log indique WEBHOOK_RECEIVED.

  • Débogage : Activez le mode debug dans config.conf ($conf['debug'] = true;).

8. Étape 5 – Intégrer d’autres services modernes

Service Transport recommandé Points clés de configuration
Mailgun / SendGrid HTTP‑POST → API REST Utiliser le module Email de Dolibarr avec curl et Authorization: Api-Key.
Google Drive / Dropbox WebDAV / API REST Configurer file_system dans Setup → Storage puis créer une règle de transfert de factures PDF.
ERP externes (SAP, Odoo) SOAP ou OData (SOAP) Activer le module SOAP via php-soap; fournir le WSDL et les credentials.
Blockchain (ex. Bitcoin Lightning) Websocket + JSON‑RPC Utiliser le plugin Payment → Lightning – vérifier les paramètres node_url, macaroon_path.
Chatbots / RPA Webhook (JSON) Créer une action Run script qui poste sur l’URL du bot (https://bot.example.com/endpoint).

Bonne pratique : Isoler chaque transport dans un fichier custom_transport.php que vous incluez via require_once. Ainsi, vous pouvez tester sans impacter le reste du système.

9. Étape 6 – Métriques de suivi post‑déploiement

Métrique Pourquoi la suivre Outil de visualisation
Taux de succès des appels API Détecter les ruptures de service du provider Grafana + Prometheus (exporter /dolibarr/api/v1/calls)
Latence moyenne Optimiser la configuration HTTP (keep‑alive) Kibana (logs TRANSPORT_SUCCESS avec timestamp)
Erreurs 4xx/5xx Identifier les problèmes d’authentification ou de serveur distant ElasticSearch + Alertmanager
Volume de messages webhook Contrôler la fréquence des notifications Panel Webhooks dans le tableau de bord Dolibarr (module Advanced Performance).

Configuration rapide : Ajoutez à dolibarr.conf une ligne log_level = DEBUG; et activez le module Metrics dans Setup → Diagnostics.

10. Checklist de validation finale

✅ Action
1 Les logs affichent uniquement TRANSPORT_SUCCESS (ou des messages clairement identifiables).
2 Les appels à l’API externe retournent les codes HTTP attendus.
3 Les webhooks sont correctement reçus et traités (statut processed).
4 Les certificats SSL sont valides et à jour (openssl s_client fonctionne).
5 Les clés API sont stockées hors du répertoire web (dans /etc/dolibarr/ ou un coffre).
6 Tests de reprise de réseau (simuler un downtime) montrent une re‑tentative et un retour au travail automatique.
7 Les métriques de performance sont dans les seuils définis (latence < 200 ms, erreur < 0,5 %).

11. Bonnes pratiques & Sécurité

  1. Utilisez toujours TLS 1.2+ – désactivez TLS 1.0/1.1 dans php.ini.

  2. Restreignez l’accès aux endpoints via IP whitelist (ex. allow_url_fopen = false, allow_url_include = false).

  3. Ne stockez jamais les clés API en clair dans les fichiers de configuration public ; préférez le vault (ex. HashiCorp Vault, AWS Secrets Manager). 4. Mettez à jour régulièrement les bibliothèques cURL/OpenSSL pour éviter les vulnérabilités connues.

  4. Segmentez les environnements : dev, staging, prod avec des endpoints distincts pour chaque zone.

  5. Sauvegardez vos configurations (export DOL_CONF=…) avant toute modification majeure.

12. Conclusion

Diagnostiquer le transport dans Dolibarr ne se limite pas à un simple contrôle de connexion. Il s’agit d’une démarche itérative où :

  • Vous vérifiez la configuration, les logs et la connectivité.

  • Vous testez chaque appel API ou webhook.

  • Vous intégrez des services modernes (API REST, webhooks, WebSockets) tout en gardant une traçabilité via les métriques.

  • Vous appliquez les bonnes pratiques de sécurité et de résilience. En suivant ce tutoriel étape par étape, vous pourrez non seulement résoudre les problèmes existants, mais également tirer parti des dernières innovations (paiements instantanés, synchronisation de données en temps réel, extensions blockchain) pour enrichir votre ERP/CRM Dolibarr. > À vous de jouer : Installez un environnement de test, reproduisez les scénarios décrits, et vous verrez rapidement vos processus de transport passer d’un état « éphémère » à une chaîne de communication fiable et moderne.

Références complémentaires

Bonne intégration ! 🚀

Publications similaires