API Dolibarr : formation FAQ pour réduire les erreurs

Introduction : Pourquoi une FAQ dédiée à l’API Dolibarr est indispensable

L’API REST de Dolibarr ERP/CRM est un outil puissant pour automatiser et intégrer vos processus métier. Cependant, son utilisation peut générer des erreurs frustrantes et coûteuses en temps si l’on ne maîtrise pas ses spécificités et ses pièges courants. Cet article se présente comme une foire aux questions (FAQ) de formation, conçue pour vous aider à anticiper, comprendre et résoudre les erreurs les plus fréquentes,transformant l’essai en une intégration fluide et robuste.

Partie 1 : Les Fondamentaux & Authentification

Q1 : Pourquoi est-ce que je reçois systématiquement une erreur 401 "Unauthorized" ?

  • Réponse & Solution : C’est l’erreur la plus commune. Elle signifie que vos identifiants (login/mot de passe d’un utilisateur Dolibarr) sont incorrects, OU que l’utilisateur n’a pas les droits suffisants pour accéder à la ressource demandée via l’API.

    • Action :

      1. Vérifiez que l’utilisateur est bien activé dans Dolibarr.

      2. Assurez-vous que les droits de l’utilisateur (Accès restreint par module) lui permettent d’accéder au module concerné (ex: Société, Produits, Factures).

      3. Pour les appels complexes, il est souvent préférable d’utiliser un compte API dédié (un utilisateur standard avec un mot de passe robuste et des droits strictement limités à ce qui est nécessaire).

    • Bonhomme : Jamais d’API key dans le code en clair. Utilisez des variables d’environnement.

Q2 : Mon token d’authentification (login/password) fonctionne pour /login, mais échoue sur /api/index.php/... ?

  • Réponse & Solution : L’endpoint de login (/api/login.php) et l’endpoint principal (/api/index.php) peuvent avoir des exigences légèrement différentes selon la version et la configuration. Vérifiez :

    1. L’URL de base de l’API est-elle correcte ? (Ex: https://votredolibarr.fr/api/index.php).

    2. Le format des credentials : utilisez les paramètres login et password en POST (ou en Basic Auth si configuré). Le format JSON {"login":"...","password":"..."} est souvent le plus fiable.

    3. Consultez les logs Dolibarr (/dolibarr/htdocs/var/logs/). Ils contiennent le détail des échecs d’authentification.

Partie 2 : Manipulation des Données (POST/PUT)

Q3 : J’ajoute une société (/societe) avec succès, mais les champs personnalisés (extrafields) sont vides.

  • Réponse & Solution : C’est un piège classique. Les champs supplémentaires (extrafields) ne sont pas dans le tableau array principal. Ils doivent être passés dans un sous-tableau nommé "array_options".

    • Exemple CORRECT : 
      {
      
  "nom": "MaSociété",
      
  "client": 1,
      
  "array_options": {
      
    "options_my_custom_field": "Valeur personnalisée"
      
  }
      
}

    • Action : Identifiez le code exact de votre champ personnalisé dans Dolibarr (Ex: options_mon_champ) via l’interface admin. Utilisez ce code comme clé dans array_options.

Q4 : Une mise à jour (PUT /societe/{id}) fonctionne partiellement, certains champs ne sont pas modifiés.

  • Réponse & Solution : L’API Dolibarr en mode PUT fonctionne souvent comme un "partial update" (PATCH) par défaut. Seuls les champs présents dans le payload sont mis à jour.

    • Problème courant : Vous ne spécifiez pas les champs que vous voulez laisser inchangés. Si un champ n’est pas dans le JSON, il peut être effacé ou ignoré selon la configuration.

    • Solution : Pour une mise à jour complète, il est plus sûr de faire d’abord un GET sur la ressource, récupérer le JSON complet, modifier les valeurs voulues, puis renvoyer le JSON entier en PUT. Pour une modification ciblée, assurez-vous que seuls les champs à modifier sont présents et que leur valeur est correctement formatée.

Q5 : Je reçois une erreur 400 "Bad Request" avec le message "Missing mandatory field" pour un champ que j’ai pourtant envoyé.

  • Réponse & Solution : Vérifiez scrupuleusement :

    1. La casse et le nom du champ : nom ≠ Nom ≠ name. Utilisez les noms exacts de l’API (documentation ou observation via l’onglet "REST API" dans l’interface Dolibarr).

    2. Le format des données : Un champ date doit être au format YYYY-MM-DD ou timestamp. Un champ tva (tva_tx) est un nombre décimal (ex: 20.000), pas une chaîne avec le symbole %.

    3. Les dépendances : Pour créer une ligne de facture, l’ID de la facture parente (fk_facture) est obligatoire. Pour créer un contact, l’ID de la société (fk_soc) est obligatoire. L’ordre de création (Société -> Contact -> Facture) est souvent critique.

Partie 3 : Lecture et Requêtes (GET)

Q6 : Mon appel GET sur /societe ne retourne pas toutes les sociétés, ou le filtrage ne fonctionne pas.

  • Réponse & Solution : La pagination et le filtrage sont gérés par des paramètres d’URL (query parameters).

    • Pagination : Utilisez limit (nombre d’éléments par page) et offset (décalage). Par défaut, il y a souvent une limite (ex: 100). Pour tout récupérer, il faut paginer.

    • Filtrage : Les filtres se font avec sortfield, sortorder, et des filtres comme mode=1 (clients), status=1 (actif). Consultez la documentation spécifique de l’objet (/societe, /product, etc.). Les filtres ne sont pas toujours uniformes.

    • Action : Testez vos filtres d’abord directement dans le navigateur ou Postman avec des paramètres simples (ex: ?limit=5&mode=1).

Partie 4 : Erreurs Système & Débogage

Q7 : L’erreur est vague (500 Internal Server Error). Comment savoir ce qui ne va pas ?

  • Réponse & Solution (LA CLÉ) : Activez le mode debug de Dolibarr !

    1. Dans conf.php (ou via l’admin), définissez $dolibarr_main_prod = 0;.

    2. Consultez les logs Dolibarr (htdocs/var/logs/dolibarr.log). C’est votre meilleur ami. Il indiquera le fichier, la ligne, et le message d’erreur PHP exact (ex: "Call to a member function fetch() on a non-object" signifie souvent un ID inexistant).

    3. Utilisez des outils comme Postman ou cURL avec l’option -v (verbose) pour voir les en-têtes de demande/réponse.

Q8 : J’ai une erreur "SQL error" ou "Duplicate entry".

  • Réponse & Solution :

    • "Duplicate entry" : Vous essayez de créer un enregistrement avec une référence (ref) ou un code (code) qui existe déjà. Pour les mises à jour, utilisez PUT avec l’ID, pas POST qui crée un nouvel enregistrement.

    • "SQL error" : Souvent lié à un format de données invalide (ex: une chaîne trop longue pour le champ, un nombre décimal mal formaté). Vérifiez la longueur max des champs dans la table Dolibarr correspondante.

Partie 5 : Bonnes Pratiques de Formation et Prévention

  1. Lisez la Documentation Officielle : La documentation de l’API est souvent éparse. Complétez-la en explorant l’interface Dolibarr : pour chaque objet (Société, Produit), l’onglet "REST API" montre souvent les endpoints et paramètres disponibles.

  2. Testez en Mode Lecture Seule : Avant tout développement POST/PUT/DELETE, testez exhaustivement vos GET pour bien comprendre la structure des données retournées.

  3. Utilisez un Outil comme Postman/Insomnia : Créez une collection pour votre projet Dolibarr. Cela permet de sauvegarder les requêtes, de gérer les variables d’environnement (URL, token) et de visualiser les réponses.

  4. Commencez Petit : Intégrez d’abord un objet simple (ex: mise à jour du nom d’une société existante) avant de vous attaquer à des objets complexes lignes de factures avec des taxes et des produits.

  5. Imposez une Vérification des Retours : Votre code doit toujours vérifier le code HTTP de la réponse (200, 201, 400, 404, 500) et toujours parser et journaliser le corps de la réponse en cas d’erreur. Le message dans la réponse JSON est souvent plus parlant que le code HTTP seul.

  6. Connaissez les Limites de Dolibarr : L’API est une surcouche. Elle ne peut pas tout faire. Par exemple, la validation métier complexe (règles de gestion spécifiques) peut échouer si elle n’est pas déclenchée correctement via l’API. Dans le doute, faites l’action manuellement dans l’interface Dolibarr et observez ce qui se passe.

Conclusion

Réduire les erreurs avec l’API Dolibarr ne relève pas de la magie, mais d’une méthodologie rigoureuse :

  1. Comprendre les prérequis (authentification, droits).

  2. Maîtriser la structure des données (champs obligatoires, format, extrafields).

  3. Diagnostiquer avec les logs et le mode debug.

  4. Adopter les bonnes pratiques (lecture préalable, tests incrémentaux, gestion des erreurs).

Cette FAQ est un point de départ. Votre meilleure formation restera la pratique éclairée : testez, échouez, consultez les logs, et ajustez votre compréhension des données et des règles métier qui se cachent derrière chaque endpoint. En faisant de l’API Dolibarr un allié compris et non un adversaire obscur, vous gagnerez en productivité et en fiabilité dans vos intégrations.

Publications similaires