API BCE : mode test avec données fictives, sans quota
Mode test API BCE : clés pk_test, API de test identique à la v2 et numéros d’entreprise fictifs qui déclenchent chaque cas, sans quota ni données réelles.
Construisez et testez votre intégration sans toucher aux données réelles ni à votre quota. L’API de test répond exactement comme l’API live (mêmes routes, même enveloppe JSON, mêmes codes d’erreur) avec des entreprises fictives.
Fonctionnement#
- Créez une paire de clés de test (
pk_test_…/sk_test_…) dans votre espace compte. - Appelez
https://api-bce.be/test/v2au lieu dehttps://companybelgium.be/api/v2, avec les mêmes en-têtes. - Pour passer en production, changez l’URL de base et utilisez une clé live : votre code ne change pas.
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"Les clés de test n’atteignent jamais les données réelles, et l’API de test refuse les clés live : impossible de les confondre par erreur.
Numéros d’entreprise de test#
Comme les cartes de test de Stripe, chaque numéro déclenche un cas précis. Tous passent le contrôle modulo 97.
| Numéro | Comportement |
|---|---|
0999.999.130 | Entreprise active, données complètes (activités, établissements, comptes annuels, dirigeants). |
0999.999.229 | Ouverture de faillite (juridicalSituationCode 050, inDistress true). |
0999.999.328 | Entreprise arrêtée (statut Stopped). |
0999.999.427 | Personne physique (indépendant), sans comptes annuels. |
0999.999.724 | 403 sur /financial et /roles : formule supérieure requise. |
0999.999.526 | 429 : quota mensuel dépassé. |
0999.999.625 | 500 : erreur serveur (et 503 côté VIES). |
0999.999.823 | 404 : numéro valide, entreprise inconnue. |
0999.999.999 | 400 : numéro invalide (contrôle modulo 97 faux). |
Numéros de TVA (VIES)#
| Numéro | Comportement |
|---|---|
BE0999999130 | Valide, avec nom et adresse. |
BE0999999328 | Non valide (entreprise arrêtée). |
BE0999999625 | 503 : VIES indisponible. |
Établissements#
| Numéro | Comportement |
|---|---|
2.999.999.172 | Siège de l’entreprise active. |
2.999.999.271 | Succursale à Gand. |
2.999.999.370 | Établissement de l’entreprise en faillite. |
Limites#
Le mode test autorise 1 000 requêtes par heure et par clé de test, sans quota mensuel. Les webhooks ne sont pas encore disponibles en mode test.
Construire une suite de tests avec API BCE#
Le mode test brille surtout dans les tests automatisés. Chaque numéro fictif déclenche un comportement connu à l’avance. Vous pouvez donc écrire un test par scénario métier, sans dépendre de la vie réelle d’une entreprise. Par exemple, 0999.999.130 renvoie toujours une société active complète, tandis que 0999.999.229 renvoie une ouverture de faillite.
- Vérification fournisseur : testez le blocage d’une commande avec
0999.999.229(faillite) et0999.999.328(entreprise arrêtée). - Formulaire client : couvrez la personne physique avec
0999.999.427, sans comptes annuels. - Gestion des erreurs :
0999.999.526simule un 429 et0999.999.625un 500. - Formules :
0999.999.724renvoie un 403 sur/financialet/roles. - Saisie :
0999.999.999échoue au contrôle modulo 97 et renvoie un 400.
Organiser vos environnements#
D’abord, gardez la même base de code pour le test et la production. Seules deux valeurs changent : l’URL de base et la paire de clés. Placez-les donc dans votre configuration d’environnement. Ensuite, faites tourner votre intégration continue sur https://api-bce.be/test/v2. Vos tests restent ainsi reproductibles et n’entament jamais le quota de production.
Côté TVA, trois numéros couvrent les cas VIES : valide, non valide et service indisponible (503). Il est donc utile de vérifier que votre facturation sait attendre puis réessayer quand VIES ne répond pas.
Limites à connaître#
Le mode test autorise 1 000 requêtes par heure et par clé de test, sans quota mensuel. En revanche, les webhooks ne sont pas encore disponibles en mode test. Pour tester la réception d’événements, utilisez plutôt l’endpoint POST /webhook/{id}/trigger avec une clé live, qui envoie une livraison de test à votre URL.
Passer du mode test à API BCE en production#
Le passage en production ne demande aucune réécriture. Cependant, quelques vérifications s’imposent. D’abord, remplacez l’URL de test par https://companybelgium.be/api/v2 et la clé pk_test_ par une clé live. Ensuite, rappelez-vous que la production applique un quota mensuel et une limite horaire propres à votre formule. Un traitement qui tournait sans souci en test peut donc atteindre la limite. Enfin, gardez vos tests automatisés branchés sur l’API de test. Ils continuent ainsi de protéger chaque déploiement, sans toucher aux données réelles.
Questions fréquentes sur le mode test API BCE#
Les données de test changent-elles ?
Non. Les entreprises fictives sont stables et chaque numéro garde son comportement. Vos assertions restent donc valables d’une exécution à l’autre.
Puis-je utiliser une clé live sur l’API de test ?
Non. L’API de test refuse les clés live, et les clés de test n’atteignent jamais les données réelles. Ainsi, une confusion entre environnements se voit immédiatement.
Les numéros de test appartiennent-ils à de vraies entreprises ?
Non. Les numéros 0999.999.xxx respectent le contrôle modulo 97, mais n’appartiennent à aucune entreprise. Vous pouvez donc les écrire dans vos tests sans risque.