Documentation de l’API CBE2JSON

Démarrage rapide

1. Obtenez votre clé API

Créez un compte gratuit (50 crédits par mois, sans carte de crédit), puis générez une clé dans votre dashboard. Une clé se compose d'un clientId et d'une secretKey.

2. Envoyez votre première requête

Chaque endpoint reçoit un POST avec un corps JSON : vos identifiants et un objet data. Cet exemple recherche Proximus par son numéro d'entreprise. Les points et le préfixe BE sont facultatifs : 0202239951 et BE0202.239.951 fonctionnent aussi.

curl -X POST https://api.cbe2json.be/byCBE \
  -H "Content-Type: application/json" \
  -d '{"clientId": "YOUR_CLIENT_ID", "secretKey": "YOUR_SECRET_KEY", "data": {"cbe": "0202.239.951"}}'

// Node.js 18+, as an ES module: save as first-call.mjs
const response = await fetch('https://api.cbe2json.be/byCBE', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    clientId: 'YOUR_CLIENT_ID',
    secretKey: 'YOUR_SECRET_KEY',
    data: { cbe: '0202.239.951' },
  }),
});
// Check the status first: not every error body is JSON.
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
const body = await response.json();
// API version 2 wraps the enterprise in { data, meta }; version 1 returns it bare.
const company = body.data ?? body;
console.log(company.enterpriseNumber, company.denominations[0].denomination);

import requests

response = requests.post(
    "https://api.cbe2json.be/byCBE",
    json={
        "clientId": "YOUR_CLIENT_ID",
        "secretKey": "YOUR_SECRET_KEY",
        "data": {"cbe": "0202.239.951"},
    },
    timeout=10,
)
# Check the status first: not every error body is JSON.
if not response.ok:
    raise RuntimeError(f"HTTP {response.status_code}: {response.text}")
body = response.json()
# API version 2 wraps the enterprise in { data, meta }; version 1 returns it bare.
company = body.get("data", body)
print(company["enterpriseNumber"], company["denominations"][0]["denomination"])

Pour rechercher par nom, envoyez un POST à /byDenomination avec "data": {"denomination": "Proximus", "limit": 10, "offset": 0}.

Pour retrouver des entreprises par activité (NACE), code postal, commune, rue et numéro, forme juridique ou situation juridique, envoyez un POST à /search avec par exemple "data": {"zipcode": "1000", "street": "Rue de la Loi", "houseNumber": "16"}. Les filtres NACE et adresse doivent correspondre au même siège ou à la même unité d'établissement. Les résultats sont triés par numéro d'entreprise croissant, ce qui rend la pagination par offset et limit stable. Utilisez cette recherche pour rechercher ou vérifier des entreprises, par exemple qui est domicilié à une adresse donnée ou si un fournisseur dispose d'un code d'activité précis — la licence BCE Open Data exclut le marketing direct.

/search/numbers accepte les mêmes filtres et ne renvoie que les numéros d'entreprise, jusqu'à 1000 par page, dans le même ordre croissant.

SDK JavaScript & TypeScript CBE2JSON

3. Traitez la réponse

Un appel réussi renvoie du JSON. À partir de la version 2 de l'API, la réponse a la forme { data, meta } : data contient l'entreprise (ou la liste d'entreprises), et meta indique la date du jeu de données BCE servi, les crédits utilisés par l'appel et les crédits restants. Vérifiez d'abord le statut HTTP : les erreurs de l'API renvoient un corps JSON comme {"errorCode": "…", "message": "…"}, avec l'un de ces codes :

byCBE consomme 1 crédit par entreprise trouvée. byDenomination et search consomment 1 crédit par entreprise renvoyée. search/numbers consomme 1 crédit par page avec résultats. Les requêtes en échec et les résultats vides ne consomment aucun crédit. Les réponses indiquent aussi vos crédits dans des en-têtes : CBE2JSON-Credits-Used, -Remaining, -Limit et -Reset.

Versions de l'API

Chaque clé API est liée à un format de réponse : le JSON que vous traitez ne change jamais à votre insu. Les nouvelles clés démarrent sur la dernière version ; vous pouvez changer la version d'une clé dans votre dashboard à tout moment, et revenir en arrière.

• Version 1 — le format original. Toutes les clés créées avant le versionnement l'utilisent.
• Version 2 — enveloppe chaque réponse dans { data, meta } : data contient l'entreprise ou la liste d'entreprises ; meta donne la date du jeu de données (dataUpdatedAt), les crédits (creditsUsed, creditsRemaining, creditsLimit, creditsResetAt) et, pour byDenomination, la page (total, limit, offset, hasNext). byDenomination accepte une limit de 100 au maximum et répond à une recherche sans résultat par une liste vide au lieu d'une erreur 404.

Pour essayer une autre version sur une seule requête, envoyez l'en-tête CBE2JSON-Version (par exemple 2). Chaque réponse porte ce même en-tête, avec la version utilisée.

Toute modification d'un format de réponse existant fait l'objet d'une nouvelle version. Les anciennes versions restent prises en charge au moins 12 mois après la sortie d'une version plus récente, et nous vous prévenons par e-mail avant d'en retirer une.