Laadt u Belgische bedrijfsgegevens in een CRM, een ERP of een inschrijvingsformulier? Versie 2 van onze KBO-API brengt stabiele referentietabellen, validatie van btw-nummers, een betalingsrisicoscore en vooral realtime webhooks. Hieronder leest u wat er verandert, hoe u van v1 migreert en welke werkwijze uw integratie robuust houdt.
Waarom een nieuwe versie van de KBO-API?
De eerste versie hield woord: ze stelde de KBO-gegevens en de verrijkingen van Espero-Soft netjes beschikbaar. Het gebruik leerde ons echter twee dingen. Integratoren willen push in plaats van polling, en ze verkiezen stabiele referentietabellen boven een pak codes die ze bij elke oproep moeten vertalen.
Referentiedata: tabellen om te cachen
NACE-codes, rechtsvormen en activiteitsgroepen hebben nu eigen endpoints. Alle paden hieronder vallen onder het basispad van versie 2:
- GET /reference/nace-codes?lang=fr
- GET /reference/juridical-forms?lang=nl
- GET /reference/activity-groups?lang=en
Die tabellen veranderen zelden. Laad ze dus één keer en bewaar ze in een cache aan clientzijde: de KBO-API stuurt een ETag-header en een Cache-Control van 24 uur mee. U hoeft niet meer bij elke opzoeking te vragen wat een code betekent, want het woordenboek zit in het geheugen. Met de ETag controleert u bovendien of een tabel gewijzigd is voordat u ze opnieuw downloadt.
Validatie van Belgische btw-nummers
Een veelgevraagd endpoint: POST /vat/validate. Het geeft de genormaliseerde versie van het nummer terug, de status (geldig, ongeldig of verkeerd formaat) en het bijbehorende ondernemingsnummer. In België bestaat het btw-nummer uit BE gevolgd door het ondernemingsnummer van tien cijfers uit de KBO. Valideer het al in het inschrijvingsformulier, voordat u de klant in uw database aanmaakt of een e-factuur via Peppol verstuurt.
Score voor betalingsrisico
GET /companies/{enterpriseNumber}/payment-risk geeft een score van 0 tot 100 en een categorie: laag, matig, hoog of kritiek. De KBO-API berekent die score op basis van meerdere signalen: leeftijd van het bedrijf, grootte, sector, boekhoudkundige situatie en recente KBO-gebeurtenissen.
Met een kant-en-klare frontend-widget toont uw team de score ook in de eigen backoffice, zonder alles zelf te bouwen. Gebruik hem als waarschuwingssignaal, bijvoorbeeld om een voorschot te vragen, en niet als automatisch oordeel.
Realtime webhooks
Dit is de meest ingrijpende vernieuwing. U abonneert zich op de gebeurtenissen die voor u tellen:
- company.updated
- company.status_changed
- company.filing_deposited
- establishment.created
- establishment.closed
Elke gebeurtenis vertrekt als POST-request naar uw URL, ondertekend met HMAC SHA-256 en een gedeeld geheim in de header X-Espero-Signature. Mislukt de levering, dan probeert de KBO-API het opnieuw met exponentiële wachttijden, tot 24 uur lang. Via een beheerpagina speelt u een gebeurtenis bovendien handmatig opnieuw af.
Goede praktijken aan ontvangerszijde
- Controleer de handtekening op de ruwe body van het request, vóór elke verwerking.
- Antwoord snel met een 2xx-status en verwerk de gebeurtenis daarna op de achtergrond.
- Vang dubbels op: een nieuwe poging kan dezelfde gebeurtenis twee keer afleveren.
- Volg mislukte leveringen op en speel gemiste gebeurtenissen opnieuw af via de beheerpagina.
Authenticatie en quota
De authenticatie werkt nog altijd met een sleutelpaar, publiek en geheim (pk_live_... en sk_live_...), ongewijzigd sinds v1. Bewaar de geheime sleutel op uw server, nooit in een mobiele app of front-endscript. De quota van de KBO-API v2 liggen bovendien hoger, en een teller in uw dashboard toont uw verbruik in realtime.
Migreren van v1 naar v2
Versie 1 blijft ondersteund tot eind 2026 en de endpoints van v2 draaien parallel. In de meeste gevallen volstaan drie stappen:
- voeg v2 toe aan het basispad van uw URL's (/api/v2/);
- voeg de header Accept: application/json toe (aanbevolen);
- bekijk de verrijkte antwoorden: ze bevatten standaard meer velden, nooit minder.
Test de overstap eerst in een testomgeving en schakel het productieverkeer daarna geleidelijk over.
Voor wie is de KBO-API bedoeld?
Onze KBO-API richt zich tot developers, ERP-integratoren, datateams die een datawarehouse voeden en kantoren die het verzamelen van klantgegevens industrialiseren. Kortom: iedereen die geen eigen KBO-connector meer wil programmeren. Let wel: gegevens over eenmanszaken blijven persoonsgegevens onder de AVG.
Typische toepassingen van de KBO-API:
- Onboarding van klanten: de klantfiche vooraf invullen op basis van het ondernemingsnummer en het btw-nummer valideren.
- Risicobeheer: meteen een webhook ontvangen zodra de status van een klant wijzigt.
- Boekhouding: weten wanneer klanten nieuwe jaarrekeningen neerleggen.
Hulp nodig om die stromen aan uw tools te koppelen? Ons team voor IT-ontwikkeling op maat kan de integratie voor u bouwen.
