L'API REST de Dolibarr, de la clé à la facture payée

Dolibarr fournit une API REST : tout ce que vous faites à l’écran (tiers, factures, commandes, produits…) peut se faire depuis un autre logiciel, un site ou un script. Cette page part de zéro et va jusqu’à une facture validée, avec son PDF et son paiement. Chaque commande a été exécutée le 13 octobre 2026 sur une instance Dolibarr 24.0.1 neuve.

En chemin, trois comportements à connaître, que la documentation ne signale pas :

• les lignes envoyées avec la facture changent d’ordre sur la facture et sur le PDF ;
• une facture validée par l’API n’a pas de PDF tant qu’on ne le demande pas ;
• quand le module est désactivé, l’API répond quand même « 200 OK ».

1. Activer le module

Configuration › Modules/Applications, module API / Web services (serveur REST). Sa page de configuration donne l’adresse de l’explorateur et propose de limiter l’accès à certaines adresses IP.

Tant que le module est désactivé, toute adresse de l’API répond avec le code 200 et ce texte :

Module <b>Api</b> must be enabled.<br><br>To activate modules, go on setup Area (Home->Setup->Modules).

Un script qui ne regarde que le code HTTP croira que tout va bien : vérifiez aussi que la réponse est du JSON.

Activez aussi les modules dont vous voulez les données. Pour cette page : Tiers, Factures et avoirs et, pour les paiements, Banques et caisses. Les API d’un module désactivé n’apparaissent pas.

2. Créer un utilisateur dédié et sa clé

La clé API donne exactement les droits de l’utilisateur à qui elle appartient. Ne la créez pas sur votre compte administrateur : créez un utilisateur réservé à l’API.

1. Utilisateurs & Groupes › Nouvel utilisateur : un nom, un identifiant (par exemple api-facturation).
2. Sur la ligne Jeton pour API, cliquez sur Générer : une clé de 32 caractères apparaît. Copiez-la, puis Créer l’utilisateur.
3. Onglet Permissions : n’accordez que le nécessaire. Pour tout ce qui suit, il a suffi de :

La fiche de l’utilisateur affiche ensuite la clé comme « Caché » : elle est enregistrée chiffrée en base. Pour la revoir, ouvrez la fiche en Modifier.

3. Le premier appel

Toutes les adresses commencent par https://votre-dolibarr/api/index.php/. La clé se transmet dans l’en-tête DOLAPIKEY :

DOLI=https://votre-dolibarr/api/index.php
CLE=collez_votre_cle_ici
curl -s -H "DOLAPIKEY: $CLE" "$DOLI/status"

{
    "success": {
        "code": 200,
        "dolibarr_version": "24.0.1",
        "access_locked": "0"
    }
}

L’en-tête Authorization: Bearer <clé> fonctionne aussi. Dolibarr accepte également la clé dans l’adresse (?DOLAPIKEY=…), mais elle se retrouve alors dans les journaux des serveurs et des proxys : préférez l’en-tête.

Les erreurs que vous rencontrerez

4. Créer un client

curl -s -X POST -H "DOLAPIKEY: $CLE" -H "Content-Type: application/json" \
  -d '{"name": "Boulangerie Martin", "client": 1}' \
  "$DOLI/thirdparties"

La réponse est simplement l’identifiant du tiers créé, par exemple 1. "client": 1 en fait un client. Pour retrouver un tiers par son nom :

curl -s -G -H "DOLAPIKEY: $CLE" \
  --data-urlencode "sqlfilters=(t.nom:like:'Boulangerie%')" \
  "$DOLI/thirdparties"

5. Créer la facture, puis ses lignes une par une

L’API accepte une facture avec ses lignes en un seul appel (un tableau lines). Ne le faites pas. Sur nos essais, les lignes y changent d’ordre : envoyées dans l’ordre 1, 2, 3, elles apparaissaient sur la facture et sur le PDF dans l’ordre 2, 1, 3, et dans l’ordre 3, 1, 2 en précisant le rang de chaque ligne. Pendant la création, Dolibarr croit insérer chaque ligne au milieu des autres et décale les rangs à tort. Le même code se trouve dans la 24.0.2 et dans la branche de développement.

Créez d’abord la facture seule :

curl -s -X POST -H "DOLAPIKEY: $CLE" -H "Content-Type: application/json" \
  -d '{"socid": 1, "type": 0, "date": "2026-10-13"}' \
  "$DOLI/invoices"

La réponse est l’identifiant de la facture (ici 4). socid est l’identifiant du client et "type": 0 désigne une facture standard. La date au format AAAA-MM-JJ est acceptée. Ajoutez ensuite chaque ligne, dans l’ordre voulu :

curl -s -X POST -H "DOLAPIKEY: $CLE" -H "Content-Type: application/json" \
  -d '{"desc": "Installation de Dolibarr", "qty": 1, "subprice": 690, "tva_tx": 20, "product_type": 1}' \
  "$DOLI/invoices/4/lines"

subprice est le prix unitaire HT, tva_tx le taux de TVA, et product_type vaut 1 pour un service, 0 pour un produit. La facture reste en brouillon, avec une référence provisoire du type (PROV4).

6. Valider la facture

curl -s -X POST -H "DOLAPIKEY: $CLE" "$DOLI/invoices/4/validate"

La réponse contient la facture complète, avec sa référence définitive ("ref": "FA2610-0001").

7. Générer et récupérer le PDF

À l’écran, la validation produit le PDF. Par l’API, non : après la validation, le dossier de la facture ne contient aucun PDF. Demandez-le explicitement, avec la référence obtenue :

curl -s -X PUT -H "DOLAPIKEY: $CLE" -H "Content-Type: application/json" \
  -d '{"modulepart": "invoice", "original_file": "FA2610-0001/FA2610-0001.pdf", "langcode": "fr_FR"}' \
  "$DOLI/documents/builddoc" > /dev/null

Le fichier est alors enregistré dans Dolibarr, comme si vous l’aviez généré à l’écran. Pour le télécharger, l’API renvoie son contenu encodé en base64 (ici décodé avec jq) :

curl -s -H "DOLAPIKEY: $CLE" \
  "$DOLI/documents/download?modulepart=invoice&original_file=FA2610-0001/FA2610-0001.pdf" \
  | jq -r .content | base64 -d > FA2610-0001.pdf

8. Enregistrer le paiement

Un paiement doit être rattaché à un compte du module Banques : sans accountid, l’API répond « Invalid value specified for accountid ». L’identifiant du compte se lit dans l’adresse de sa fiche (…/compta/bank/card.php?id=1). Celui du mode de règlement se trouve par l’API :

curl -s -H "DOLAPIKEY: $CLE" "$DOLI/setup/dictionary/payment_types"

Sur une installation neuve : 2 virement, 4 espèces, 6 carte, 7 chèque. Puis :

curl -s -X POST -H "DOLAPIKEY: $CLE" -H "Content-Type: application/json" \
  -d '{"datepaye": "2026-10-13", "paymentid": 2, "closepaidinvoices": "yes", "accountid": 1, "num_payment": "VIR-001"}' \
  "$DOLI/invoices/4/payments"

Avec "closepaidinvoices": "yes", la facture réglée en totalité passe au statut payée.

L’explorateur, pour tout le reste

À l’adresse https://votre-dolibarr/api/index.php/explorer/, Dolibarr liste toutes ses API. Collez la clé dans le champ en haut à droite et cliquez sur Explore : sans clé, seule l’API login apparaît. Chaque appel y est documenté et peut être essayé ; la liste dépend des modules activés. La même description, au format Swagger, est à /api/index.php/explorer/swagger.json.

Les bonnes pratiques

• Un utilisateur par usage (site, outil de facturation, script…), chacun avec ses seuls droits : vous pourrez en couper un sans toucher aux autres.
• Toujours en HTTPS : la clé circule dans chaque requête.
• Si l’API ne sert qu’à un serveur connu, limitez l’accès à son adresse IP dans la configuration du module.

Pour relier Dolibarr à un autre logiciel sans écrire le code vous-même, le forfait Module sur mesure part d’un devis précis.