Importer des données dans Dolibarr depuis un fichier CSV ou Excel

Dolibarr sait reprendre vos clients, contacts, produits, stocks ou prix d’achat depuis un tableur, grâce à un assistant en quatre étapes. Attention : il écrit directement dans les tables. Il ne fait donc pas tout ce que font les écrans de saisie (pas de mouvement de stock, pas d’historique de prix), et il est strict sur le format des fichiers.

Ce guide suit l’assistant de Dolibarr 24.0.2 avec de vrais fichiers CSV et Excel, importés le 14 octobre 2026 sur une instance de test, dont une vingtaine d’erreurs provoquées exprès pour relever les messages exacts.

Où se trouve l’assistant

Menu Outils › Importations / Exportations › Nouvel import. Si le menu n’apparaît pas, activez le module Imports de données dans Accueil › Configuration › Modules/Applications.

L’assistant tient en quatre onglets :

1. Étape 1 : le lot de données à importer (tiers, produits…). Seuls les lots des modules activés sont proposés : activez d’abord Produits, Stock ou Fournisseurs si vous en avez besoin.
2. Étape 2 : le fichier, ajouté avec Ajouter fichier puis choisi avec la flèche à droite.
3. Étape 3 : la correspondance entre les colonnes du fichier et les champs de Dolibarr.
4. Étape 4 : les options, puis Lancer la simulation d’import, et enfin Importer les données.

Les lots les plus utilisés, avec leur libellé exact à l’étape 1 :

Et les relevés bancaires ?

L’assistant de Dolibarr 24.0.2 n’en importe pas. Avec le module Banques activé, la liste ne propose, côté banque, que les coordonnées bancaires des tiers : aucun lot pour les écritures d’un relevé. Pour importer un relevé, il faut donc un développement ou un module complémentaire ; nous n’en avons testé aucun.

L’ordre à respecter

Un fichier désigne souvent des fiches créées par un autre : un contact donne le nom de son tiers, une ligne de stock la référence du produit et celle de l’entrepôt. Si la fiche n’existe pas encore, la ligne est refusée. D’où l’ordre que nous avons suivi, sans erreur :

1. les tiers ;
2. les contacts ;
3. les produits ;
4. les entrepôts ;
5. les stocks ;
6. les prix fournisseurs ;
7. les catégories.

Partir du fichier modèle

À l’étape 2, Dolibarr propose Télécharger un fichier d’exemple, en CSV ou en Excel. Ce fichier contient :

• une ligne d’en-têtes dans votre langue, avec le code du champ entre parenthèses : Nom du tiers* (s.nom), Code pays (s.fk_pays)… L’astérisque marque les champs obligatoires ;
• une deuxième ligne d’exemple, qui décrit ce qui est attendu (0 (closed) / 1 (active), etc.).

Le CSV utilise la virgule comme séparateur et l’encodage UTF-8.

Gardez les en-têtes tels quels. À l’étape 3, Dolibarr reconnaît le code entre parenthèses (ou un libellé identique au sien, comme Ville) et remplit seul la correspondance : dans notre test, les 14 colonnes d’un fichier de tiers ont été associées sans rien toucher, y compris un attribut supplémentaire. Avec des en-têtes à vous (« Raison sociale », « Est client »), il faut tout associer à la main.

Supprimez ensuite la ligne d’exemple et les colonnes inutiles, puis remplissez vos données. La ligne d’en-têtes ne gêne pas : à l’étape 4, Importer les lignes à la position (de - à) commence à 2 par défaut.

Étape par étape, avec un fichier de tiers

Étape 2. Le fichier ne doit pas dépasser la limite d’envoi de Dolibarr, 2 048 Ko après une installation neuve (l’infobulle à côté du bouton l’indique). Au-delà, l’ajout échoue avec « Erreur, l’enregistrement du fichier a échoué. ». La limite se change dans Accueil › Configuration › Sécurité, onglet Fichiers (voir notre guide d’installation avec Docker, qui détaille ce réglage).

Étape 3. Vérifiez d’abord la ligne Options du fichier CSV : le Séparateur de champs retenu doit être celui de votre fichier (voir plus bas, c’est la première cause d’échec). Puis contrôlez chaque liste déroulante. Sous le tableau, une note indique soit « Tous les champs cibles qui ont besoin d’une valeur obligatoire sont affectés. », soit « Certains champs cibles obligatoires n’ont pas de correspondance dans le fichier source » suivi de leur nom.

Cette note n’est qu’un avertissement : l’import passe quand même. Dans notre test, un tiers importé sans les colonnes Client* et Fournisseur* a été créé ni client ni fournisseur. Lisez-la.

Étape 4. Trois réglages : les lignes à importer, la Clé (colonne) pour la mise à jour (voir plus bas) et le Mode d’importation. Puis Lancer la simulation d’import.

La simulation fait réellement l’import, puis l’annule : rien ne reste en base (nous avons compté les tiers avant et après). Si tout va bien, elle affiche « Résultat de la simulation : Aucune erreur » et le nombre de lignes qui seront insérées et mises à jour. Sinon, elle liste les erreurs ligne par ligne, et le bouton Importer les données est grisé : « Vous devez d’abord corriger toutes les erreurs avant de pouvoir lancer l’import définitif. »

C’est tout ou rien : une seule ligne en erreur bloque tout le fichier. Corrigez le fichier, ajoutez-le de nouveau et relancez la simulation.

L’import. Importer les données affiche le nombre de lignes insérées et mises à jour, et un numéro d’import (par exemple 20261014131140), enregistré dans le champ import_key de chaque fiche créée ou modifiée. Notez-le : l’assistant n’a pas de bouton pour annuler un import, et ce numéro permet de retrouver ensuite, en base, ce qu’il a écrit. Faites une sauvegarde avant un gros import : Sauvegarder et restaurer Dolibarr.

Pour le fichier suivant, repartez de Nouvel import. Dans notre test, revenir directement à l’étape 2 pour choisir un autre fichier a fait réappliquer la correspondance du fichier précédent, avec des erreurs absurdes à la clé.

Nouveau en 24 : le mode d’importation

Dolibarr 24 ajoute à l’étape 4 un Mode d’importation :

• Mode sécurisé (plus lent), le réglage par défaut : Dolibarr déclenche, pour chaque ligne, les actions automatiques que ferait une saisie à l’écran. Avec le module Agenda, notre import de 5 tiers a créé 5 événements « Tiers … créé », et une mise à jour, des événements « Tiers … modifié » ;
• Mode rapide (plus rapide) : aucune action automatique ligne par ligne. Notre import de 2 tiers dans ce mode n’a créé aucun événement.

La simulation, elle, ne déclenche jamais ces actions. Gardez le mode sécurisé, sauf pour un très gros fichier dont vous ne voulez ni événements ni notifications.

Mettre à jour des fiches au lieu d’en créer

Sans clé, chaque ligne crée une fiche. Réimporter le même fichier crée donc des doublons : dans notre test, les 5 tiers ont été créés une seconde fois (et ceux dont le code client valait auto ont reçu un nouveau code).

Pour modifier des fiches existantes, choisissez à l’étape 4 une Clé (colonne) pour la mise à jour. Pour chaque ligne, Dolibarr cherche une fiche ayant la même valeur :

• une fiche trouvée : elle est mise à jour ;
• aucune : la ligne crée une nouvelle fiche (dans notre test, 2 tiers mis à jour, 1 créé) ;
• plusieurs : erreur « Plusieurs enregistrements ont été trouvés avec ces filtres: ThirdPartyName = ‘Atelier Wendling’, entity IN (1) ».

Les clés proposées dépendent du lot : pour les tiers, Nom du tiers, Code postal, Email, Code client, Code fournisseur, les codes comptables et les identifiants professionnels (SIREN, SIRET, NAF…) ; pour les produits, la Réf. ; pour les stocks, le Produit et l’Entrepôt. Prenez une valeur unique, comme le code client, le SIRET ou la référence : un nom peut exister deux fois.

Deux précautions, vérifiées :

• Toutes les colonnes associées sont réécrites, y compris les cellules vides. Nous avons mis à jour le téléphone d’un tiers avec un fichier dont la colonne Email était vide : son adresse email a été effacée. Les colonnes absentes du fichier, elles, ne sont pas touchées (l’attribut supplémentaire « Secteur » est resté en place). Pour une mise à jour, ne mettez dans le fichier que la clé et les colonnes à changer.
• La colonne clé doit être associée et remplie, sinon la simulation répond « You request to search duplicates on field nom but no value was provided for this field on this line. » (en anglais, même dans l’interface française).

Si un import a déjà créé des doublons de tiers ou de contacts, notre module Détection de doublons les retrouve et propose de les fusionner.

Les erreurs fréquentes, avec le message exact

Le séparateur

Dolibarr part de la virgule. Si la première ligne ne contient aucune virgule mais plus de deux points-virgules, il bascule seul sur le point-virgule. Conséquence vérifiée : un fichier au point-virgule de trois colonnes ou moins (un fichier de stock, typiquement) n’est pas reconnu, et tout arrive dans une seule colonne.

Le remède : à l’étape 3, tapez ; dans Séparateur de champs, cliquez Modifier, puis refaites la correspondance, que Dolibarr a vidée (ou laissée incomplète). Pour un fichier séparé par des tabulations, tapez \t. Le réglage par défaut se change dans la configuration du module (roue crantée de Imports de données) : « Séparateur de caractères CSV (Par défaut) ».

Autre cas : dans un fichier à la virgule, une adresse comme « Zone artisanale, bâtiment B » sans guillemets décale toutes les colonnes suivantes. Le message ne parle alors que de la conséquence : « Champ H: ‘Strasbourg’ n’est pas une valeur disponible dans le champ code de la table Pays ».

Un signe qui ne trompe pas : « Résultat de la simulation : Aucune erreur » avec « Nombre de lignes qui seront insérées : 0 ». Aucune colonne n’est associée.

L’encodage

Enregistrez le CSV en UTF-8. Nous avons importé un fichier encodé en Windows-1252 : les accents passent (« Hôtel à l’Étoile »), mais le symbole €, le « œ », l’apostrophe typographique ’ et le tiret – deviennent des caractères invisibles. « Société Œnologique d’Alsace » est devenu « Société nologique dAlsace », sans aucune erreur à la simulation. Un fichier UTF-8 avec BOM (une marque invisible en tête de fichier) est passé sans problème, tout comme un fichier en ISO-8859-1 sans ces caractères.

Les dates

Format AAAA-MM-JJ. Une date française est refusée :

Champ G: '14/10/2026' ne respecte pas la règle ^[0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9]( [0-9][0-9]:[0-9][0-9]:[0-9][0-9])?$

« Champ G » désigne la colonne G de votre fichier.

Les nombres

Point décimal, sans espace : 12.50. Dans un prix de produit, 12,50 est refusé avec « Data truncated for column ‘price’ at row 1 ». Certains champs convertissent la virgule (le capital d’un tiers : 12 500,50 est devenu 12500,5), d’autres non : ne comptez pas dessus.

Les champs obligatoires et les valeurs codées

Les valeurs attendues :

• Client : 0 (ni client ni prospect), 1 (client), 2 (prospect), 3 (client et prospect) ; Fournisseur : 0 ou 1 ; État : 1 (actif) ou 0 (clos) ;
• Code pays : le code ISO, FR, DE, BE ;
• Civilité d’un contact : le code du dictionnaire, MR, MME, MLE, MTRE ou DR ;
• Code client ou Code fournisseur : auto pour que Dolibarr attribue le numéro suivant (nos tiers ont reçu CU2610-00001, CU2610-00002… avec la numérotation par défaut). Cellule vide ou colonne absente : pas de code du tout.

Les fiches désignées par leur nom ou leur référence

Un contact est rattaché à son tiers par le nom exact du tiers. Une faute de frappe donne « Champ A: ‘Boulangerie Kiefer’ n’est pas une référence existante comme Tiers ». Un nom présent deux fois (un doublon) donne « Plusieurs enregistrements trouvés lors de la recherche à partir de la référence Boulangerie Kieffer . Aucun moyen de savoir quel ID utiliser. »

Une référence faite uniquement de chiffres est lue comme un identifiant interne. Notre produit de référence 1001 (identifiant interne 9) n’a pas pu recevoir de stock : Dolibarr cherchait le produit n° 1001, d’où « Cannot add or update a child row: a foreign key constraint fails ». Écrire ref:1001 dans la colonne a réglé le problème. D’après le code, la règle vaut pour toutes les colonnes qui désignent une autre fiche (produit, tiers, entrepôt, catégorie).

Les attributs supplémentaires

Les attributs supplémentaires (extrafields) apparaissent comme colonnes à la fin de la liste, sous leur libellé : Secteur (extra.secteur) dans le fichier modèle. Dans notre test, ils ont été importés avec les tiers, sans réglage particulier.

Les fichiers Excel (.xlsx)

L’assistant lit directement le format Excel 2007 (.xlsx). Avec un fichier enregistré par LibreOffice, nous avons constaté :

• une formule est lue telle quelle, pas son résultat : « Incorrect double value: ‘=1.5*2’ for column … price ». Remplacez les formules par leurs valeurs avant l’import ;
• une cellule date arrive sous la forme 2026-10-01 00:00:00 : acceptée pour la date de création d’un tiers, refusée pour celle d’un produit (la règle n’y admet pas l’heure). Mettez les dates en texte, au format AAAA-MM-JJ ;
• un code postal saisi comme nombre perd son zéro : 06000 est devenu 6000. Mettez la colonne au format texte.

D’après le code, seule la feuille active du classeur est lue.

Produits : le prix TTC et l’historique ne suivent pas

L’import écrit le prix tel quel, sans le recalculer :

• avec seulement un Prix de vente HT (1,20), le prix TTC reste à 0 en base, et l’historique des prix est vide. Dans notre test, seule l’ouverture de l’onglet Prix de vente du produit a recalculé le TTC et créé la première ligne d’historique (ouvrir la fiche ou la liste des produits n’a rien changé) ; un produit dont personne n’ouvre cet onglet garde un prix TTC à 0 ;
• avec les deux colonnes HT et TTC, les deux valeurs sont enregistrées telles quelles : à vous de les rendre cohérentes ;
• mettre à jour un prix par import (clé Réf.) a changé le prix HT (1,201,50), mais le prix TTC est resté à 1,44 et l’historique n’a pas bougé. Pour changer quelques prix, passez par l’onglet Prix de vente du produit.

La colonne PriceBaseType* est obligatoire : HT ou TTC.

Stocks : des quantités, pas des mouvements

Le lot Stocks et emplacements (entrepôts) des produits écrit directement la quantité par entrepôt. Dans notre test, 40 cahiers à Strasbourg et 15 à Colmar : la fiche affiche bien 55 en stock, mais « Dernier mouvement : Aucun », la liste des mouvements est vide, et le prix moyen pondéré (PMP) n’est pas calculé.

Réimporter le même produit dans le même entrepôt échoue (« Duplicate entry ‘6-3’ for key ‘uk_product_stock’ ») ; avec les deux clés Produit et Entrepôt, la quantité est remplacée (200180), pas ajoutée.

Pour un stock de départ dont vous voulez garder la trace, préférez l’inventaire, qui crée de vrais mouvements : voir Saisir le stock initial.

Catégories : la liste s’importe, les liens non (24.0.2)

Le lot Liste des tags/catégories fonctionne. Le Type vaut 0 pour les produits, 1 pour les fournisseurs, 2 pour les clients/prospects (le fichier modèle donne la liste complète). Pour le Tag/catégorie parent, mettez 0 pour une catégorie de premier niveau : vide, la ligne est refusée (« Column ‘fk_parent’ cannot be null »). Une sous-catégorie peut désigner son parent par son libellé, même créé plus haut dans le même fichier.

En revanche, en 24.0.2, les liens entre catégories et fiches ne s’importent pas. Nous avons testé les produits, les clients et les fournisseurs : la simulation affiche « Dolibarr a détecté une erreur technique » et refuse chaque ligne, même avec des valeurs justes. La cause est dans la vérification que fait l’assistant (requête mal formée) ; le code est identique dans la branche 24.0 au 14/10/2026.

Le contournement testé : dans la liste des produits, cochez les produits, choisissez l’action Affecter un tag/catégorie, sélectionnez la catégorie, puis Valider : « 2 enregistrements modifiés ». La liste des tiers propose la même action (non testée ici).

Un dernier piège : les profils d’import

À l’étape 3, l’assistant permet d’enregistrer la correspondance comme profil d’import, pour la réutiliser. L’enregistrement fonctionne, mais en 24.0.2, choisir le profil puis cliquer Appliquer ne change rien : les listes restent vides (le formulaire envoie l’étape 3, alors que le code ne traite le profil qu’à l’étape 4). Des en-têtes repris du fichier modèle font le même travail, et fonctionnent.

En résumé

• Partez du fichier modèle et gardez ses en-têtes : la correspondance se fait seule.
• Importez dans l’ordre : tiers, contacts, produits, entrepôts, stocks, prix fournisseurs, catégories.
• CSV en UTF-8, dates en AAAA-MM-JJ, nombres avec un point, pas de formules.
• Au point-virgule avec trois colonnes ou moins : tapez ; vous-même à l’étape 3.
• Lisez la simulation : une seule erreur bloque tout le fichier.
• Pour modifier des fiches, une clé unique et seulement les colonnes à changer : une cellule vide efface.
• Stocks et prix : l’import ne crée ni mouvements ni historique ; vérifiez le prix TTC.
• Catégories : liez-les par l’action de masse des listes, pas par l’import, en 24.0.2.

Si un import refuse de passer malgré tout, le diagnostic à 90 € consiste à regarder votre instance et votre fichier avec vous pendant une heure, puis à vous remettre par écrit ce qui bloque et ce que coûterait la correction.