API BCE test mode: test keys and fictitious company data
API BCE test mode: pk_test keys, a test API identical to v2, and fictitious enterprise numbers that trigger every case, with no quota and no real data.
Build and test your integration without touching real data or your quota. The test API answers exactly like the live API (same routes, same JSON envelope, same error codes) with fictitious companies.
How it works#
- Create a test key pair (
pk_test_…/sk_test_…) in your account. - Call
https://api-bce.be/test/v2instead ofhttps://companybelgium.be/api/v2, with the same headers. - When you go live, swap the base URL and use a live key: your code does not change.
curl https://api-bce.be/test/v2/enterprise/0999.999.130 \
-H "X-API-Key: $API_BCE_KEY_TEST" \
-H "X-API-Secret: $API_BCE_SECRET_TEST"Test keys never reach real data, and live keys are refused by the test API: you cannot mix them up by accident.
Test enterprise numbers#
Like Stripe test cards, each number triggers a precise case. All of them pass the modulo 97 check.
| Number | Behaviour |
|---|---|
0999.999.130 | Active company, full data (activities, establishments, annual accounts, directors). |
0999.999.229 | Bankruptcy opened (juridicalSituationCode 050, inDistress true). |
0999.999.328 | Stopped company (status Stopped). |
0999.999.427 | Natural person (self-employed), no annual accounts. |
0999.999.724 | 403 on /financial and /roles: plan upgrade required. |
0999.999.526 | 429: monthly quota exceeded. |
0999.999.625 | 500: server error (and 503 from VIES). |
0999.999.823 | 404: valid number, unknown company. |
0999.999.999 | 400: invalid number (failed check digits). |
VAT numbers (VIES)#
| Number | Behaviour |
|---|---|
BE0999999130 | Valid, with name and address. |
BE0999999328 | Not valid (stopped company). |
BE0999999625 | 503: VIES unavailable. |
Establishments#
| Number | Behaviour |
|---|---|
2.999.999.172 | Head office of the active company. |
2.999.999.271 | Branch in Ghent. |
2.999.999.370 | Establishment of the bankrupt company. |
Limits#
Test mode allows 1,000 requests per hour per test key and uses no monthly quota. Webhooks are not available in test mode yet.
What to test before going live#
Test mode is most useful when you cover the unhappy paths, not only the happy one. Because each test number triggers a precise case, you can write automated tests that assert how your code reacts. For example, a KYB flow should stop on a bankruptcy, and an invoicing flow should warn on a stopped company.
0999.999.130: active company; check your mapping of activities, establishments, accounts and directors.0999.999.229: bankruptcy opened (juridicalSituationCode050,inDistresstrue); check that your risk rules flag it.0999.999.328: stopped company; check that your supplier check blocks it.0999.999.427: natural person; check that your screens handle the missing annual accounts.0999.999.724,0999.999.526and0999.999.625: 403, 429 and 500; check your error handling and retries.
Wire API BCE test mode into your pipeline#
First, keep the base URL and the key pair in configuration. Then, point your continuous integration at https://api-bce.be/test/v2 with a dedicated test key. Test mode allows 1,000 requests per hour per test key and uses no monthly quota. Therefore, a test suite can run on every commit, as long as it stays under that hourly limit.
VAT checks have their own cases too. BE0999999130 is valid with a name and address, BE0999999328 is not valid, and BE0999999625 returns a 503 to simulate VIES being down. In addition, the establishments 2.999.999.172, 2.999.999.271 and 2.999.999.370 cover a head office, a branch and a site of the bankrupt company.
Pitfalls when switching to live#
Test keys never reach real data, and the test API refuses live keys. As a result, a mixed configuration fails loudly instead of silently. However, webhooks are not available in test mode yet, so plan a separate live check for your receiver. Finally, never keep test numbers in production code paths.
A short go-live checklist helps. First, replace the base URL with https://companybelgium.be/api/v2. Then, swap the test pair for a live key and secret. Next, call /me to confirm the plan and the remaining quota. Finally, fetch one real enterprise you know well and compare it with the fictitious record your tests used. As a result, any mapping gap shows up before customers see it. Your code itself should not change, since API BCE serves the same routes in both modes.
API BCE test mode FAQ#
Does test mode consume my monthly quota?
No. Test mode uses no monthly quota. Instead, it allows 1,000 requests per hour for each test key.
Are the test companies real?
No. They are fictitious. The 0999.999.xxx numbers pass the modulo 97 check but belong to no company.
Can I test webhooks with test keys?
Not yet. For now, use the trigger endpoint on a live webhook to send a test delivery to your receiver.