API v2 Belgische bedrijfsdata + webhooks

Waarom v2?

Onze v1-API leverde wat beloofd was: Belgische bedrijfsdata en Espero-Soft-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.

Referentiedata

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 meegegeven). Geen "beschrijf deze code" meer bij elke lookup — u houdt het woordenboek in geheugen.

Validatie Belgisch btw-nummer

Veelgevraagd endpoint: POST /api/v2/vat/validate. Retourneert de genormaliseerde versie, de status (geldig / ongeldig / fout formaat) en het gekoppelde ondernemingsnummer. Handig om een onboardingformulier te valideren voor u een klantrecord aanmaakt.

Scoring van betalingsrisico

GET /api/v2/companies/{enterpriseNumber}/payment-risk retourneert een score 0–100 en een categorie (laag / matig / hoog / kritiek), opgebouwd uit geaggregeerde signalen: leeftijd, grootte, sector, boekhoudsituatie, recente KBO-events.

Een kant-en-klare front-widget is ook beschikbaar voor teams die de info visueel willen integreren in hun backoffice.

Realtime webhooks

De meest structurele toevoeging. Abonnement 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. Exponentiële retry tot 24u, adminpagina om manueel opnieuw af te spelen.

Authenticatie en quota

Auth blijft op een public key + secret-paar (pk_live_... / sk_live_...), ongewijzigd sinds v1. Quota zijn ruimer op v2, en de teller is realtime zichtbaar in uw dashboard.

Migratie vanaf v1

v1 blijft ondersteund tot eind 2026. v2-endpoints lopen parallel. Voor de meeste gevallen:

• Vervang /api/ door /api/v2/ in uw URL's.
• Voeg header Accept: application/json toe (aanbevolen).
• Bekijk de rijkere responses (meer velden default, niet minder).

Voor wie?

Developers, ERP-integrators, dataploegen die een warehouse voeden, kantoren die klantendatacollectie industrialiseren. Iedereen die niet meer zelf een KBO-connector wil bouwen.