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.

BCE API endpoints : reference complete des routes REST

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

{
  "success": true,
  "data": { ... },
  "timestamp": "2026-05-10T14:32:01.523Z"
}

En cas d'erreur :

JSON

{
  "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

{
  "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 :

Param	Type	Description
`q`	string	Requête (nom, partie de nom, numéro)
`limit`	int	Max résultats (défaut: 20, max: 100)
`offset`	int	Pagination (défaut: 0)
`status`	string	Filtre (`AC` actif, `ST` cessé, `all` tous)
`postalCode`	string	Filtre par code postal
`naceCode`	string	Filtre par code NACE

Exemple :

http

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

Réponse :

JSON

{
  "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

{
  "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

{
  "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

{
  "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 :

Param	Type	Description
`version`	string	`2003`, `2008` ou `2025` (défaut `2008`)
`q`	string	Recherche dans les libellés
`lang`	string	Langue 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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

Code	Sens	À faire
200	OK	Lire `data`
400	Bad Request	Vérifier les paramètres
401	Unauthorized	Vérifier l'API key/secret
403	Forbidden	Endpoint non autorisé sur votre plan
404	Not Found	L'entreprise/établissement n'existe pas
429	Too Many Requests	Respecter `Retry-After`
500 / 502 / 503	Server Error	Retry exponentiel

Headers utiles

Header	Sens
`X-RateLimit-Limit`	Quota total sur la fenêtre
`X-RateLimit-Remaining`	Quota restant
`X-RateLimit-Reset`	Timestamp de réinitialisation
`Retry-After`	Secondes à attendre avant retry (sur 429)
`X-Request-ID`	ID 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.

En bref

À propos de cette référence

Structure d'une réponse

Endpoints — Entreprises

GET /companies/:enterpriseNumber

GET /companies/search

Endpoints — Adresses

GET /companies/:enterpriseNumber/addresses

Endpoints — Établissements

GET /companies/:enterpriseNumber/establishments

GET /establishments/:establishmentNumber

Endpoints — Activités NACE

GET /companies/:enterpriseNumber/activities

GET /nace-codes

Endpoints — Dirigeants

GET /companies/:enterpriseNumber/directors

Endpoints — Bénéficiaires effectifs (UBO)

GET /companies/:enterpriseNumber/ubo

Endpoints — Vérification Peppol

GET /peppol/check/:identifier

Endpoints — Dénominations

GET /companies/:enterpriseNumber/denominations

Endpoints — Webhooks

POST /webhooks

GET /webhooks

DELETE /webhooks/:id

Codes HTTP standard

Headers utiles

Bonnes pratiques

Comment Company Belgium documente ses endpoints

En résumé

Questions fréquentes

Prêt à commencer ?

Commentaires

Laisser un commentaire

Articles similaires

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

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

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