API KVK avec Node.js et TypeScript : guide complet

Node.js et TypeScript sont les technologies les plus répandues pour les applications web modernes et les produits SaaS. Si vous voulez rechercher des informations sur des entreprises, valider des numéros KVK ou intégrer des clients B2B, l’API KVK de KVKBase est le moyen le plus rapide d’y parvenir. Dans ce guide, nous vous accompagnons pas à pas dans l’intégration de l’API à votre projet Node.js ou TypeScript.

Pourquoi Node.js et TypeScript pour les intégrations KVK ?

JavaScript et TypeScript dominent l’écosystème web. Que vous construisiez une API avec Express ou Fastify, une application full-stack avec Next.js ou une application d’entreprise avec NestJS, vous aurez un jour besoin de récupérer des données d’entreprises néerlandaises. Et il est bien plus agréable de manipuler les réponses de l’API de façon typée.

L’API KVKBase renvoie du JSON structuré, ce qui convient parfaitement aux projets TypeScript. Définissez les types une fois, et le reste de votre code profite automatiquement de l’autocomplétion et des vérifications à la compilation.

Installation et configuration

Aucun SDK externe n’est nécessaire. L’API KVKBase fonctionne avec de simples requêtes HTTP. Dans ce guide, nous utilisons fetch (disponible dans Node.js 18+) pour l’approche la plus simple.

Commencez par créer un fichier .env contenant votre clé d’API :

KVKBASE_API_KEY=your_api_key_here

Vous pouvez obtenir votre clé d’API depuis le tableau de bord KVKBase.

Définir les types TypeScript

Commencez par définir les types de la réponse de l’API. Vous bénéficiez ainsi de l’autocomplétion complète dans votre éditeur et évitez les erreurs à l’exécution :

// types/kvkbase.ts

export interface KvkCompany {
  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?: KvkCompany;
  fout?: string;
}

Effectuer l’appel à l’API KVK

Voici une fonction réutilisable pour récupérer les données d’une entreprise :

// lib/kvkbase.ts

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

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

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

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

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

Intégration avec Express

Voici comment ajouter un endpoint de recherche KVK à votre application Express :

// routes/company.ts

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

const router = express.Router();

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

  if (!/^\d{8}$/.test(kvkNumber)) {
    return res.status(400).json({ error: 'Invalid KVK number (8 digits expected)' });
  }

  const company = await lookupCompany(kvkNumber);

  if (!company) {
    return res.status(404).json({ error: 'Company not found' });
  }

  res.json(company);
});

export default router;

Intégration avec l’App Router de Next.js

Avec Next.js 13+, utilisez les Route Handlers pour les appels d’API côté serveur :

// app/api/company/[kvkNumber]/route.ts

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

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

  if (!/^\d{8}$/.test(kvkNumber)) {
    return NextResponse.json(
      { error: 'Invalid KVK number' },
      { status: 400 }
    );
  }

  const company = await lookupCompany(kvkNumber);

  if (!company) {
    return NextResponse.json({ error: 'Not found' }, { status: 404 });
  }

  return NextResponse.json(company);
}

Vous pouvez ensuite l’utiliser dans un composant client avec SWR ou React Query pour une recherche en temps réel pendant la saisie.

Remplissage automatique de formulaire dans Next.js

L’un des cas d’usage les plus précieux est le remplissage automatique des champs d’un formulaire à partir du numéro KVK. Voici un composant React :

// components/CompanyDetailsForm.tsx

'use client';

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

export function CompanyDetailsForm() {
  const [kvkNumber, setKvkNumber] = useState('');
  const [company, setCompany] = useState<KvkCompany | null>(null);
  const [loading, setLoading] = useState(false);

  async function lookup() {
    if (kvkNumber.length !== 8) return;
    setLoading(true);
    const res = await fetch(`/api/company/${kvkNumber}`);
    if (res.ok) setCompany(await res.json());
    setLoading(false);
  }

  return (
    <form>
      <input
        type="text"
        value={kvkNumber}
        onChange={(e) => setKvkNumber(e.target.value)}
        onBlur={lookup}
        placeholder="KVK number (8 digits)"
        maxLength={8}
      />
      {loading && <span>Fetching company data...</span>}
      {company && (
        <>
          <input name="companyName" value={company.naam} readOnly />
          <input name="street" value={company.adres.straat} readOnly />
          <input name="postalCode" value={company.adres.postcode} readOnly />
          <input name="city" value={company.adres.plaats} readOnly />
        </>
      )}
    </form>
  );
}

Mise en cache pour de meilleures performances

Les données KVK changent rarement. Mettez vos réponses en cache pour éviter des appels d’API inutiles et gagner en rapidité :

// lib/kvkbase.ts : avec cache en mémoire

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

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

  const company = await fetchCompanyFromApi(kvkNumber);
  if (company) {
    cache.set(kvkNumber, { data: company, timestamp: Date.now() });
  }
  return company;
}

Pour les environnements de production, utilisez Redis ou un magasin en mémoire similaire. Avec Next.js, vous pouvez aussi utiliser le cache de fetch intégré avec { next: { revalidate: 3600 } }.

Gestion des erreurs et logique de nouvelle tentative

Les applications robustes ont besoin d’une gestion des erreurs solide. Voici un pattern avec backoff exponentiel :

async function fetchWithRetry<T>(
  url: string,
  options: RequestInit,
  maxAttempts = 3
): Promise<T> {
  for (let attempt = 0; attempt < maxAttempts; attempt++) {
    const response = await fetch(url, options);

    if (response.ok) return response.json() as Promise<T>;
    if (response.status === 404) throw new Error('Not found');
    if (response.status === 429) {
      // Limite de débit : attendre avant la prochaine tentative
      await new Promise((r) => setTimeout(r, 1000 * Math.pow(2, attempt)));
      continue;
    }

    throw new Error(`API error: ${response.status}`);
  }
  throw new Error('Max attempts reached');
}

Validation du numéro KVK côté client

Validez le numéro KVK côté client avant d’appeler l’API. Un numéro KVK valide comporte toujours 8 chiffres et respecte des règles de somme de contrôle. Vous trouverez plus de détails sur les règles de validation dans notre article sur la validation du numéro KVK et la somme de contrôle.

export function isValidKvkNumber(kvk: string): boolean {
  if (!/^\d{8}$/.test(kvk)) return false;
  // Vérification de format basique ; pour la validation complète par somme de contrôle : voir la documentation KVKBase
  return true;
}

Prochaines étapes

Avec cette intégration, vous disposez d’une base solide pour récupérer des données d’entreprises néerlandaises dans votre projet Node.js ou TypeScript. À partir de là, vous pouvez :

• Automatiser l’onboarding B2B : les clients n’ont plus qu’à saisir leur numéro KVK
• Enrichir votre CRM : ajouter automatiquement les données d’entreprise à vos prospects
• Optimiser le paiement : un paiement plus rapide pour les clients professionnels

Consultez aussi notre guide Python pour l’API KVK si vous avez un backend Python, ou lisez notre article sur la recherche de numéros KVK pour une introduction plus large.

Prêt à vous lancer ? Créez un compte gratuit sur kvkbase.nl et vous aurez accès à l’API en quelques minutes.