Documentation / Mode test

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#

  1. Créez une paire de clés de test (pk_test_… / sk_test_…) dans votre espace compte.
  2. Appelez https://api-bce.be/test/v2 au lieu de https://companybelgium.be/api/v2, avec les mêmes en-têtes.
  3. 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éroComportement
0999.999.130Entreprise active, données complètes (activités, établissements, comptes annuels, dirigeants).
0999.999.229Ouverture de faillite (juridicalSituationCode 050, inDistress true).
0999.999.328Entreprise arrêtée (statut Stopped).
0999.999.427Personne physique (indépendant), sans comptes annuels.
0999.999.724403 sur /financial et /roles : formule supérieure requise.
0999.999.526429 : quota mensuel dépassé.
0999.999.625500 : erreur serveur (et 503 côté VIES).
0999.999.823404 : numéro valide, entreprise inconnue.
0999.999.999400 : numéro invalide (contrôle modulo 97 faux).

Numéros de TVA (VIES)#

NuméroComportement
BE0999999130Valide, avec nom et adresse.
BE0999999328Non valide (entreprise arrêtée).
BE0999999625503 : VIES indisponible.

Établissements#

NuméroComportement
2.999.999.172Siège de l’entreprise active.
2.999.999.271Succursale à 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) et 0999.999.328 (entreprise arrêtée).
  • Formulaire client : couvrez la personne physique avec 0999.999.427, sans comptes annuels.
  • Gestion des erreurs : 0999.999.526 simule un 429 et 0999.999.625 un 500.
  • Formules : 0999.999.724 renvoie un 403 sur /financial et /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.