API v2 : Reference Data, validation TVA et webhooks temps réel

En bref

L'API Company Belgium v2 introduit quatre nouveautés structurantes : des endpoints Reference Data pour les codes NACE et formes juridiques (conçus pour le cache client), la validation de numéro TVA belge en temps réel, un scoring de risque de paiement 0-100, et des webhooks signés HMAC-SHA256 pour recevoir les événements BCE en push plutôt qu'en polling. La v1 reste supportée jusqu'à fin 2026.

Pourquoi une v2 ?

Notre API BCE v1 a tenu sa promesse : exposer proprement les données BCE/KBO et les enrichissements Company Belgium. Mais l'usage nous a appris deux choses : les intégrateurs veulent du push plutôt que du polling, et ils veulent des référentiels stables plutôt qu'à chaque appel un paquet de codes à traduire.

La v2 est disponible en parallèle de la v1. Elle introduit quatre nouveautés structurantes : Reference Data, validation TVA, scoring de risque et webhooks.

Reference Data

Les codes NACE, les formes juridiques et les groupes d'activité sont désormais accessibles via des endpoints dédiés :

• GET /api/v2/reference/nace-codes?lang=fr

• GET /api/v2/reference/juridical-forms?lang=nl

• GET /api/v2/reference/activity-groups?lang=en

Ces tables changent rarement. Elles sont conçues pour être cachées côté client (ETag + Cache-Control 24 h fournis). Vous ne demandez plus « décrivez-moi ce code » à chaque lookup d'entreprise : vous avez le dictionnaire en mémoire.

1
2
3
4
5

class="code-comment">// Charger les codes NACE une fois au démarrage, les cacher en mémoire
const res = await fetch(class="code-string">"https:class="code-comment">//companybelgium.be/api/v2/reference/nace-codes?lang=fr", {
  headers: { class="code-string">"X-API-Key": key, class="code-string">"X-API-Secret": secret }
});
const naceCodes = await res.json(); class="code-comment">// { class="code-string">"62010": class="code-string">"Programmation informatique", ... }

Validation TVA belge

Endpoint très demandé :

1
2
3
4

curl -X POST https://companybelgium.be/api/v2/vat/validate \
  -H "X-API-Key: pk_live_..." \
  -H "X-API-Secret: sk_live_..." \
  -d '{"vatNumber": "BE 0200.065.765"}'

Renvoie la version normalisée, le statut (valid / invalid / bad_format) et le numéro d'entreprise BCE associé. Utile pour valider un formulaire d'onboarding avant de créer un client en base. Ce mécanisme est aussi au coeur de notre module de facturation belge avec autoliquidation intracom.

Scoring du risque de paiement

1
2
3

curl https://companybelgium.be/api/v2/companies/0200065765/payment-risk \
  -H "X-API-Key: pk_live_..." \
  -H "X-API-Secret: sk_live_..."

Renvoie un score 0–100 et une catégorie (low / moderate / high / critical), calculés à partir de signaux agrégés : âge de l'entreprise, taille, secteur, situation comptable, événements BCE récents.

Un widget front prêt à l'emploi est également disponible pour intégrer visuellement l'information dans votre back-office sans tout construire.

Webhooks temps réel

La nouveauté la plus structurante. Abonnez-vous à des événements :

• company.updated

• company.status_changed

• company.filing_deposited

• establishment.created

• establishment.closed

Chaque événement part en POST vers votre URL, signé en HMAC SHA-256 avec un secret partagé. En-tête X-Espero-Signature.

1
2
3
4
5
6
7
8
9

import crypto from class="code-string">"crypto";

function verify(rawBody: string, signature: string, secret: string) {
  const expected = crypto
    .createHmac(class="code-string">"sha256", secret)
    .update(rawBody)
    .digest(class="code-string">"hex");
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
}

Retry exponentiel jusqu'à 24 h, page d'admin pour rejouer manuellement un événement en cas d'échec côté consommateur. Pour un guide complet sur les webhooks et leur sécurisation, lisez notre article sur les webhooks et notifications en temps réel.

Authentification et quotas

L'auth reste basée sur une paire clé publique + secret (pk_live_... / sk_live_...), inchangée depuis la v1. Les quotas sont plus généreux sur la v2, et le compteur est visible en temps réel dans votre tableau de bord.

Migration depuis la v1

La v1 reste supportée jusqu'à fin 2026. Pour la majorité des cas :

• Remplacer /api/ par /api/v2/ dans vos URLs.

• Ajouter l'en-tête Accept: application/json (recommandé).

• Revoir les réponses enrichies (plus de champs par défaut, pas moins).

Un guide de migration détaillé sera publié au prochain sprint. En attendant, consultez le guide d'intégration de l'API BCE dans une application et notre référence des endpoints REST pour les détails des routes v2.