Leçons apprises : implémenter le mode multi‑devise dans Dolibarr sans casser l’existant
Par [Nom du rédacteur] – 3 Novembre 2025
1. Introduction
Dolibarr ERP/CRM est une solution open‑source très populaire pour la gestion des petites et moyennes entreprises. Son architecture modulaire permet d’ajouter de nouvelles fonctionnalités via des modules ou des extensions. Parmi les besoins grandissants des entreprises qui se développent à l’international, la gestion multi‑devise est souvent la première à être demandée.
Pourtant, ajouter le support multi‑devise à une installation déjà en production n’est pas une tâche anodine. Une mauvaise implémentation peut entraîner : pertes de données, incohérences comptables, accidents de version ou même la rupture du processus métier.
Cet article partage les leçons apprises d’une implémentation récente dans une boutique en ligne qui a adopté Dolibarr 9.0 avec le module Multi‑Currency tout en conservant l’ensemble de son parc existant de 1 500 transactions journalières.
2. Contexte & objectifs
| Point | Situation initiale | Objectif |
|---|---|---|
| Produits | Catalogue mono‑devise (EUR) | Support des devises USD, GBP, CHF et EUR simultanément |
| Clients | 3 000 comptes, frais fixes | Factures et devis dans la devise du client |
| Paiement | Stripe/SEPA uniquement en EUR | Concaténation des passerelles de paiement selon la devise |
| Compta | Plan comptable unique | Conservation du plan comptable tout en publiant les écritures avec la bonne monnaie |
| Contrainte | Aucun downtime, pas de re‑déploiement du serveur | Implémentation progressif‑débogué |
3. Analyse des risques
| Risque | Impact potentiel | Mitigation prévue |
|---|---|---|
| Perte de données lors d’une migration du module | Historique de factures perdu | Sauvegarde incrémentale + test de restauration sur environnement de staging |
| Incohérences de conversion (taux de change obsolète) | Erreurs de réconciliation bancaire | Intégration d’une API taux de change (ex. : exchangerate.host) avec cache quotidien |
| Blocage des versions à cause de conflits de module | Impossibilité de mettre à jour Dolibarr | Utilisation d’un fork de multicurrency compatible avec la branche actuelle (ex. : dev-2024x) |
| Résistance du personnel face au changement | Retard dans la prise en main | Sessions de formation + documentation pas à pas |
4. Stratégie d’implémentation pas‑à‑pas
4.1 Pré‑requis & environnement
- Sauvegarde complète de la base (
mydatabase.sql) et du répertoire$DOL_HOME/doli(fichiers de configuration, pièces jointes). - Copie locale du dépôt
github.com/Dolibarr/dolibarrsur un serveur de test. - Création d’un environnement isolé (Docker) pour éviter toute interférence avec la production.
4.2 Choix du module « Multi‑Currency »
- Le module officiel
multicurrencyde la communauté est maintenu sur la branche14.0-dev. - Pour éviter les conflits de dépendances, on crée un fork nommé
multicurrency-9.0. - Les changements clés :
- Compatibilité avec
dolibarr 9.0(mise à jour dudll*des fichiers). - Ajout d’un paramètre de taux de change fixe (au lieu du calcul dynamique par défaut).
- Gestion du choix de la devise sur le formulaire de facture (client → devise).
- Compatibilité avec
4.3 Mise en place du cache de taux de change
// Cache simple basé sur des fichiers JSON
function get_rate(string $from, string $to) {
$cache_file = _PATH_ROOT.'/cache/rate_'.$from.'_'.$to.'.json';
if (file_exists($cache_file) && (time() - filemtime($cache_file) < 86400)) {
$rates = json_decode(file_get_contents($cache_file), true);
return $rates[$to] ?? 1;
}
// Appel API externe
$response = file_get_contents("https://api.exchangerate.host/latest?base=$from&symbols=$to");
$data = json_decode($response, true);
$rate = $data['rates'][$to];
file_put_contents($cache_file, json_encode([$to => $rate]));
return $rate;
}- Tous les montants stockés en base sont convertis au moment du paiement et déclarés dans la devise comptable (EUR) via le taux du jour.
- Le journal comptable reçoit deux lignes : transaction et variation de change.
4.4 Migration des données existantes
| Étape | Action | Exemple de script |
|---|---|---|
| 1. Export CSV | Extraire toutes les factures (devise EUR) | SELECT id, amount, date FROM ll_facture; |
| 2. Conversion | Appliquer le taux du jour et créer une nouvelle ligne avec la devise cible | UPDATE ll_facture SET currency='USD', amount=ROUND(amount * $rate_USD,2) WHERE currency='EUR'; |
| 3. Import | Ré‑importer les lignes converties dans la table ll_facture avec champ currency rempli |
Script Python → API REST de Dolibarr (/api/v1/invoices) |
| 4. Vérification | Comparer le total facturé avant/après conversion | SELECT SUM(amount) FROM ll_facture WHERE currency='EUR'; vs. nouveau devis |
Leçon clé : garder un identifiant de version (ex. :
v1.0‑2025‑11‑01) sur chaque ligne importée afin de pouvoir la retracer en cas d’erreur.
4.5 Tests fonctionnels & de charge
- Tests unitaires sur le module
multicurrency(PHPUnit). - Scénarios de conversion : 5% de variation de taux quotidien, dates limites de paiement.
- Tests de charge avec 10 000 requêtes simultanées (JMeter) pour s’assurer que le cache ne crée pas de goulot d’étranglement.
4.6 Déploiement progressif
| Phase | Action | Durée |
|---|---|---|
| Pilot | 5 % des clients (groupe interne) activent la devise | 1 semaine |
| Beta | 30 % des clients en conversion auto (tests manuels) | 2 semaines |
| Production | Activation globale avec monitoring (Grafana) | 1 jour (hors heures de pic) |
- Rollback possible via le backup du module
multicurrency-9.0et la restauration de la base avant la migration.
5. Lessons apprises (les points qui ont le plus marqué)
| # | Leçon | Pourquoi est‑ce important ? |
|---|---|---|
| 1 | Ne jamais modifier le cœur de Dolibarr sans fork | Toute modification du core empêche les futures mises à jour et crée des conflits de mise à jour. |
| 2 | Cache de taux de change | Un appel API à chaque transaction ralentit le serveur et génère des coûts inutiles. Un cache persistant garantit la performance. |
| 3 | Sauvegarde + restauration testée | Laisser les sauvegardes « au cas où » n’est pas suffisant ; le test de restauration sur un environnement de test est le seul moyen de garantir la récupération. |
| 4 | Séparer les flux monétaires | Stockage interne : lier chaque transaction à une devise. Reporting comptable : convertir systématiquement en devise comptable (EUR). |
| 5 | Documentation pas à pas | Les équipes techniques et non‑techniques (comptabilité, service client) doivent disposer d’un guide visuel (flowchart, screenshots). |
| 6 | Communication progressive | Informer petit‑bout en petit‑bout les parties prenantes évite les résistances et permet de corriger les bugs en production contrôlée. |
| 7 | Gestion des variations de devise | Ajouter une entrée comptable « gain/perte de change » évite que les écarts inattendus passent inaperçus dans les états financiers. |
| 8 | Tests de charge dès le début | Découvrir un goulet d’étranglement après le déploiement nuit à la réputation. Simuler le pic de trafic dès la phase de développement évite cela. |
6. Bonnes pratiques à retenir
- Fork & versionnage : créez toujours un fork du module et conservez le numéro de version (ex. :
multicurrency-9.0.1). - Isolation du déploiement : tests en Docker/CI avant de toucher à la prod.
- Cache intelligent : choisissez un intervalle de mise à jour qui correspond à votre fréquence de transaction (ex. : 24 h pour les petites boutiques).
- Journalisation : loggez chaque conversion (
$old_amount,$new_amount,$rate) pour traçabilité. - Versionning de la base : ajoutez une colonne
currency_versionqui indique la version du taux appliquée lors de l’enregistrement. - Formation utilisateur : préparez un mini‑tutoriel de 10 minutes (vidéo ou slide) montrant comment changer la devise d’une facture.
- Suivi post‑déploiement : pendant les 48 h suivantes, surveillez les écarts de sortie du module (rapport d’écarts > 2 % → alerte).
7. Conclusion
L’ajout du support multi‑devise dans Dolibarr n’est pas une simple activation de case à cocher. Il s’agit d’une modernisation du processus de gestion financière qui implique : sommation de plusieurs flux monétaires, conversion exacte des montants, mise à jour des écritures comptables et, surtout, une forte discipline de sauvegarde, de test et de communication.
En suivant les étapes décrites ci‑dessus :
- Vous préservez l’intégrité de votre installation existante,
- Vous garantis la cohérence comptable et fiscale,
- Vous offrez à vos clients la possibilité de payer dans leur devise préférée,
- Vous respectez les exigences légales (taux de change, variations de change).
Dans les organisations où la rapidité d’évolution est un avantage concurrentiel, ces leçons vous permettront de déployer de nouvelles fonctionnalités sans crainte de « casser l’existant », tout en préservant la stabilité et la confiance de vos utilisateurs.
À votre prochaine mise à jour ?
“Le meilleur changement est celui qui s’opère sans bruit, mais qui laisse une empreinte durable.”
— Proverbe agile appliqué à Dolibarr.