Exact Online relatie aanmaken met KVK-data

Waar de data landt

Een relatie in Exact Online is een Account onder crm/Accounts, per administratie:

POST https://start.exactonline.nl/api/v1/{division}/crm/Accounts

De velden die je uit een lookup kunt vullen:

Dat huisnummer is de eerste plek waar het misgaat. Wij geven street, houseNumber en houseNumberAddition los terug, Exact wil één regel. Plak ze in die volgorde aan elkaar en sla de losse onderdelen ook in je eigen database op, anders kun je later nooit meer betrouwbaar op huisnummer matchen.

Het integratiepunt is jouw script

Er zit geen koppelvlak tussen ons en Exact. Wat je bouwt is een klein stuk middleware, in welke taal dan ook, met vier stappen:

1. Een KVK-nummer komt binnen, uit een formulier, je CRM of een importbestand.
2. GET /v1/lookup/{kvkNumber}?enrich=true bij ons, met een controle op isActive.
3. Een dubbelencheck in Exact met een OData-filter op het KVK-nummer.
4. POST bij afwezigheid, PUT op de bestaande GUID bij aanwezigheid.

Stap 3 slaan mensen over en dat is precies waarom Exact-administraties vol dubbele relaties zitten:

GET /api/v1/{division}/crm/Accounts?$filter=ChamberOfCommerce eq '68750110'&$select=ID,Name
Authorization: Bearer {exact_access_token}
Accept: application/json

Krijg je nul resultaten, dan pas aanmaken:

{
  "Name": "Acme B.V.",
  "ChamberOfCommerce": "68750110",
  "VATNumber": "NL123456789B01",
  "AddressLine1": "Keizersgracht 123",
  "Postcode": "1015 CJ",
  "City": "Amsterdam",
  "Country": "NL"
}

Voor de bredere ERP-kant, inclusief het bijhouden van wijzigingen, staat er een uitgewerkt stuk in ERP-integratie met KVK-data.

Waar het KVK-nummer vandaan komt

Exact is het eindpunt, niet de invoer. Ergens eerder kiest iemand een bedrijf. Drie plekken waar dat in de praktijk gebeurt, met verschillende gevolgen voor je sync:

• Een aanmeldformulier op je eigen site. Hang de widget aan het KVK-veld: de bezoeker zoekt op naam en jij ontvangt een gekozen nummer in plaats van een overgetypt nummer.
• Je CRM. Dan is het nummer al bij de leadregistratie gevalideerd en is de Exact-sync nog maar een kopieerslag. Dit is de rustigste variant, omdat de dubbelencheck dan al eerder in de keten zit.
• Een importbestand van een accountant of uit een oude administratie. Hier is normaliseren geen luxe maar stap nul: die kolom bevat gegarandeerd tekst, spaties en lege cellen.

Heb je alleen een bedrijfsnaam, dan komt daar een zoekstap voor met GET /v1/search?.... Die geeft kandidaten met hun KVK-nummer terug, waarna een mens kiest. Automatisch de eerste treffer overnemen levert bij een naam als “Van der Berg Holding” gegarandeerd de verkeerde relatie op, en een verkeerde relatie in je boekhouding merk je pas bij de eerste factuur.

Wat er in productie stukgaat

Het rouleren van de refresh token. Exact gebruikt kortlevende access tokens en een refresh token die bij elk gebruik wordt vervangen. Draaien twee processen tegelijk een refresh, dan wint er één en is de ander definitief uitgelogd. Bewaar de tokens centraal, ververs onder een lock, en schrijf de nieuwe refresh token weg vóórdat je hem gebruikt. Dit is de meest voorkomende reden dat een Exact-koppeling op maandagochtend stil staat.

KVK-nummers zonder voorloopnul. Oudere KVK-nummers beginnen met een nul. Gaat de data ooit door Excel of door een kolom van het type getal, dan wordt 01234567 opgeslagen als 1234567 en matcht je OData-filter niets. Pad altijd links bij tot acht cijfers voordat je zoekt of wegschrijft.

Historisch vervuilde ChamberOfCommerce-velden. Omdat Exact het veld niet valideert, staat er van alles in: nummers met punten, met spaties, met de tekst “KVK” ervoor, en soms een 12-cijferig vestigingsnummer. Je dubbelencheck met een exact filter vindt die records niet en maakt een tweede relatie aan. Normaliseer eerst: alleen cijfers overhouden, links bijvullen tot acht, en ruim de bestaande rommel op in een eenmalige run.

Rate limits aan beide kanten tijdens een import. Exact meet zijn limiet per minuut en per dag en geeft die terug in de X-RateLimit-headers op elke response. Onze kant heeft een eigen limiet per minuut. Bij een import van duizenden relaties loop je tegen de traagste van de twee aan. Lees de Exact-headers uit in plaats van blind te retryen, en gebruik aan onze kant POST /v1/lookup/batch zodat de lookups niet de bottleneck zijn.

Een niet meer bestaand bedrijf. Bij NOT_FOUND is de inschrijving uitgeschreven. Maak dan geen relatie aan en verwijder ook niet automatisch een bestaande relatie: er hangen facturen en boekingen aan. Zet een vlag in je eigen systeem en laat een mens beslissen.