Aller au contenu principal

EMSmartFill — Données clients belges fiables pour Dolibarr

EMSmartFill connecte Dolibarr au registre officiel BCE/KBO (Banque-Carrefour des Entreprises) via l'API cbeapi.be. Le module vérifie vos tiers belges, pré-remplit automatiquement leurs fiches, et corrige en masse les numéros de TVA mal formatés — pour 10 pays de l'Union européenne.

Introduction

Pourquoi EMSmartFill ?

Au fil du temps, votre base de tiers Dolibarr accumule des erreurs : numéros de TVA mal formatés (be 0123.456.789, 0987654321 sans préfixe), adresses périmées, formes juridiques manquantes, doublons partiels. Pour une PME belge, c'est du temps perdu sur les factures, des rejets Peppol, et bientôt un blocage légal quand la facturation électronique B2B deviendra obligatoire en 2026.

EMSmartFill récupère les informations directement depuis la source officielle belge et fiabilise votre base en quelques clics.

Pourquoi pas le bouton TVA natif de Dolibarr ?

Dolibarr dispose d'un bouton « Vérifier » natif sur les fiches tiers, mais pour la Belgique il interroge VIES (le service européen) qui ne renvoie que la validité — pas d'adresse, pas de nom officiel, pas de forme juridique. EMSmartFill remplace ce bouton par une version qui interroge le registre BCE/KBO et ramène toutes les données utiles.

1. Installation

Prérequis

  • Version récente de Dolibarr
  • PHP ≥ 8.0
  • Module standard Dolibarr Sociétés/Tiers activé
  • Accès administrateur à votre Dolibarr

Étapes

  1. Téléchargez le fichier ZIP du module depuis votre commande Dolistore (ou depuis www.e-dem.com).
  2. Connectez-vous à Dolibarr en tant qu'administrateur.
  3. Allez dans Configuration → Modules/Applications.
  4. Cliquez sur Déployer/installer un module externe en haut à droite.
  5. Sélectionnez le fichier ZIP module_emsmartfill-X.Y.Z.zip et validez.
  6. Le module apparaît dans la liste. Activez-le en cliquant sur l'interrupteur.

Note pour les hébergements particuliers (Cloudron, Plesk, cPanel) : si votre hébergement utilise un DocumentRoot non-standard, le module détecte automatiquement le chemin grâce au pattern d'inclusion main.inc.php officiel. Aucune configuration spéciale requise.

Vérification post-installation

Après activation, vous devez voir :

  • Un nouveau lien EMSmartFill dans le menu de configuration des modules
  • Une nouvelle icône d'admin (Configuration → Modules → EMSmartFill)
  • Sur chaque fiche de tiers belge avec un numéro de TVA, un bouton « Vérifier avec BCE »

2. Création du compte cbeapi.be

EMSmartFill utilise l'API cbeapi.be pour interroger le registre BCE/KBO. Vous devez créer un compte gratuit chez eux.

Pourquoi cbeapi.be et pas le BCE directement ?

Le BCE/KBO ne propose pas d'API publique grand public. cbeapi.be est un service belge tiers qui agrège, met en cache et expose les données du registre via une API REST simple. 2 500 requêtes par jour gratuites à l'inscription, ce qui couvre largement les besoins d'une PME standard.

Étapes

  1. Rendez-vous sur https://cbeapi.be
  2. Créez un compte (email + mot de passe)
  3. Dans votre tableau de bord, copiez la clé API (token Bearer)
  4. Notez les limites de votre forfait (2 500 req/jour pour le gratuit)

Volumes typiques

Cas d'usage Requêtes/jour estimées
PME avec quelques nouveaux tiers/semaine < 10/jour
Vérification mensuelle en masse (500 tiers) 500 (1 jour/mois)
Comptable avec 4 000 tiers vérifiés tous les 6 mois 4 000 répartis sur 2 jours
Vérification automatique sur création de tiers 1 par création

Si vous dépassez régulièrement 2 500/jour, regardez les forfaits payants directement sur cbeapi.be.

3. Configuration du module

Saisie de la clé API

  1. Allez dans Configuration → Modules/Applications → EMSmartFill → Configurer
  2. Dans l'onglet Configuration, vous voyez :
    • Clé API (champ masqué — le placeholder affiche les 4 derniers caractères de la clé existante si déjà saisie)
    • URL de l'API : valeur par défaut https://cbeapi.be/api/v1 (à ne pas modifier sauf cas spécial)
    • Timeout : par défaut 10 secondes — augmentez à 20-30 s si vous êtes sur un hébergement lent
  3. Collez votre clé API et cliquez sur Tester la connexion.
  4. Si la connexion réussit, le module affiche les données d'un tiers de test.

Si le test échoue, voyez la section Dépannage.

Options de comportement

Onglet Options :

Option Effet Recommandation
Vérification automatique Vérifie le tiers automatiquement à sa création ou modification Désactivé par défaut. Activez si vous voulez du « zéro clic ».
Pré-remplissage automatique Pré-remplit automatiquement après une vérification réussie Désactivé par défaut. À combiner avec la vérification auto. Attention : écrase silencieusement les données saisies à la main.
Logguer les réponses API Stocke la réponse JSON complète de chaque appel dans le journal d'audit Utile en cas de support. Coûte un peu de stockage.

4. Vérifier un tiers

Cas d'usage de base

  1. Ouvrez une fiche de tiers belge (exemple : un tiers que vous venez de créer avec juste le numéro de TVA renseigné BE0718623213).
  2. Cliquez sur le bouton « Vérifier avec BCE » en haut à droite de la fiche.
  3. Une boîte de dialogue de confirmation apparaît. Cliquez Oui.
  4. Le module interroge cbeapi.be et affiche un encadré avec les données BCE récupérées : nom, adresse, code postal, ville, pays, numéro d'entreprise, statut, forme juridique, NACE...

À ce stade, rien n'est encore modifié dans Dolibarr. C'est juste un affichage des données disponibles.

États visuels du bouton

Couleur Signification
Bleu / neutre Tiers jamais vérifié
🟢 Vert « BCE Vérifié » Vérifié avec succès, données disponibles
🟠 Orange Tiers introuvable dans le BCE (numéro de TVA erroné ou société cessée)
🔴 Rouge Erreur API (clé invalide, quota dépassé, problème réseau)
Grisé TVA absente ou non belge

Numéros de TVA mal formatés

EMSmartFill normalise automatiquement les variantes courantes avant l'appel API. Les formats suivants sont tous acceptés et donnent le même résultat :

  • BE0718623213
  • be 0718.623.213
  • BE 0718 623 213
  • BE-0718-623-213
  • 0718623213 (uniquement si le pays du tiers est défini comme Belgique)

5. Pré-remplissage par champ

Après une vérification, vous voyez l'encadré BCE avec un tableau comparatif champ par champ :

☑ Champ Valeur actuelle Valeur BCE Statut
☑ nom ACME SRL E-dem 🟠 Différent
☑ address (vide) Les Bôles 60 🟡 À remplir
☑ zip (vide) 5350 🟡 À remplir
☑ town Bruxelles Ohey 🟠 Différent
☐ country_id Belgique Belgique 🟢 Identique

Statuts possibles

  • 🟢 Identique — pas de différence, pas de checkbox (rien à faire)
  • 🟡 Vide (sera rempli) — Dolibarr est vide, BCE a une valeur → coché par défaut
  • 🟠 Différent — les deux ont une valeur mais différente → coché par défaut, avec attention
  • ⚪ Absent du BCE — Dolibarr a une valeur, BCE pas → jamais coché (on ne supprime jamais)

Raccourcis

  • Sélectionner toutes les différences — coche tous les rouges/jaunes en une fois
  • Sélectionner uniquement les champs vides — pour ceux qui ne veulent JAMAIS écraser une valeur saisie à la main, ne coche que les jaunes

Appliquer

Cliquez sur Appliquer la sélection : Dolibarr met à jour uniquement les champs cochés, et conserve tout le reste tel quel. Un message confirme le nombre de champs mis à jour.

6. Vérification en masse

Cas d'usage

Vous avez 500 tiers belges dans votre base. Vous voulez tous les vérifier d'un coup pour identifier ceux dont les données ont changé.

Étapes

  1. Allez dans Configuration → Modules → EMSmartFill → Vérification en masse
  2. Choisissez votre filtre d'éligibilité :
    • Tous les tiers avec TVA — tous les tiers belges, peu importe l'état
    • Jamais vérifiés — uniquement ceux qui n'ont pas encore de date de vérification
    • Non vérifiés depuis — saisissez une date (au format YYYY-MM-DD)
    • Réessayer les erreurs — uniquement les tiers en statut error
    • Réessayer les non-trouvés — uniquement les tiers en statut not_found
  3. Cochez les types de tiers à inclure : Clients / Fournisseurs / Prospects
  4. Ajustez si nécessaire :
    • Throttle (ms entre appels API) : 1 000 ms par défaut. Si l'API vous limite, montez à 2 000-5 000 ms.
    • Taille du lot (tiers par tick AJAX) : 5 par défaut. Si votre réseau est rapide, vous pouvez monter à 10-20.
  5. Cliquez Lancer la vérification.

Suivi en temps réel

Le module affiche une barre de progression qui s'actualise toutes les 1-2 secondes via AJAX. Vous voyez en permanence le pourcentage traité, les compteurs Succès / Non trouvés / Erreurs, et les boutons Pause / Reprendre / Abandonner.

Vous pouvez fermer l'onglet et revenir plus tard — l'état est persistant en base de données.

Reprise après interruption

Si votre navigateur crash, votre PC redémarre, ou votre session expire : au prochain chargement de la page Vérification en masse, le module détecte automatiquement le run interrompu et vous propose de Reprendre (continuer là où il en était) ou Abandonner (clôturer).

Rapport détaillé

Une fois le run terminé, cliquez Voir le rapport détaillé pour avoir le résumé global avec dates de début/fin, le tableau complet des tiers traités (avec filtres par statut), et un bouton œil 👁️ par ligne pour ouvrir directement la fiche du tiers concerné.

7. Normalisation TVA en masse

Onglet « Analyse »

Allez dans EMSmartFill → Normalisation TVA en masse, onglet Analyse. Cliquez Lancer l'analyse. Le module scanne tous vos tiers et les répartit en 4 catégories :

  • ✅ Déjà propres — TVA bien formatée, rien à faire
  • 🔵 Auto-correction possible — espaces, points, tirets, casse à corriger, ou préfixe pays à ajouter (si le pays du tiers est connu)
  • 🟡 Revue manuelle requise — cas ambigus : longueur incorrecte, pays inconnu, format douteux
  • 🔴 Rejetés — vides ou pays non supporté (hors UE)

Onglet « Auto-corrections »

Affiche le détail de la catégorie 🔵. Tableau avec : tiers (lien vers la fiche), pays, TVA actuelle (ex : be 0123.456.789), TVA proposée (ex : BE0123456789), raison de la correction.

Toutes les lignes sont cochées par défaut. Décochez celles que vous ne voulez pas modifier, puis cliquez Appliquer la sélection. Une boîte de dialogue confirme avant exécution. Les corrections sont loggées dans le journal d'audit (avant/après).

Onglet « Revue manuelle »

Pour les cas 🟡 que le module ne peut pas trancher tout seul (TVA invalide, pays inconnu, format douteux), vous voyez chaque cas un par un avec 3 actions :

  • Appliquer — saisissez la valeur correcte et validez
  • Passer — passer au suivant, vous traiterez plus tard
  • Rejeter (laisser tel quel) — la TVA est OK comme ça, ne plus signaler ce tiers

Pays supportés

Pays Format
🇧🇪 Belgique BE0123456789 (10 chiffres)
🇫🇷 France FR12345678901 (2 lettres ou chiffres + 9 chiffres)
🇱🇺 Luxembourg LU12345678 (8 chiffres)
🇳🇱 Pays-Bas NL123456789B01 (9 chiffres + B + 2 chiffres)
🇩🇪 Allemagne DE123456789 (9 chiffres)
🇪🇸 Espagne ES?1234567? (lettre/chiffre + 7 chiffres + lettre/chiffre)
🇮🇹 Italie IT12345678901 (11 chiffres)
🇵🇹 Portugal PT123456789 (9 chiffres)
🇦🇹 Autriche ATU12345678 (U + 8 chiffres)
🇮🇪 Irlande IE12345678 ou IE123456789 (variable)

8. Automatisation

Si vous voulez du « zéro clic », activez les triggers dans l'onglet Options.

Vérification automatique

Quand activée : chaque fois qu'un tiers belge est créé ou modifié avec un numéro de TVA, le module appelle automatiquement l'API BCE et stocke le résultat dans les champs extra (date + statut).

Impact API : si vous créez 100 tiers par jour, vous consommez 100 requêtes par jour. À surveiller si vous êtes proche du quota 2 500/jour.

Pré-remplissage automatique

Quand activée (et que la vérification auto est aussi active) : après vérification, le module applique automatiquement TOUS les champs BCE sur le tiers, sans demander confirmation.

À utiliser avec précaution : vous perdez le contrôle par champ. Si vos vendeurs ont saisi des informations spécifiques (dénomination commerciale différente de la légale par exemple), elles seront écrasées. Recommandation : laissez désactivé sauf si vous savez exactement ce que vous faites.

9. Journal d'audit et debug

Page Debug

EMSmartFill → Debug affiche un tableau de toutes les actions effectuées (date, utilisateur, type d'action, tiers, TVA, statut HTTP, résultat). Cliquez sur Voir pour déplier la réponse API brute (JSON formaté).

Types d'actions tracés :

  • verify_vat — vérification manuelle d'un tiers
  • prefill — pré-remplissage appliqué
  • search_vat, search_name — recherche dans le BCE
  • bulk_verify — un item d'un run en masse
  • trigger_auto — déclenché par le trigger automatique
  • vat_normalize — correction TVA depuis la page de normalisation

Page Maintenance

EMSmartFill → Maintenance vérifie l'intégrité de la base (prérequis système, modules requis, structure des tables, champs extra, test de connexion API) et propose des actions de réparation. Si quelque chose est cassé (table manquante, champ extra effacé...), le bouton Réparer la base recrée les éléments manquants sans perdre vos données existantes.

10. FAQ

Mon tiers n'est pas trouvé alors que la société existe bien

Trois causes possibles :

  1. Le numéro de TVA contient une faute de frappe — vérifiez sur le site officiel du BCE
  2. La société a été cessée récemment — le BCE conserve le numéro mais le marque inactif
  3. Quirk historique : certains très anciens numéros de TVA (commençant par 1 au lieu de 0) sont valides mais rares — le module les accepte

Je veux vérifier un tiers belge SANS écraser ses données

C'est exactement le cas d'usage de base : cliquez Vérifier avec BCE → vous voyez les données → fermez l'encadré sans cliquer Appliquer. Aucune donnée n'est modifiée. Le bouton passe juste en vert « BCE Vérifié » et la date est enregistrée.

Le module modifie le numéro d'entreprise (Id. prof. 1)

Lors d'un pré-remplissage, le champ Id. prof. 1 (N° professionnel) est rempli avec le numéro d'entreprise belge à 10 chiffres (sans préfixe BE) : 0718623213 par exemple. C'est le format légal correct attendu par Dolibarr pour la Belgique. Le numéro de TVA (tva_intra) garde son préfixe BE : BE0718623213.

Peut-on désactiver le bouton « Vérifier avec BCE » pour certains utilisateurs ?

Oui. Allez dans Utilisateurs et groupes → Permissions et retirez la permission emsmartfill / verify aux utilisateurs concernés. Le bouton n'apparaîtra plus pour eux.

Que se passe-t-il quand je dépasse le quota gratuit cbeapi.be ?

L'API renvoie un code HTTP 429 (Too Many Requests). EMSmartFill réessaie automatiquement une fois après 5 secondes. Si l'erreur persiste, le tiers est marqué en statut error et vous pouvez relancer le lendemain ou souscrire à un forfait payant.

Compatible Multicompany ?

Oui. La clé API peut être globale ou par entité. Les logs sont isolés par entité. Testé avec et sans le module activé.

Compatible avec emPeppol ?

Oui, parfaitement complémentaire. EMSmartFill nettoie la base de tiers ; emPeppol envoie les factures Peppol. Une base propre = des factures qui partent du premier coup, sans rejet.

11. Dépannage

Le test de connexion échoue avec « HTTP 401 — Clé API invalide »

  • Vérifiez que vous avez bien copié toute la clé (sans espace au début/fin)
  • Vérifiez sur https://cbeapi.be que votre clé est active
  • Re-saisissez la clé dans le champ (le champ est masqué par sécurité, mais si vous laissez vide, la clé existante est conservée)

Le test de connexion échoue avec « HTTPS_REQUIRED »

Votre URL d'API commence par http:// au lieu de https://. Modifiez le champ URL de l'API pour utiliser https://cbeapi.be/api/v1.

Le test de connexion échoue avec « API_TIMEOUT »

Augmentez la valeur du Timeout dans la configuration (par défaut 10 s, essayez 30 s). Si l'erreur persiste, votre serveur ne peut peut-être pas atteindre cbeapi.be — vérifiez avec votre hébergeur.

Le bouton « Vérifier avec BCE » n'apparaît pas

  • Vérifiez que le tiers a bien un numéro de TVA renseigné
  • Vérifiez que le numéro commence par BE (sinon le bouton est grisé avec un tooltip explicatif)
  • Vérifiez que votre utilisateur a la permission emsmartfill / verify

Les champs extra (Dernière vérification, Statut) n'apparaissent pas sur la fiche

Allez dans EMSmartFill → Maintenance et cliquez Réparer la base. Le module recrée les champs extra manquants.

Le bulk run est bloqué en statut « En cours » mais rien ne se passe

C'est un run interrompu (crash navigateur, déconnexion). Au prochain chargement de la page Vérification en masse, le module détecte automatiquement les runs anciens (>5 min sans tick) et les marque en stale. Vous pouvez alors Reprendre ou Abandonner.

Besoin d'aide ?

Module activement maintenu — réponse sous 48 h ouvrées.