CompanyBelgium
BCE API endpoints reference : liste complète des routes REST (companies, addresses, NACE, UBO, établissements, Peppol)
API & Intégration
APIBCE/KBOIntégrationTutorielCodes NACEUBO

BCE API endpoints reference : liste complète des routes REST (companies, addresses, NACE, UBO, établissements, Peppol)

Référence technique exhaustive des endpoints REST de l'API Company Belgium : recherche, fiche entreprise, adresses, activités NACE, établissements, dirigeants, UBO, vérification Peppol. Avec schémas de réponse, paramètres et codes d'erreur.

10 mai 202610 min de lecture

En bref

L'API BCE/KBO de Company Belgium expose une dizaine de domaines fonctionnels via des routes REST versionnees (/v1/) : recherche et fiche d'entreprise, adresses, etablissements, codes NACE, dirigeants, beneficiaires effectifs UBO, verification Peppol, denominations et webhooks. Toutes les reponses suivent le meme contrat JSON avec les headers standard de rate limiting.

À propos de cette référence

Document de référence exhaustif pour les développeurs intégrant l'API BCE/KBO. Tous les endpoints publics y figurent, avec leurs paramètres, schémas de réponse et erreurs possibles.

Base URL : https://api.companybelgium.be/v1

Format : JSON (request + response)

Authentification : X-API-Key + X-API-Secret dans les headers

Structure d'une réponse

Toutes les réponses suivent le même contrat :

JSON 
1
2
3
4
5
{
  "success": true,
  "data": { ... },
  "timestamp": "2026-05-10T14:32:01.523Z"
}

En cas d'erreur :

JSON 
1
2
3
4
5
{
  "success": false,
  "error": "Company not found",
  "timestamp": "2026-05-10T14:32:01.523Z"
}

Endpoints — Entreprises

GET /companies/:enterpriseNumber

Récupère la fiche complète d'une entreprise.

Paramètres : numéro BCE (avec ou sans points, ex. 0200.065.765 ou 0200065765)

Réponse :

JSON 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
{
  "data": {
    "enterpriseNumber": "0200065765",
    "vatNumber": "BE0200065765",
    "name": "Espero-Soft Informatiques SRL",
    "legalForm": "Société à responsabilité limitée",
    "status": "AC",
    "startDate": "1989-05-12",
    "endDate": null,
    "address": {
      "street": "Rue Example",
      "number": "12",
      "postalCode": "1000",
      "municipality": "Bruxelles",
      "country": "BE",
      "fullAddress": "Rue Example 12, 1000 Bruxelles"
    },
    "mainActivity": {
      "code": "62.010",
      "label": "Programmation informatique",
      "version": "2008"
    },
    "establishmentsCount": 3
  }
}

Erreurs : 404 (non trouvé), 429 (rate limit), 401 (auth).

GET /companies/search

Recherche full-text d'entreprises.

Paramètres query :

ParamTypeDescription
qstringRequête (nom, partie de nom, numéro)
limitintMax résultats (défaut: 20, max: 100)
offsetintPagination (défaut: 0)
statusstringFiltre (AC actif, ST cessé, all tous)
postalCodestringFiltre par code postal
naceCodestringFiltre par code NACE

Exemple :

http 
1
GET /companies/search?q=espero&limit=10&status=AC

Réponse :

JSON 
1
2
3
4
5
6
7
8
9
10
11
{
  "data": [
    {
      "enterpriseNumber": "0200065765",
      "name": "Espero-Soft Informatiques SRL",
      "status": "AC",
      "municipality": "Bruxelles"
    }
  ],
  "pagination": { "total": 1, "limit": 10, "offset": 0 }
}

Endpoints — Adresses

GET /companies/:enterpriseNumber/addresses

Récupère toutes les adresses associées à une entreprise (siège, courrier, exploitation).

Réponse :

JSON 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
  "data": [
    {
      "type": "REGO",
      "typeLabel": "Siège social",
      "street": "Rue Example",
      "number": "12",
      "postalCode": "1000",
      "municipality": "Bruxelles",
      "country": "BE",
      "validFrom": "2018-01-01",
      "validTo": null
    }
  ]
}

Types d'adresses : REGO (siège social), PMRG (résidence privée gérant), COBR (correspondance), EXPL (exploitation).

Endpoints — Établissements

GET /companies/:enterpriseNumber/establishments

Liste les unités d'établissement d'une entreprise (sites physiques rattachés).

Réponse :

JSON 
1
2
3
4
5
6
7
8
9
10
11
12
{
  "data": [
    {
      "establishmentNumber": "2100000123",
      "name": "Espero-Soft - Antenne Liège",
      "startDate": "2020-09-01",
      "endDate": null,
      "address": { ... },
      "mainActivity": { ... }
    }
  ]
}

GET /establishments/:establishmentNumber

Récupère une unité d'établissement par son numéro.

Endpoints — Activités NACE

GET /companies/:enterpriseNumber/activities

Liste les codes NACE déclarés (principal + secondaires, par version 2003/2008/2025).

Réponse :

JSON 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
  "data": [
    {
      "code": "62.010",
      "label": "Programmation informatique",
      "version": "2008",
      "type": "MAIN",
      "validFrom": "2018-01-01"
    },
    {
      "code": "63.110",
      "label": "Traitement de données, hébergement",
      "version": "2008",
      "type": "SECONDARY",
      "validFrom": "2020-03-15"
    }
  ]
}

GET /nace-codes

Référentiel complet des codes NACE.

Paramètres query :

ParamTypeDescription
versionstring2003, 2008 ou 2025 (défaut 2008)
qstringRecherche dans les libellés
langstringLangue du libellé (fr, nl, en)

Endpoints — Dirigeants

GET /companies/:enterpriseNumber/directors

Liste les fonctions exercées (administrateurs, gérants, représentants permanents).

Réponse :

JSON 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{
  "data": [
    {
      "functionCode": "AD",
      "functionLabel": "Administrateur délégué",
      "person": {
        "name": "Espero AKPOLI",
        "type": "NATURAL"
      },
      "startDate": "2018-01-01"
    },
    {
      "functionCode": "CO",
      "functionLabel": "Commissaire",
      "person": {
        "name": "Audit & Co SRL",
        "enterpriseNumber": "0400123456",
        "type": "LEGAL"
      },
      "startDate": "2022-06-01"
    }
  ]
}

Endpoints — Bénéficiaires effectifs (UBO)

GET /companies/:enterpriseNumber/ubo

Récupère la cascade UBO complète, croisée avec le registre belge.

Pour les détails légaux du registre UBO, voir l'article dédié.

Réponse :

JSON 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
{
  "data": {
    "lastConfirmation": "2025-12-15",
    "level1": [
      {
        "name": "Jean Dupont",
        "birthDate": "1975-03-21",
        "nationality": "BE",
        "controlPercentage": 60.0,
        "category": "DIRECT"
      }
    ],
    "level2Cascade": [
      {
        "personName": "Marie Martin",
        "effectivePercentage": 48.0,
        "chain": [
          { "company": "Holding ABC SRL", "ownership": 80.0 },
          { "company": "Espero-Soft SRL", "ownership": 60.0 }
        ]
      }
    ],
    "discrepanciesWithRegister": []
  }
}

Endpoints — Vérification Peppol

GET /peppol/check/:identifier

Vérifie si une entreprise est enregistrée sur Peppol (réseau de facturation électronique).

Paramètres : identifier au format 0208:0200065765 (schéma Peppol pour BCE) ou simplement le numéro BCE.

Réponse :

JSON 
1
2
3
4
5
6
7
8
9
10
11
{
  "data": {
    "registered": true,
    "smpUrl": "https://smp.example.com",
    "capabilities": [
      "urn:peppol:invoice:billing:3.0",
      "urn:peppol:invoice:creditnote:3.0"
    ],
    "lastSeen": "2026-05-09T08:12:00Z"
  }
}

Cas non enregistré :

JSON 
1
2
3
4
5
6
7
8
{
  "data": {
    "registered": false,
    "smpUrl": null,
    "capabilities": [],
    "lastSeen": null
  }
}

Endpoints — Dénominations

GET /companies/:enterpriseNumber/denominations

Historique complet des noms et dénominations commerciales (FR/NL/EN).

Réponse :

JSON 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
  "data": [
    {
      "type": "SOCIAL",
      "language": "fr",
      "value": "Espero-Soft Informatiques",
      "validFrom": "2018-01-01"
    },
    {
      "type": "COMMERCIAL",
      "language": "fr",
      "value": "Espero-Soft",
      "validFrom": "2018-01-01"
    }
  ]
}

Endpoints — Webhooks

POST /webhooks

Créer une souscription webhook.

Body :

JSON 
1
2
3
4
5
6
7
8
9
10
11
{
  "url": "https://votre-app.example.com/webhooks/bce",
  "events": [
    "company.updated",
    "company.director.added",
    "company.ubo.changed",
    "company.accounts.filed",
    "company.peppol.registered"
  ],
  "enterpriseNumbers": ["0200065765", "0400123456"]
}

GET /webhooks

Liste vos souscriptions.

DELETE /webhooks/:id

Désactive une souscription.

Codes HTTP standard

CodeSensÀ faire
200OKLire data
400Bad RequestVérifier les paramètres
401UnauthorizedVérifier l'API key/secret
403ForbiddenEndpoint non autorisé sur votre plan
404Not FoundL'entreprise/établissement n'existe pas
429Too Many RequestsRespecter Retry-After
500 / 502 / 503Server ErrorRetry exponentiel

Headers utiles

HeaderSens
X-RateLimit-LimitQuota total sur la fenêtre
X-RateLimit-RemainingQuota restant
X-RateLimit-ResetTimestamp de réinitialisation
Retry-AfterSecondes à attendre avant retry (sur 429)
X-Request-IDID unique de la requête (à fournir au support)

Bonnes pratiques

  • Réutiliser une instance de client HTTP (keep-alive)
  • Implémenter le retry exponentiel sur 429/5xx
  • Mettre en cache les fiches d'entreprise (TTL 5-30 min selon volatilité)
  • Surveiller X-RateLimit-Remaining dans vos logs
  • Préférer les webhooks au polling pour suivre les changements

Comment Company Belgium documente ses endpoints

L'API Company Belgium expose :

  • Spec OpenAPI 3.1 complète disponible sur /docs/openapi.json
  • Sandbox sur https://sandbox.api.companybelgium.be avec données de test
  • SDK Python et TypeScript générés depuis la spec
  • Page de statut publique (incidents, maintenance)

Pour démarrer : voir le tutoriel Python ou le tutoriel Node.js/TypeScript.

Pour comprendre comment scaler : voir l'architecture rate limit / caching.

Pour comparer aux alternatives : comparatif des 5 API BCE.

En résumé

Une API BCE/KBO moderne expose une dizaine de domaines fonctionnels : entreprises, adresses, établissements, NACE, dirigeants, UBO, Peppol, dénominations, webhooks. Le contrat de réponse uniforme ({success, data, error, timestamp}) et les headers rate limit standardisés rendent l'intégration prévisible.

Bookmarkez cette page comme référence. Toutes les routes sont stables et versionnées (/v1/) — les évolutions futures passeront par /v2/ sans casser l'existant.

Questions fréquentes

Quels sont les principaux endpoints de l'API BCE Company Belgium ?

L'API BCE expose les routes suivantes : GET /companies/search pour la recherche full-text, GET /companies/:number pour la fiche complete, GET /companies/:number/addresses pour les adresses, GET /companies/:number/establishments pour les etablissements, GET /companies/:number/activities pour les codes NACE, GET /companies/:number/ubo pour la cascade UBO et GET /peppol/check/:identifier pour verifier l'enregistrement Peppol.

Comment authentifier les requetes vers l'API BCE ?

Chaque requete doit inclure deux headers : X-API-Key avec votre cle publique (pk_live_...) et X-API-Secret avec votre cle secrete (sk_live_...). Ces cles sont generees dans la section Cles API de votre dashboard sur companybelgium.be. La cle secrete est hashee en SHA-256 et n'est affichee qu'une seule fois lors de la creation.

Comment gerer le rate limiting (erreur 429) dans les appels a l'API BCE ?

Quand l'API retourne un code HTTP 429, lisez le header Retry-After qui indique le nombre de secondes a attendre avant de reessayer. Implementez un retry avec backoff exponentiel : attendez Retry-After * 2^tentative secondes entre chaque essai. Surveillez aussi X-RateLimit-Remaining dans vos logs pour anticiper les depassements.

L'API BCE supporte-t-elle les webhooks pour suivre les changements d'entreprises ?

Oui, l'endpoint POST /webhooks permet de s'abonner aux evenements de changement d'entreprise : company.updated, company.director.added, company.ubo.changed, company.accounts.filed et company.peppol.registered. Vous recevez une notification HTTP en temps reel sur votre URL des qu'un evenement se produit, ce qui evite de poller l'API toutes les heures.

Prêt à commencer ?

Créez votre compte gratuitement et obtenez vos clés API en quelques minutes.

Commentaires

Chargement des commentaires…

Laisser un commentaire

Non publié — sert uniquement à vous notifier.

Les commentaires sont modérés avant publication.

Articles similaires

Belgian Crossroads Bank for Enterprises (BCE/KBO) API : documentation développeur complète en anglais

Belgian Crossroads Bank for Enterprises (BCE/KBO) API : documentation développeur complète en anglais

Documentation développeur en anglais pour l'API de la Banque-Carrefour des Entreprises belge. Vue d'ensemble du registre BCE/KBO, contexte légal, options d'accès, démarrage rapide avec exemples cURL et patterns d'intégration pour les développeurs internationaux.

Rate limits, quotas et caching pour scaler une application BCE/KBO : architecture de référence

Rate limits, quotas et caching pour scaler une application BCE/KBO : architecture de référence

Votre app interroge l'API BCE/KBO en volume — comment éviter les 429, maîtriser les coûts et garantir la latence ? Architecture de référence avec cache à plusieurs niveaux, file de requêtes, observabilité et webhooks. Patterns concrets et chiffres à viser.

API officielle KBO vs API tierces : limites du service public BCE et pourquoi passer à une API moderne

API officielle KBO vs API tierces : limites du service public BCE et pourquoi passer à une API moderne

L'API officielle du SPF Économie est gratuite — mais elle est SOAP, sans webhooks, sans enrichissement UBO ou Peppol, et sans SLA. Voici en détail pourquoi 80 % des projets sérieux finissent par migrer vers une API tierce, et comment évaluer si c'est votre cas.

Retour au blog
    BCE API endpoints : reference complete des routes REST | CompanyBelgium