Skip to main content

EMSmartFill — Reliable Belgian client data for Dolibarr

EMSmartFill connects Dolibarr to the official BCE/KBO registry (Crossroads Bank for Enterprises) via the cbeapi.be API. The module verifies your Belgian companies, automatically pre-fills their records, and bulk-fixes malformatted VAT numbers — for 10 European Union countries.

Introduction

Why EMSmartFill?

Over time, your Dolibarr company database accumulates errors: malformatted VAT numbers (be 0123.456.789, 0987654321 without prefix), outdated addresses, missing legal forms, partial duplicates. For a Belgian SME, this means wasted time on invoices, Peppol rejections, and soon a legal blocker when B2B e-invoicing becomes mandatory in 2026.

EMSmartFill retrieves data directly from the official Belgian source and cleans up your database in a few clicks.

Why not Dolibarr's native VAT button?

Dolibarr has a native "Verify" button on company records, but for Belgium it queries VIES (the European service) which only returns validity — no address, no official name, no legal form. EMSmartFill replaces that button with a version that queries the BCE/KBO registry and retrieves all useful data.

1. Installation

Prerequisites

  • Recent Dolibarr version
  • PHP ≥ 8.0
  • Standard Dolibarr Companies/Third parties module enabled
  • Administrator access to your Dolibarr

Steps

  1. Download the module ZIP file from your Dolistore order (or from www.e-dem.com).
  2. Log in to Dolibarr as an administrator.
  3. Go to Setup → Modules/Applications.
  4. Click Deploy/install external module in the top right.
  5. Select the ZIP file module_emsmartfill-X.Y.Z.zip and confirm.
  6. The module appears in the list. Enable it by clicking the toggle.

Note for specific hosting (Cloudron, Plesk, cPanel): if your hosting uses a non-standard DocumentRoot, the module automatically detects the path thanks to the official main.inc.php inclusion pattern. No special configuration required.

Post-installation check

After activation, you should see:

  • A new EMSmartFill link in the module configuration menu
  • A new admin icon (Setup → Modules → EMSmartFill)
  • On every Belgian company record with a VAT number, a "Verify with BCE" button

2. Creating a cbeapi.be account

EMSmartFill uses the cbeapi.be API to query the BCE/KBO registry. You need to create a free account with them.

Why cbeapi.be and not BCE directly?

The BCE/KBO does not offer a public consumer API. cbeapi.be is a Belgian third-party service that aggregates, caches and exposes registry data via a simple REST API. 2,500 free requests per day on signup, which amply covers a standard SME's needs.

Steps

  1. Go to https://cbeapi.be
  2. Create an account (email + password)
  3. In your dashboard, copy the API key (Bearer token)
  4. Note your plan limits (2,500 req/day for the free tier)

Typical volumes

Use case Estimated requests/day
SME with a few new companies/week < 10/day
Monthly bulk verification (500 companies) 500 (1 day/month)
Accountant with 4,000 companies verified every 6 months 4,000 spread over 2 days
Automatic verification on company creation 1 per creation

If you regularly exceed 2,500/day, check the paid plans directly on cbeapi.be.

3. Module configuration

Entering the API key

  1. Go to Setup → Modules/Applications → EMSmartFill → Configure
  2. In the Configuration tab, you see:
    • API key (masked field — the placeholder shows the last 4 characters of the existing key if already entered)
    • API URL: default value https://cbeapi.be/api/v1 (do not change except in special cases)
    • Timeout: 10 seconds by default — increase to 20-30 s if you are on slow hosting
  3. Paste your API key and click Test connection.
  4. If the connection succeeds, the module displays the data of a test company.

If the test fails, see the Troubleshooting section.

Behavior options

Options tab:

Option Effect Recommendation
Automatic verification Verifies the company automatically on creation or modification Disabled by default. Enable if you want "zero click".
Automatic pre-filling Automatically pre-fills after a successful verification Disabled by default. Combine with auto verification. Warning: silently overwrites manually entered data.
Log API responses Stores the full JSON response of each call in the audit log Useful for support. Costs a little storage.

4. Verifying a company

Basic use case

  1. Open a Belgian company record (example: a company you just created with only the VAT number BE0718623213).
  2. Click the "Verify with BCE" button in the top right of the record.
  3. A confirmation dialog appears. Click Yes.
  4. The module queries cbeapi.be and displays a panel with the retrieved BCE data: name, address, postal code, town, country, company number, status, legal form, NACE...

At this point, nothing has been changed in Dolibarr yet. It is just a display of the available data.

Button visual states

Color Meaning
Blue / neutral Company never verified
🟢 Green "BCE Verified" Verified successfully, data available
🟠 Orange Company not found in BCE (wrong VAT number or company ceased)
🔴 Red API error (invalid key, quota exceeded, network issue)
Greyed out VAT missing or non-Belgian

Malformatted VAT numbers

EMSmartFill automatically normalizes common variants before the API call. The following formats are all accepted and give the same result:

  • BE0718623213
  • be 0718.623.213
  • BE 0718 623 213
  • BE-0718-623-213
  • 0718623213 (only if the company's country is set to Belgium)

5. Field-by-field pre-filling

After a verification, you see the BCE panel with a field-by-field comparison table:

☑ Field Current value BCE value Status
☑ name ACME SRL E-dem 🟠 Different
☑ address (empty) Les Bôles 60 🟡 To fill
☑ zip (empty) 5350 🟡 To fill
☑ town Brussels Ohey 🟠 Different
☐ country_id Belgium Belgium 🟢 Identical

Possible statuses

  • 🟢 Identical — no difference, no checkbox (nothing to do)
  • 🟡 Empty (will be filled) — Dolibarr is empty, BCE has a value → checked by default
  • 🟠 Different — both have a value but different → checked by default, with care
  • ⚪ Absent from BCE — Dolibarr has a value, BCE does not → never checked (we never delete)

Shortcuts

  • Select all differences — checks all reds/yellows at once
  • Select only empty fields — for those who NEVER want to overwrite a manually entered value, checks only the yellows

Apply

Click Apply selection: Dolibarr updates only the checked fields and keeps everything else as is. A message confirms the number of fields updated.

6. Bulk verification

Use case

You have 500 Belgian companies in your database. You want to verify them all at once to identify those whose data has changed.

Steps

  1. Go to Setup → Modules → EMSmartFill → Bulk verification
  2. Choose your eligibility filter:
    • All companies with VAT — all Belgian companies, regardless of state
    • Never verified — only those without a verification date yet
    • Not verified since — enter a date (in YYYY-MM-DD format)
    • Retry errors — only companies in error status
    • Retry not found — only companies in not_found status
  3. Check the company types to include: Customers / Suppliers / Prospects
  4. Adjust if needed:
    • Throttle (ms between API calls): 1,000 ms by default. If the API limits you, raise to 2,000-5,000 ms.
    • Batch size (companies per AJAX tick): 5 by default. If your network is fast, you can raise to 10-20.
  5. Click Start verification.

Real-time tracking

The module displays a progress bar that updates every 1-2 seconds via AJAX. You constantly see the percentage processed, the Success / Not found / Errors counters, and the Pause / Resume / Abort buttons.

You can close the tab and come back later — the state is persisted in the database.

Recovery after interruption

If your browser crashes, your PC reboots, or your session expires: on the next load of the Bulk verification page, the module automatically detects the interrupted run and offers to Resume (continue where it left off) or Abort (close).

Detailed report

Once the run is complete, click View detailed report for the global summary with start/end dates, the full table of processed companies (with status filters), and an eye button 👁️ per row to open the relevant company record directly.

7. Bulk VAT normalization

"Analysis" tab

Go to EMSmartFill → Bulk VAT normalization, Analysis tab. Click Start analysis. The module scans all your companies and sorts them into 4 categories:

  • ✅ Already clean — well-formatted VAT, nothing to do
  • 🔵 Auto-correction possible — spaces, dots, dashes, case to fix, or country prefix to add (if the company's country is known)
  • 🟡 Manual review required — ambiguous cases: incorrect length, unknown country, doubtful format
  • 🔴 Rejected — empty or unsupported country (outside the EU)

"Auto-corrections" tab

Shows the detail of the 🔵 category. Table with: company (link to the record), country, current VAT (e.g. be 0123.456.789), proposed VAT (e.g. BE0123456789), correction reason.

All rows are checked by default. Uncheck those you do not want to modify, then click Apply selection. A dialog confirms before execution. Corrections are logged in the audit log (before/after).

"Manual review" tab

For 🟡 cases the module cannot decide on its own (invalid VAT, unknown country, doubtful format), you see each case one by one with 3 actions:

  • Apply — enter the correct value and confirm
  • Skip — move to the next, you will handle it later
  • Reject (leave as is) — the VAT is fine, stop flagging this company

Supported countries

Country Format
🇧🇪 Belgium BE0123456789 (10 digits)
🇫🇷 France FR12345678901 (2 letters or digits + 9 digits)
🇱🇺 Luxembourg LU12345678 (8 digits)
🇳🇱 Netherlands NL123456789B01 (9 digits + B + 2 digits)
🇩🇪 Germany DE123456789 (9 digits)
🇪🇸 Spain ES?1234567? (letter/digit + 7 digits + letter/digit)
🇮🇹 Italy IT12345678901 (11 digits)
🇵🇹 Portugal PT123456789 (9 digits)
🇦🇹 Austria ATU12345678 (U + 8 digits)
🇮🇪 Ireland IE12345678 or IE123456789 (variable)

8. Automation

If you want "zero click", enable the triggers in the Options tab.

Automatic verification

When enabled: each time a Belgian company is created or modified with a VAT number, the module automatically calls the BCE API and stores the result in the extra fields (date + status).

API impact: if you create 100 companies per day, you consume 100 requests per day. Watch out if you are close to the 2,500/day quota.

Automatic pre-filling

When enabled (and auto verification is also active): after verification, the module automatically applies ALL BCE fields to the company, without asking for confirmation.

Use with caution: you lose field-by-field control. If your salespeople entered specific information (a commercial name different from the legal one, for example), it will be overwritten. Recommendation: leave disabled unless you know exactly what you are doing.

9. Audit log and debug

Debug page

EMSmartFill → Debug shows a table of all actions performed (date, user, action type, company, VAT, HTTP status, result). Click View to expand the raw API response (formatted JSON).

Tracked action types:

  • verify_vat — manual verification of a company
  • prefill — pre-filling applied
  • search_vat, search_name — search in the BCE
  • bulk_verify — an item from a bulk run
  • trigger_auto — triggered by the automatic trigger
  • vat_normalize — VAT correction from the normalization page

Maintenance page

EMSmartFill → Maintenance checks database integrity (system prerequisites, required modules, table structure, extra fields, API connection test) and offers repair actions. If something is broken (missing table, deleted extra field...), the Repair database button recreates the missing elements without losing your existing data.

10. FAQ

My company is not found even though it really exists

Three possible causes:

  1. The VAT number contains a typo — check on the official BCE website
  2. The company was recently ceased — the BCE keeps the number but marks it inactive
  3. Historical quirk: some very old VAT numbers (starting with 1 instead of 0) are valid but rare — the module accepts them

I want to verify a Belgian company WITHOUT overwriting its data

This is exactly the basic use case: click Verify with BCE → you see the data → close the panel without clicking Apply. No data is modified. The button just turns green "BCE Verified" and the date is recorded.

The module modifies the company number (Prof. ID 1)

During pre-filling, the Prof. ID 1 (Professional number) field is filled with the 10-digit Belgian company number (without the BE prefix): 0718623213 for example. This is the correct legal format expected by Dolibarr for Belgium. The VAT number (tva_intra) keeps its BE prefix: BE0718623213.

Can the "Verify with BCE" button be disabled for some users?

Yes. Go to Users and groups → Permissions and remove the emsmartfill / verify permission from the relevant users. The button will no longer appear for them.

What happens when I exceed the cbeapi.be free quota?

The API returns an HTTP 429 code (Too Many Requests). EMSmartFill automatically retries once after 5 seconds. If the error persists, the company is marked in error status and you can retry the next day or subscribe to a paid plan.

Multicompany compatible?

Yes. The API key can be global or per entity. Logs are isolated per entity. Tested with and without the module enabled.

Compatible with emPeppol?

Yes, perfectly complementary. EMSmartFill cleans the company database; emPeppol sends Peppol invoices. A clean database = invoices that go through on the first try, without rejection.

11. Troubleshooting

The connection test fails with "HTTP 401 — Invalid API key"

  • Check that you copied the entire key (no space at the start/end)
  • Check on https://cbeapi.be that your key is active
  • Re-enter the key in the field (the field is masked for security, but if you leave it empty, the existing key is kept)

The connection test fails with "HTTPS_REQUIRED"

Your API URL starts with http:// instead of https://. Change the API URL field to use https://cbeapi.be/api/v1.

The connection test fails with "API_TIMEOUT"

Increase the Timeout value in the configuration (10 s by default, try 30 s). If the error persists, your server may not be able to reach cbeapi.be — check with your host.

The "Verify with BCE" button does not appear

  • Check that the company has a VAT number entered
  • Check that the number starts with BE (otherwise the button is greyed out with an explanatory tooltip)
  • Check that your user has the emsmartfill / verify permission

The extra fields (Last verification, Status) do not appear on the record

Go to EMSmartFill → Maintenance and click Repair database. The module recreates the missing extra fields.

The bulk run is stuck in "In progress" status but nothing happens

This is an interrupted run (browser crash, disconnection). On the next load of the Bulk verification page, the module automatically detects old runs (>5 min without a tick) and marks them as stale. You can then Resume or Abort.

Need help?

Actively maintained module — response within 48 business hours.