API Dolibarr : retail FAQ sans casser l’existant

Version 1.0 – 3 novembre 2025

Objectif : vous fournir un guide complet, en mode « FAQ », pour exploiter l’API de Dolibarr dans un contexte retail tout en préservant la stabilité de votre installation actuelle.

1️⃣ Pourquoi passer par l’API Dolibarr en mode retail ?

Besoin retail	Solution apportée par l’API
Gestion en temps réel des stocks	Consultation et mise à jour instantanée des quantités via des endpoints REST.
Intégration avec un Point‑de‑Vente (PDV)	Appels asynchrones depuis le terminal POS (JavaScript, Android, iOS).
Suivi des ventes par point de vente	Export/import des factures et des paiements en quelques requêtes.
Synchronisation multi‑entreprise	API multi‑company : chaque société possède son propre namespace.
Extension & automation	Hooks, scripts PHP ou appels HTTP à automatiser les flux (re‑approvisionnement, tarification dynamique).

Bottom line : l’API de Dolibarr ne remplace pas votre interface d’administration ; elle agit comme un calque supplémentaire que vous pouvez activer uniquement sur les environnements de production que vous décidez de “router” vers l’API.

2️⃣ Installation & activation de l’API sans impacter le système existant

Étape	Action	Risque pour l’existant
1. Activer le module	Extensions → Modules → Gestion des API → Activer “API REST”.	Aucun impact direct ; le module ajoute uniquement des points d’entrée HTTP.
2. Configurer les routes	Dans Administration → Système → API → Routes, vous pouvez choisir les sous‑domaines (ex. `/api/retail`).	L’activation se fait par route, donc vos URLs classiques restent intactes.
3. Limiter les droits par défaut	Créez d’abord un key avec le rôle “Read‑Only”.	Les utilisateurs disposant d’un key plus puissant peuvent être ajoutés plus tard, sans toucher aux comptes existants.
4. Tests en mode “shadow”	Utilisez un reverse‑proxy (NGINX) ou le module Rewrite pour rediriger uniquement les requêtes provenant d’une IP/developpeur dédié.	Le trafic habituel ne passe jamais par `/api/*` tant que vous ne le décidez pas.
5. Désactiver le module en un clic	Dans le tableau de bord, désactivez simplement “API REST”.	Tous les endpoints retournent 404 ; aucune donnée n’est perdue.

Bon à savoir : La plupart des modules de l’API sont déconnectés du reste du système tant que vous ne les avez pas explicitement assignés à une route. C’est la clef pour éviter toute rupture accidentelle.

3️⃣ Authentification – Comment obtenir une clé API sans toucher aux comptes headers existants

Accédez à Administration → Système → API → Authentification.

Cliquez sur “Créer un key”.

Nom du key : retail‑demo‑001.

Rôle : API_ReadOnly.

Durée : Indefinie (ou définissez une date d’expiration).

IP autorisée (optionnelle) : IP_DE_VOTRE_POS.

*Ce processus crée uniquement un enregistrement de type api_key* dans la table user), distincte des utilisateurs “front‑office”. Aucun compte client existant n’est modifié.

4️⃣ Les appels les plus fréquents – Mini‑FAQ code

4.1 Lister les produits en stock (sans filtrer par défaut)

curl -X GET "https://ma-boutique.fr/api/retail/stock?mode=detail" \

     -H "Authorization: Token retail-demo-001"

Réponse type

{

  "status": "ok",

  "data": [

    {"id": 27, "designation":"Casquette", "qte": 150, "price": 9.90},

    {"id": 53, "designation":"T-shirt",  "qte":  34, "price": 19.50}

  ]

}

4.2 Déposer une vente depuis le PDV

POST /api/retail/transaction

Authorization: Token retail-demo-001

Content-Type: application/json
{

  "type": "sale",

  "customers": [{ "id": 12, "name":"Dupont Jean", "email":"j.dupont@mail.com"}],

  "lines": [

    { "product_id": 27, "quantity": 2, "unit_price": 9.90 },

    { "product_id": 53, "quantity": 1, "unit_price": 19.50 }

  ],

  "payment_method": "cash"

}

Note : La réponse comprend transaction_id et le statut de mise à jour du stock (décrés). Aucun champ supplémentaire n’est nécessaire dans votre table de ventes – tout est ajouté automatiquement.

4.3 Mettre à jour le prix d’un produit de façon non disruptive

curl -X PUT "https://ma-boutique.fr/api/retail/product/27/price" \

     -H "Authorization: Token retail-demo-001" \

     -d '{"price": 8.90}'

Answer : { "status":"ok", "product_id":27, "old_price":9.90, "new_price":8.90 }

Astuce : Utiliser la balise PUT et l’en‑tête If-Match vous permet d’annuler la modification si le prix a changé entre les deux appels (gestion des courses).

5️⃣ Gestion des multi‑companies – Pas de collision avec votre boutique principale

Situation	Solution API	Exemple
Une société supplémentaire (ex. boutique en ligne associée)	Créez un key avec le champ `company_id` = `99`.	`Authorization: Token retail-demo-002`
Accès en lecture‑seule à plusieurs compañías	Ajoutez `company_id` dans la query string (`?company=99`).	`/api/retail/stock?company=99`
Migrations	L’API accepte les identifiants legacy (`legacy_id`) pour faire le retrofit sans toucher aux tables `product` ou `order`.	`GET /api/retail/product/legacy/0015?api_token=…`

Resultat : Vos flux retail sont isolés par company_id. Même si vous avez 5 boutiques, aucun risque de perte de données liée à un mauvais namespace.

6️⃣ Prévenir les régressions – Checklist avant de passer en production

✅ Action	Description
1️⃣ Activer le mode “verbose”	Dans `Administration → Système → API → Debug`, activez le log `api_trace`. Vous obtenez un fichier `dolibarr.log` contenant chaque endpoint appelé.
2️⃣ Exécuter la suite de tests automatisés	Utilisez `phpunit` ou `behat` sur le répertoire `tests/api` du repo pour valider le comportement attendu.
3️⃣ Créer une branche de feature	`git checkout -b api-retail-2025` ; testez toutes les nouvelles routes avant de les merger.
4️⃣ Simuler le volume de trafic	`ab -n 500 -c 20 https://ma-boutique.fr/api/retail/stock` et surveillez `dolibarr.log` pour tout débordement.
5️⃣ Sauvegarder le snapshot	`pg_dump dolibarr > dump_avant_api.sql` – en cas de régression, il suffit de restaurer.
6️⃣ Déployer en canary sur 5 % du trafic	Utilisez un routeur Nginx avec `map $host $api_route { default ""; api-retail.example.com /api/retail; }` puis redirigez uniquement un sous‑groupe d’utilisateurs.
7️⃣ Déclencher un `git revert` en 1 clic	Si vous avez besoin d’un rollback instantané, le module “API” possède un bouton “Revert to stable”.

7️⃣ Bonnes pratiques pour rester “API‑first” sans bouleverser le core

Pratique	Explication
Versionner vos endpoints (`/v1/…` ou `/v2/…`)	Permet de garder les anciens appels fonctionnels tout en expérimentant de nouvelles fonctionnalités.
Utiliser les headers `Accept` et `Content-Type`	Évite les collisions de données ; vous pouvez recevoir du JSON ou du XML selon vos besoins.
Limiter le payload	Envoyez uniquement les champs nécessaires (`product_id`, `quantity`, `unit_price`) pour réduire le volume de traitement.
Seubre les réponses avec un code d’erreur uniformisé (`200 OK`, `400 Bad Request`, `401 Unauthorized`, `404 Not Found`, `422 Unprocessable Entity`)	Facilite la gestion d’erreurs côté client sans avoir à décortiquer du HTML ou du PHP raw.
Documenter chaque endpoint avec OpenAPI 3.0	Copiez le fichier `openapi.yaml` généré par Dolibarr (`/api/doc/openapi.yaml`) et partagez‑le avec vos équipes.

8️⃣ Exemple complet : synchroniser votre PDV et votre boutique en temps réel

Initialisation du client API (pseudocode en PHP)

<?php

require __DIR__.'/vendor/autoload.php';
$api = new DolibarrApi\Client([

    'base_uri'  => 'https://ma-boutique.fr/api/retail',

    'api_token' => 'retail-demo-001',

    'timeout'   => 5,

]);
// 1️⃣ Lire le catalogue à chaque démarrage du PDV

$catalogue = $api->get('/product?limit=500');
// 2️⃣ Boucle de discount dynamique (ex: 10% de remise le vendredi)

if (date('N') == 5) {

    foreach ($catalogue as &$p) {

        $p->price *= 0.9;   // remise 10%

    }

    $api->post('/product/update', ['body' => $catalogue]);

}
// 3️⃣ Notification de passage de stock à zéro

$api->post('/stock/alert', ['json' => ['product_id'=>27,'notify_email'=>'stock@alert.com']]);

Gestion du webhook côté serveur

location /webhook/retail {

    limit_req_zone $binary_remote_addr zone=api:10m rate=20r/s;

    limit_req zone=api burst=10 nodelay;
proxy_pass http://127.0.0.1:8080;

    proxy_set_header Host $host;

}

Résultat : Le système retail se synchronise event‑driven avec la boutique, sans besoin de poller chaque minute.

9️⃣ FAQ rapides – Réponses aux questions les plus fréquentes

Question	Réponse
Dois‑je modifier ma base de données pour activer l’API ?	Non. L’API crée ses propres tables (`api_keys`, `api_logs`). Aucun schéma existant n’est touché.
Puis‑je désactiver l’API sans perdre les commandes déjà traitées ?	Oui. Les transactions déjà en base restent rétro‑actives. Désactiver ne supprime que les endpoints.
Qu’est‑ce qui se passe si mon key est compromis ?	Révoquez‑le immédiatement via API → Authentification → Supprimer. Toutes les requêtes portant ce token seront rejetées.
L’API introduit‑elle des appels asynchrones qui peuvent ralentir le front‑office ?	Non, tant que vous n’utilisez pas les webhooks. Les appels sont stateless et timeout à 5 s par défaut.
Puis‑je limiter l’API à une IP uniquement ?	Oui, dans le profil du key vous pouvez spécifier une ou plusieurs IPs autorisées.
Est‑ce que les champs personnalisés (ex. “code_barcode”) sont exportables ?	Oui, ajoutez‑les dans le filtre `?_fields=code_barcode,price` dans votre requête.
Je veux tester en local sans interférer avec ma boutique réelle.	Lancez un conteneur Docker : `docker run -p 8080:80 dolibar/dolibarr:latest` ; activez l’API sur `http://localhost:8080/api/retail`.
Comment migrer mes scripts de paiement legacy vers l’API ?	Conservez l’URL d’origine (ex. `/payments.php`) pour le front‑office, mais redirigez les appels du backend vers `/api/retail/transaction` via un proxy PHP.

🔚 Conclusion – Profiter de l’API sans faire sauter le système

Activation ciblée : n’activez que les routes nécessaires (/api/retail/*).

Authentification fine : créez des clefs dédiées aux scenarios retail; ne les mélangez pas avec les comptes admin.

Versionning & canary : gardez les releases de l’API sous contrôle, testez en petits flux avant le déploiement complet.

Rollback simple : un bouton d’activation/désactivation ou un docker‑compose vous ramène à la situation initiale en moins de 30 secondes.

En suivant la checklist et les bonnes pratiques ci‑dessus, votre boutique retail peut bénéficier pleinement de l’API Dolibarr – stocks en temps réel, synchronisation multi‑store, paiements automatisés – sans jamais compromettre le fonctionnement actuel de votre installation.

💡 Prochaine étape : créez votre premier key retail‑demo‑001, testez le endpoint /product depuis votre console, puis intégrez‑le dans votre PDV. Vous serez bientôt capable de publier des soldes, de mettre à jour les prix et de prévoir des alertes de rupture sans jamais toucher au cœur de Dolibarr.

Bonne intégration !

Pour toute question supplémentaire ou besoin de support technique, n’hésitez pas à ouvrir un ticket sur le forum officiel de Dolibarr ou à contacter notre équipe via le canal Slack #dolibarr‑api‑retail.

API Dolibarr : retail FAQ sans casser l’existant

1️⃣ Pourquoi passer par l’API Dolibarr en mode retail ?

2️⃣ Installation & activation de l’API sans impacter le système existant

3️⃣ Authentification – Comment obtenir une clé API sans toucher aux comptes headers existants

4️⃣ Les appels les plus fréquents – Mini‑FAQ code

4.1 Lister les produits en stock (sans filtrer par défaut)

4.2 Déposer une vente depuis le PDV

4.3 Mettre à jour le prix d’un produit de façon non disruptive

5️⃣ Gestion des multi‑companies – Pas de collision avec votre boutique principale

6️⃣ Prévenir les régressions – Checklist avant de passer en production

7️⃣ Bonnes pratiques pour rester “API‑first” sans bouleverser le core

8️⃣ Exemple complet : synchroniser votre PDV et votre boutique en temps réel

9️⃣ FAQ rapides – Réponses aux questions les plus fréquentes

🔚 Conclusion – Profiter de l’API sans faire sauter le système

API Dolibarr : facturation électronique Guide pratique orienté ROI

Dolibarr et sauvegarde : erreurs fréquentes et solutions avec intégrations modernes

Diagnostiquer Dolibarr : emailing Framework sans casser l’existant

Dolibarr et la gestion des relations clients : Les meilleures pratiques à connaître

Optimisez votre entreprise avec Dolibarr et la gestion des relations clients

Comment automatiser votre entreprise avec Dolibarr modules ?

1️⃣ Pourquoi passer par l’API Dolibarr en mode retail ?

2️⃣ Installation & activation de l’API sans impacter le système existant

3️⃣ Authentification – Comment obtenir une clé API sans toucher aux comptes headers existants

4️⃣ Les appels les plus fréquents – Mini‑FAQ code

4.1 Lister les produits en stock (sans filtrer par défaut)

4.2 Déposer une vente depuis le PDV

4.3 Mettre à jour le prix d’un produit de façon non disruptive

5️⃣ Gestion des multi‑companies – Pas de collision avec votre boutique principale

6️⃣ Prévenir les régressions – Checklist avant de passer en production

7️⃣ Bonnes pratiques pour rester “API‑first” sans bouleverser le core

8️⃣ Exemple complet : synchroniser votre PDV et votre boutique en temps réel

9️⃣ FAQ rapides – Réponses aux questions les plus fréquentes

🔚 Conclusion – Profiter de l’API sans faire sauter le système

Publications similaires

1️⃣ Pourquoi passer par l’API Dolibarr en mode retail ?

3️⃣ Authentification – Comment obtenir une clé API sans toucher aux comptes headers existants

4️⃣ Les appels les plus fréquents – Mini‑FAQ code

4.1 Lister les produits en stock (sans filtrer par défaut)

4.2 Déposer une vente depuis le PDV

4.3 Mettre à jour le prix d’un produit de façon non disruptive

5️⃣ Gestion des multi‑companies – Pas de collision avec votre boutique principale

6️⃣ Prévenir les régressions – Checklist avant de passer en production

9️⃣ FAQ rapides – Réponses aux questions les plus fréquentes

🔚 Conclusion – Profiter de l’API sans faire sauter le système