API v2: Reference Data, btw-validatie en realtime webhooks

In het kort

Company Belgium API v2 introduceert vier structurele nieuwigheden: Reference Data-endpoints voor NACE-codes en rechtsvormen (ontworpen voor client-side caching), realtime Belgische btw-nummervalidatie, een betalingsrisicoscore van 0-100, en HMAC-SHA256-ondertekende webhooks om KBO-events in push te ontvangen in plaats van polling. v1 blijft ondersteund tot eind 2026.

Waarom v2?

Onze v1 KBO BCE-API leverde wat beloofd was: Belgische bedrijfsdata en Company Belgium-verrijking netjes ontsluiten. Maar het gebruik leerde ons twee dingen: integrators willen push in plaats van polling, en ze willen stabiele referentietabellen in plaats van bij elke oproep codes te moeten vertalen.

v2 draait parallel aan v1 en introduceert vier structurele nieuwigheden: Reference Data, btw-validatie, risicoscoring en webhooks.

Reference Data

NACE-codes, rechtsvormen en activiteitsgroepen zijn nu beschikbaar via eigen endpoints:

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

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

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

Deze tabellen veranderen zelden. Ze zijn bedoeld om client-side gecacht te worden (ETag + 24u Cache-Control).

1
2
3
4
5

class="code-comment">// Laad NACE-codes bij opstart, cache in memory
const res = await fetch(class="code-string">"https:class="code-comment">//companybelgium.be/api/v2/reference/nace-codes?lang=nl", {
  headers: { class="code-string">"X-API-Key": key, class="code-string">"X-API-Secret": secret }
});
const naceCodes = await res.json();

Belgische btw-validatie

Veelgevraagd endpoint:

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"}'

Retourneert de genormaliseerde versie, de status (valid / invalid / bad_format) en het gekoppelde KBO-ondernemingsnummer. Dit mechanisme vormt ook de kern van onze Belgische facturatiemodule met automatische intracom-verlegging.

Betalingsrisicoscore

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_..."

Retourneert een score 0–100 en een categorie (low / moderate / high / critical), opgebouwd uit geaggregeerde signalen.

Realtime webhooks

De meest structurele toevoeging. Abonneer op events:

• company.updated

• company.status_changed

• company.filing_deposited

• establishment.created

• establishment.closed

Elk event gaat als POST naar uw URL, ondertekend met HMAC SHA-256 via een gedeeld geheim. Header 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));
}

Exponentiële retry tot 24u, adminpagina om een event manueel opnieuw af te spelen. Lees onze gids over webhooks en realtime notificaties voor het volledige beveiligingsprotocol.

Authenticatie en quota

Auth blijft op een public key + secret-paar, ongewijzigd sinds v1. Quota zijn ruimer op v2.

Migratie vanaf v1

v1 blijft ondersteund tot eind 2026. Voor de meeste gevallen: vervang /api/ door /api/v2/ in uw URL's. Een gedetailleerde migratiegids volgt volgende sprint. Raadpleeg alvast de referentiegids REST-endpoints voor de volledige routestructuur van v2.