KVK API met Node.js en TypeScript: De Complete Gids voor Developers

Node.js en TypeScript zijn de meest gebruikte technologieën voor moderne webapplicaties en SaaS-producten. Als je bedrijfsinformatie wilt ophalen, KVK-nummers wilt valideren of B2B-klanten wilt onboarden, dan is de KVK API van KVKBase de snelste manier om dat te doen. In deze gids laten we je stap voor stap zien hoe je de API integreert in je Node.js of TypeScript project.

Waarom Node.js en TypeScript voor KVK-integraties?

JavaScript en TypeScript domineren het web-ecosysteem. Of je nu een API bouwt met Express of Fastify, een full-stack app met Next.js, of een enterprise applicatie met NestJS — vroeg of laat wil je Nederlandse bedrijfsgegevens ophalen. En dan is het prettig als je type-veilig kunt werken met de API-responses.

De KVKBase API geeft je gestructureerde JSON terug, ideaal voor TypeScript-projecten. Eén keer de types definiëren, en de rest van je codebase profiteert automatisch van autocomplete en compile-time checks.

Installatie en setup

Je hebt geen externe SDK nodig. De KVKBase API werkt met gewone HTTP-requests. We gebruiken in deze gids fetch (beschikbaar in Node.js 18+) voor de eenvoudigste aanpak.

Maak eerst een .env bestand aan met je API-key:

KVKBASE_API_KEY=jouw_api_key_hier

Je kunt je API-key ophalen via het KVKBase dashboard.

TypeScript types definiëren

Begin met het definiëren van types voor de API-response. Dit geeft je volledige autocomplete in je editor en voorkomt runtime-fouten:

// types/kvkbase.ts

export interface KvkBedrijf {
  kvkNummer: string;
  naam: string;
  rechtsvorm: string;
  actief: boolean;
  adres: {
    straat: string;
    huisnummer: string;
    postcode: string;
    plaats: string;
    land: string;
  };
  sbiCodes: SbiCode[];
  btwNummer?: string;
}

export interface SbiCode {
  code: string;
  omschrijving: string;
}

export interface KvkBaseResponse {
  succes: boolean;
  data?: KvkBedrijf;
  fout?: string;
}

De KVK API aanroepen

Hier is een herbruikbare functie om bedrijfsgegevens op te halen:

// lib/kvkbase.ts

import type { KvkBaseResponse, KvkBedrijf } from '../types/kvkbase';

const API_URL = 'https://api.kvkbase.nl/api/v1';
const API_KEY = process.env.KVKBASE_API_KEY!;

export async function zoekBedrijf(kvkNummer: string): Promise<KvkBedrijf | null> {
  const response = await fetch(`${API_URL}/kvk/${kvkNummer}`, {
    headers: {
      'X-Api-Key': API_KEY,
      'Content-Type': 'application/json',
    },
  });

  if (!response.ok) {
    if (response.status === 404) return null;
    throw new Error(`KVKBase API fout: ${response.status}`);
  }

  const data: KvkBaseResponse = await response.json();
  return data.succes ? (data.data ?? null) : null;
}

Integratie met Express

Zo voeg je een KVK-lookup endpoint toe aan je Express-applicatie:

// routes/bedrijf.ts

import express from 'express';
import { zoekBedrijf } from '../lib/kvkbase';

const router = express.Router();

router.get('/bedrijf/:kvkNummer', async (req, res) => {
  const { kvkNummer } = req.params;

  if (!/^\d{8}$/.test(kvkNummer)) {
    return res.status(400).json({ fout: 'Ongeldig KVK-nummer (8 cijfers verwacht)' });
  }

  const bedrijf = await zoekBedrijf(kvkNummer);

  if (!bedrijf) {
    return res.status(404).json({ fout: 'Bedrijf niet gevonden' });
  }

  res.json(bedrijf);
});

export default router;

Integratie met Next.js App Router

Met Next.js 13+ gebruik je Route Handlers voor server-side API-calls:

// app/api/bedrijf/[kvkNummer]/route.ts

import { NextRequest, NextResponse } from 'next/server';
import { zoekBedrijf } from '@/lib/kvkbase';

export async function GET(
  request: NextRequest,
  { params }: { params: { kvkNummer: string } }
) {
  const { kvkNummer } = params;

  if (!/^\d{8}$/.test(kvkNummer)) {
    return NextResponse.json(
      { fout: 'Ongeldig KVK-nummer' },
      { status: 400 }
    );
  }

  const bedrijf = await zoekBedrijf(kvkNummer);

  if (!bedrijf) {
    return NextResponse.json({ fout: 'Niet gevonden' }, { status: 404 });
  }

  return NextResponse.json(bedrijf);
}

Vervolgens kun je dit gebruiken in een client component met SWR of React Query voor real-time zoeken terwijl de gebruiker typt.

Formulier auto-fill in Next.js

Een van de meest waardevolle use cases is het automatisch invullen van formuliervelden op basis van het KVK-nummer. Hier is een React component:

// components/BedrijfsgegevensForm.tsx

'use client';

import { useState } from 'react';
import type { KvkBedrijf } from '@/types/kvkbase';

export function BedrijfsgegevensForm() {
  const [kvkNummer, setKvkNummer] = useState('');
  const [bedrijf, setBedrijf] = useState<KvkBedrijf | null>(null);
  const [laden, setLaden] = useState(false);

  async function zoek() {
    if (kvkNummer.length !== 8) return;
    setLaden(true);
    const res = await fetch(`/api/bedrijf/${kvkNummer}`);
    if (res.ok) setBedrijf(await res.json());
    setLaden(false);
  }

  return (
    <form>
      <input
        type="text"
        value={kvkNummer}
        onChange={(e) => setKvkNummer(e.target.value)}
        onBlur={zoek}
        placeholder="KVK-nummer (8 cijfers)"
        maxLength={8}
      />
      {laden && <span>Gegevens ophalen...</span>}
      {bedrijf && (
        <>
          <input name="bedrijfsnaam" value={bedrijf.naam} readOnly />
          <input name="straat" value={bedrijf.adres.straat} readOnly />
          <input name="postcode" value={bedrijf.adres.postcode} readOnly />
          <input name="plaats" value={bedrijf.adres.plaats} readOnly />
        </>
      )}
    </form>
  );
}

Caching voor betere performance

KVK-gegevens veranderen zelden. Cache je responses om onnodige API-calls te vermijden en de snelheid te verbeteren:

// lib/kvkbase.ts — met in-memory cache

const cache = new Map<string, { data: KvkBedrijf; timestamp: number }>();
const CACHE_TTL = 3600 * 1000; // 1 uur

export async function zoekBedrijf(kvkNummer: string): Promise<KvkBedrijf | null> {
  const cached = cache.get(kvkNummer);
  if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
    return cached.data;
  }

  const bedrijf = await fetchBedrijfVanApi(kvkNummer);
  if (bedrijf) {
    cache.set(kvkNummer, { data: bedrijf, timestamp: Date.now() });
  }
  return bedrijf;
}

Voor productie-omgevingen gebruik je beter Redis of een vergelijkbare in-memory store. Voor Next.js kun je ook de ingebouwde fetch-cache gebruiken met { next: { revalidate: 3600 } }.

Foutafhandeling en retry-logica

Robuuste applicaties hebben goede foutafhandeling nodig. Hier is een patroon met exponential backoff:

async function fetchMetRetry<T>(
  url: string,
  opties: RequestInit,
  maxPogingen = 3
): Promise<T> {
  for (let poging = 0; poging < maxPogingen; poging++) {
    const response = await fetch(url, opties);

    if (response.ok) return response.json() as Promise<T>;
    if (response.status === 404) throw new Error('Niet gevonden');
    if (response.status === 429) {
      // Rate limit: wacht voor volgende poging
      await new Promise((r) => setTimeout(r, 1000 * Math.pow(2, poging)));
      continue;
    }

    throw new Error(`API fout: ${response.status}`);
  }
  throw new Error('Maximale pogingen bereikt');
}

KVK-nummer validatie aan de client-side

Valideer het KVK-nummer al aan de client-side voordat je een API-call doet. Een geldig KVK-nummer heeft altijd 8 cijfers en voldoet aan de checksum-regels. Meer details over de validatieregels vind je in ons artikel over KVK nummer validatie en checksum.

export function isGeldigKvkNummer(kvk: string): boolean {
  if (!/^\d{8}$/.test(kvk)) return false;
  // Eenvoudige format check; voor volledige checksum validatie: zie KVKBase docs
  return true;
}

Volgende stappen

Met deze integratie heb je een solide basis voor het ophalen van Nederlandse bedrijfsgegevens in je Node.js of TypeScript project. Vanuit hier kun je:

• B2B onboarding automatiseren — laat klanten alleen hun KVK-nummer invullen
• CRM verrijken — voeg automatisch bedrijfsgegevens toe aan leads
• Checkout optimaliseren — snellere checkout voor zakelijke klanten

Bekijk ook onze Python gids voor de KVK API als je een backend in Python hebt, of lees meer over het opzoeken van KVK-nummers voor een bredere introductie.

Klaar om te starten? Maak een gratis account aan op kvkbase.nl en je hebt binnen een paar minuten toegang tot de API.