KVK-gegevens ophalen in Zapier

De eerlijke opzet: een generieke webhook-stap

Er is geen KVKBase-app in de Zapier directory. Wat er wel is, en wat prima werkt: Webhooks by Zapier, de ingebouwde stap waarmee je elke REST API aanroept. Dezelfde aanpak geldt voor Make (module HTTP), n8n (node HTTP Request) en Power Automate (actie HTTP).

Een werkende Zap ziet er zo uit:

Stap 2 wordt bijna altijd overgeslagen en is de goedkoopste die er is. Een lege of half ingevulde cel kost je anders een task én een lookup, en levert een foutmelding op.

De configuratie van stap 3:

Action:  Webhooks by Zapier > GET
URL:     https://api.kvkbase.nl/v1/lookup/68750110?enrich=true
Headers: Authorization | Bearer YOUR_API_KEY

Het KVK-nummer vervang je door de veldverwijzing uit je trigger. Zet de key in de header, niet in de query string: query strings belanden in logs, bij Zapier en bij ons.

Hoe Zapier de response aanlevert

Zapier vlakt de JSON af voordat je hem kunt mappen. Geneste objecten worden samengevoegd met een dubbele underscore, dus address.city wordt address__city en vat.valid wordt vat__valid. Arrays zoals activities en websites worden samengevouwen: wil je precies één SBI-code, gebruik dan een Formatter- of Code-stap om het juiste element te kiezen in plaats van te hopen dat de eerste de hoofdactiviteit is.

Hier zit de val die iedereen een keer maakt. Zapier bouwt het mappingmenu op uit je testresponse. Test je zonder enrich=true, dan bestaan employees__total, websites en statutoryName niet in dat menu en kun je ze nooit meer mappen. Test je met een eenmanszaak, dan ontbreekt het hele vat-blok, want het BTW-nummer wordt alleen afgeleid voor een BV en een NV.

Test dus altijd met exact de URL en de query-parameters die je in productie gebruikt, en met een bedrijf dat alle velden heeft die je nodig hebt. Verandert de mapping later, dan moet je de stap opnieuw testen voordat de nieuwe velden verschijnen.

Als je alleen een bedrijfsnaam hebt

Een trigger levert vaak een naam en geen nummer. Dan zet je twee webhook-stappen achter elkaar: eerst GET /v1/search?... met de naam, wat kandidaten met hun KVK-nummer oplevert, daarna GET /v1/lookup/{kvkNumber} met het nummer uit de eerste treffer.

Doe dat alleen als je met een fout kunt leven. Een Zap kiest altijd de eerste treffer, en bij een naam als “Van der Berg Holding” zijn dat er tien. Voor alles wat een factuur of een contract raakt, laat je een mens kiezen: stuur de kandidaten naar Slack of naar een goedkeuringsstap en verrijk daarna pas. Houd er ook rekening mee dat deze route twee lookups per record kost in plaats van één.

Wat er in productie stukgaat

Een 404 zet de Zap stil. Bestaat het bedrijf niet meer, dan geven wij NOT_FOUND met een 404. Webhooks by Zapier ziet elke niet-2xx als een fout en stopt die run. Bij een lijst van vijfhonderd rijen betekent dat vijfhonderd errors in je taskgeschiedenis. Gebruik GET /v1/verify/{kvkNumber} als je alleen wilt weten of een nummer bestaat, of vang de fout op met een error-pad zodat de rest doorloopt.

Een bulktrigger raakt de rate limit. Een spreadsheet met tweeduizend rijen die in één keer binnenkomt, vuurt tweeduizend calls af. Op het gratis plan zit je op tien per minuut, op Starter op zestig. Zapier meldt dan RATE_LIMIT_EXCEEDED en probeert het automatisch opnieuw, wat de limiet opnieuw raakt. Zet een Delay-stap in de Zap, of doe de eerste vulling met een script en gebruik de Zap alleen voor nieuwe rijen.

Stille lege velden. Mapt een stap vat__number terwijl de response dat blok niet had, dan schrijft Zapier gewoon een lege waarde weg. Er komt geen fout, je kolom is alleen leeg. Wil je dat zien, filter dan op vat__valid is true voordat je een reverse charge toepast.

Quota is niet hetzelfde als rate limit. De limiet per minuut komt terug zodra je wacht, je maandquota niet. Een Zap die per ongeluk in een lus zit, kan een gratis quota van vijftig lookups in één ochtend opmaken. Controleer GET /v1/me/quota als een Zap onverklaarbaar begint te falen.

Voor herhaalbaar werk op honderden of duizenden bedrijven is een klein script met POST /v1/lookup/batch altijd goedkoper dan een Zap per rij. Zapier is op zijn best voor het losse geval: één nieuw formulierantwoord, één nieuwe deal, één nieuwe klant.