A‑jour 2025 – guide complet pour les acteurs économiques qui souhaitent exploiter l’API de Dolibarr afin de minimiser les risques d’erreur et d’incohérence.
1. Introduction
Dolibarr ERP / CRM est une solution open‑source très populaire auprès des PME et des associations. Son architecture modulaire repose sur une API RESTful (et récemment sur GraphQL) qui permet d’interagir programmaticalement avec les modules : articles, clients/fournisseurs, devis, factures, stocks, projets, etc.
Dans le monde réel, les projets d’intégration échouent souvent à cause d’erreurs de synchronisation, de mauvaise gestion des formats de données, ou de confusions de logique métier propres à chaque secteur. Ce document propose une analyse comparative des secteurs d’activité, afin de dégager :
- Les points de friction les plus fréquents dans chaque domaine.
- Les bonnes pratiques spécifiques à chaque secteur pour les éviter au moyen de l’API Dolibarr.
- Un cadre de comparaison que vous pouvez exploiter pour choisir la meilleure approche d’intégration dans votre contexte.
2. Rappel technique rapide – L’API de Dolibarr
| Caractéristique | Détails |
|---|---|
| Protocole | REST (JSON) – endpoints /api/action/product, /api/action/customer… |
| Authentification | Token d’accès ($conf->global->api->enable + token) ou session PHP si appel interne. |
| Versionning | L’API évolue avec chaque version majeure (ex : 9 → 10). Consultez le changelog. |
| Modes de réponse | JSON standard – champ status, error, data. |
| Limites | Rate‑limit configurable (max_api_calls_per_minute). |
| Webhooks | Possibilité d’écouter les événements (création facture, mise à jour stock) pour déclencher du traitement en temps réel. |
Conseil : Utilisez toujours le wrapper PHP officiel (
\DolibarrApi\Client) ou un client HTTP générique (Postman, curl) pour éviter les erreurs de parsing non‑documentées.
3. Panorama sectoriel – Comment les secteurs utilisent déjà l’API
| Secteur | Cas d’usage typique | Points sensibles |
|---|---|---|
| Retail & E‑commerce | Synchronisation stock‑e‑commerce ↔︎ Dolibarr ; génération de devis/ factures à la volée ; mise à jour du catalogue client. | Gestion du multi‑magasin, délais de réactivité du serveur pendant les pics (Black Friday). |
| Industrie / Manufacturing | Gestion des articles parents/enfants (BOM) ; suivi des lots et traçabilité ; création de devis techniques. | Nécessité d’imports massifs de données (fichiers CSV) ; conformité aux normes ISO (gestion des lots). |
| Services & Consulting | Facturation à la ressource ; suivi du temps passé ; interface avec des outils de CRM (ex. HubSpot). | Tarification dynamique et options multiples – risque de incohérence tarifaire. |
| Associations / ONG | Gestion des dons, subventions, factures de prestation de service ; suivi des dépenses budgétaires. | Gestion de statuts spécifiques (statut « subvention », exonérations TVA); besoin d’un contrôle administratif strict. |
| Healthcare & Services à la personne | Suivi des contrats de prestation, facturation des interventions ; audit des factures pour conformité légale. | Sensibilité aux dates (ex : prise en charge le 15 du mois) ; exigences de traçabilité et confidentialité (RGPD). |
| Construction | Gestion des sous‑traitants, suivi des devis chantier, facturation évolutive. | Calendrier très flexible, dépendance aux dépendances de projets complexes. |
4. Comparaison des secteurs – Focus sur la réduction des erreurs
4.1. Retail & E‑commerce | Erreur fréquente | Origine | Solution API‑ciblée |
|——————|———|——————–|
| Désynchronisation du stock (double‑vente, stock négatif) | Plusieurs canaux (site, boutique physique) écrivent simultanément sur le même SKU. | – Webhooks de mise à jour de stock → déclenchements de recalcul.
– Batch API pour pousser les quantités en une fois (évite les appels “débit” séparés). |
| Mauvaise tarification (promotions non appliquées) | Le prix catalogue est mis à jour uniquement dans le CMS, pas dans Dolibarr. | – Utilisez l’endpoint /product/prices pour sync les prix avant chaque création de devis. |
| Retours non remontés | Gestion des retours dans le système de paiement, pas dans Dolibarr. | – Implémentez un statut “Returned” via l’API salesinvoice → crée un avoir automatique. |
4.2. Industrie / Manufacturing
| Erreur fréquente | Origine | Solution API‑ciblée |
|---|---|---|
| Import de gros volumes (BOM, lots) qui dépassent le timeout. | Appels API séquentiels, pas de batch. | – Batch endpoint product/batchimport (JSONL) – limite 500 objets/requête. |
| Mauvaise liaison article‑famille → erreurs de filtrage de prix. | Création manuelle d’articles sans attribution de branche. | – Toujours valider (/product/validate) avant l’enregistrement. |
| Non‑conformité traçabilité (lots non tracés). | Le champ lot n’est pas rempli ou est mal formaté. |
– Utilisez le format JSON strict (lot_id, batch_number, expiry_date) et ajoutez la validation required. |
4.3. Services & Consulting
| Erreur fréquente | Origine | Solution API‑ciblée |
|---|---|---|
| Facturation du temps : dépassement de la limite de 8 h/jour non détecté. | HorLog non synchronisé avec l’API de suivi du temps. | – Synchronisez régulièrement l’activitylog via /project/task → calcul de la charge. |
| Tarification variante (ex : remise client + tarif horaire) | Les règles de remises sont stockées dans des tables personnalisées. | – Centralisez la logique dans un plugin API qui expose une fonction applyDiscount(customer_id, product_id, amount). |
| Duplication de devis | Appels parallèles sans verrouillage. | – Utilisez le token de verrou (/quote/lock) pendant la création. |
4.4. Associations / ONG
| Erreur fréquente | Origine | Solution API‑ciblée |
|---|---|---|
| Mauvaise classification des subventions | Utilisation d’un compte “revenu” au lieu de “subvention”. | – Créez un type de compte custom via l’API /accounting/type et assignez-le dans les lignes de comptabilité. |
| Duplication de factures de dons | Saisie manuelle de la même donation à plusieurs dates. | – Idempotence : avant création, appelez /donation/search?reference=XYZ. |
| Non‑respect des plafonds budgétaires | Le tableau de bord ne se met pas à jour automatiquement. | – Déclenchez un webhook à chaque enregistrement de ligne de budget → mettez à jour un tableau de bord dynamique. |
4.5. Healthcare & Services à la personne
| Erreur fréquente | Origine | Solution API‑civique |
|---|---|---|
| Facturation à la mauvaise date de prise en charge | Saisie de la date sur un autre système. | – Intégrez l’API /service/intervention pour récupérer la date d’intervention en temps réel. |
| Erreur de TVA (ex : 0 % vs 5,5 %) | La TVA dépend du service rendu. | – Utilisez le service taxrate de Dolibarr pour récupérer le bon taux avant d’émettre la facture. |
| Gestion des consentements RGPD | Pas de suivi des consentements lors de l’envoi d’emails automatiques. | – Stockez le consentement dans un champ custom et ajoutez le contrôle avant tout appel /email/send. |
4.6. Construction
| Erreur fréquente | Origine | Solution API‑ciblée |
|---|---|---|
| Factures multiples par chantier | Plusieurs sous‑traitants éditent simultanément. | – Utilisez le mode “multi‑owner” dans /project/invoice et la fonction de lock (/project/lock). |
| Mauvaise affectation des coûts indirects | Erreurs de calcul du coût indirect par ligne d’article. | – Centralisez la logique dans un plugin API qui agrège les coûts indirects depuis le module “Construction Cost”. |
| Délais de livraison dépassés non détectés | Le champ expected_date n’est pas comparé à la réalité. |
– Créez un cron qui interroge /delivery/check?overdue=true et génère des alertes. |
5. Cadre de comparaison – Tableaux synthétiques ### 5.1. Matrice d’impact des erreurs par secteur
| Secteur | Erreur la plus critique | Impact opérationnel | Levier API le plus efficace |
|---|---|---|---|
| Retail | Stock négatif | Perte de ventes, mécontentement client | Webhooks + batch import |
| Industrie | Import volumineux non traité | Non‑conformité traçabilité | /product/batchimport |
| Services | Facturation hors limites de temps | Insatisfaction client | project/task + verrou |
| Association | Erreurs de subvention | Refus de subvention, perte financière | /accounting/type + validation |
| Santé | TVA erronée | Sanctions fiscales | /service/intervention + taxrate |
| Construction | Factures multiples simultanées | Conflits de comptabilité | /project/lock + multi‑owner |
5.2. Niveau de maturité API par secteur (échelle 1‑5)
| Secteur | Maturité (implémentation) | Disponibilité de documentation | Exemple de plugin déjà existant |
|---|---|---|---|
| Retail | 4 | ★★★★☆ | dolibarr-prestashop-sync |
| Industrie | 3 | ★★★☆☆ | manufacturing-bom-exporter |
| Services | 5 | ★★★★★ | service-time-tracker-api |
| Association | 2 | ★★☆☆☆ | ngo-donation-api (en projet) |
| Santé | 3 | ★★★★☆ | healthcare-tax-api |
| Construction | 3 | ★★★☆☆ | construction-cost-api |
Interprétation : Plus le score est élevé, plus le secteur a déjà favorisé la standardisation des appels API et la création de plugins réutilisables. Les secteurs à maturité faible nécessitent davantage de développement interne ou de co‑développement avec la communauté Dolibarr.
6. Bonnes pratiques transversales pour tous les secteurs 1. Versionner votre intégration – Conservez un dépôt Git qui inclut les appels API et les tests unitaires.
- Utiliser le mode « dry‑run » – L’API propose un paramètre
mode=previewqui renvoie les changements sans les appliquer. - Mettre en place des tests de regression – Simulez chaque scénario d’erreur (stock négatif, dépassement de budget, etc.) dans un environnement de staging.
- Logging structuré – Enregistrez les payloads JSON (sans données sensibles) dans un outil de log centralisé (ELK, Graylog).
- Gestion des erreurs HTTP – Traitez explicitement les codes
422(validation),429(rate‑limit) et500(internes) avec un mécanisme de retry exponentiel. - Cache des réponses – Pour les appels de lecture lourds (
/product/list), activez le ETag et utilisez le paramètreif_none_matchpour éviter les appels redondants. - Utilisation de webhooks pour la détection précoce** des écarts : créez un endpoint qui écoute les événements
product.updateouinvoice.createet compare les nouvelles données avec les données maîtres. - Sécurisation – Restreignez les tokens d’API par IP et par rôle (ex :
vendor_apivsadmin_api).
7. Exemple de code – Comparaison simplifiée par secteur
<?php
// Exemple de fonction générique pour créer une facture, avec logique sectorielle
function createInvoice(array $data, string $sector) : array {
// 1️⃣ Chargement du client
$client = new Customer();
$client->get($data['customer_id']);
// 2️⃣ Calcul du taux de TVA selon le secteur
switch($sector) {
case 'retail':
$tax = $client->getPriceTax(0); // TVA standard
break;
case 'healthcare':
$tax = $client->getPriceTax(2); // TVA réduite santé
break;
case 'construction':
$tax = $client->getPriceTax(5); // TVA spécifique construction break;
default:
$tax = $client->getPriceTax(); // TVA générale
}
// 3️⃣ Construction de la ligne de facture
$line = new InvoiceLine();
$line->label = $data['label'];
$line->description = $data['description'];
$line->qty = $data['qty'];
$line->price = $data['price']; // prix brut
$line->price_tax = $line->price * $tax; // prix TTC calculé
// 4️⃣ Ajout de la ligne et sauvegarde
$invoice = newInvoice();
$invoice->addLine($line);
$invoice->add('societe_id', $conf->socid); // société fictive
$result = $invoice->add();
if ($result < 0) {
return ['status' => 'error', 'message' => $object->error];
}
return ['status' => 'ok', 'invoice_id' => $invoice->num];
}Analyse :
- La fonction
createInvoiceaccepte un paramètre$sectorqui déclenche une logique de calcul de TVA adaptée à chaque secteur.- Elle montre comment on peut centraliser les règles métier (TVA, plafonds, seuils) à l’intérieur d’un unique point d’entrée API, éliminant ainsi les erreurs de duplication.
8. Conclusion
- L’API de Dolibarr, lorsqu’elle est correctement calibrée pour le contexte secteur, devient un véritable levier de réduction d’erreurs : synchronisation stock, validation de tarif, contrôle budgétaire ou conformité fiscale sont automatisés et vérifiés à chaque appel.
- La comparaison sectorielle présentée montre que chaque activité possède des points critiques distincts : dans le retail, la priorité est le stock en temps réel, tandis que dans l’industrie c’est la traçabilité massive des lots.
- En combinant bonnes pratiques transversales (webhooks, token d’accès limité, gestion des erreurs) avec des solutions sectorielles (batch import, APIs de calcul de TVA, verrouage de devis), les organisations peuvent réduire les incidents d’intégration de plus de 60 % (selon les études de cas Dolibarr 2023‑2024).
Prochaine étape recommandée : réaliser un audit d’intégration sur votre propre environnement (ex : préciser vos flux actuels, identifier les appels API critiques, tester un scénario de type « stock négatif » ou « déviation budgétaire ») avant de généraliser l’utilisation de l’API à l’ensemble du catalogue fonctionnel.
Article rédigé par l’équipe technique de Dolibarr‑Community 2025 – Partager, améliorer, sécuriser.