Réduire les coûts de l'API KVK : le bon appel pour chaque tâche

La plupart des équipes commencent par appeler la recherche enrichie partout, parce qu’elle renvoie le plus de données et qu’elle tient en une ligne de code. Puis la première facture mensuelle ou l’alerte de quota arrive, et personne ne sait dire quelle fonctionnalité a consommé les jetons. Les appels étaient tous corrects. Ils n’étaient simplement pas tous nécessaires.

Cet article détaille ce que coûte chaque appel KVKBase et lequel convient à quelle tâche, afin de réduire votre consommation de jetons sans perdre les données dont vous avez réellement besoin.

Ce que coûte chaque appel

KVKBase compte l’usage en jetons. Une recherche de base par numéro KVK (nom, adresse, statut) coûte 1 jeton. Ajouter ?enrich=true vous donne les noms commerciaux, la forme juridique, les codes SBI et les établissements pour 2 jetons. Le profil complet issu du Basisprofiel de la KVK (?enrich=true&vat=true) ajoute les effectifs, la date d’immatriculation, les descriptions SBI officielles et le numéro de TVA pour les personnes morales, et coûte 12 jetons. Une requête de recherche coûte 1 jeton, et lister tous les établissements d’une entreprise en coûte 5.

Le seul appel gratuit est GET /v1/verify/{kvkNumber}. Il indique si un numéro existe et si l’immatriculation est active, rien de plus. Les tarifs actuels et les quotas de jetons par formule figurent sur la page des tarifs, et la liste complète dans la référence de l’API.

L’écart compte. Le profil complet coûte douze fois une recherche de base. Si vous l’utilisez pour une tâche qui n’a besoin que d’un nom et d’une ville, vous payez onze jetons de données que vous jetez.

Adapter l’appel à la question

Considérez chaque fonctionnalité de votre produit comme une question, et choisissez l’appel le moins cher capable d’y répondre.

« Est-ce une entreprise réelle et active ? » correspond à un appel verify, gratuit. Un formulaire d’inscription qui rejette les fautes de frappe et les numéros éteints peut tourner dessus toute la journée. Un détail à gérer : verify ne connaît pas toujours le nom. Selon l’origine de la réponse, name peut valoir null et active peut être inconnu, donc traitez un statut inconnu comme « redemander avec une recherche », et non comme « inactif ».

« À qui appartient ce numéro, et où sont-ils installés ? » correspond à la recherche de base à 1 jeton. Elle couvre les coordonnées de facturation, le préremplissage d’un paiement et la plupart des fiches clients. Notre guide de la recherche de numéro KVK présente les champs de la réponse.

« Sous quel nom commercialisent-ils, et que font-ils ? » demande la recherche enrichie à 2 jetons. Utilisez-la lorsque vous rapprochez par noms commerciaux ou segmentez par code SBI.

« Quelle est la taille de cette entreprise, et quel est son numéro de TVA ? » est la seule raison de payer 12 jetons. Utilisez-la au moment où une décision en dépend, comme des plafonds de crédit ou un dossier KYC, et non sur chaque ligne d’un import.

Ne lancez pas l’appel coûteux en premier

Un schéma économique consiste à escalader. Commencez par verify, car il est gratuit et élimine toutes les fautes de frappe et toutes les entreprises dissoutes. Ne lancez la recherche de base que pour les numéros qui passent. Ne lancez le profil complet que pour le petit groupe qui atteint une étape où vous en avez vraiment besoin, par exemple un client qui demande un devis au-dessus d’un certain montant.

async function onboard(kvkNumber, apiKey) {
  const headers = { Authorization: `Bearer ${apiKey}` };
  const base = "https://api.kvkbase.nl/v1";

  const check = await fetch(`${base}/verify/${kvkNumber}`, { headers })
    .then((r) => r.json());
  if (!check.exists) return { ok: false, reason: "unknown number" };
  if (check.active === false) return { ok: false, reason: "not active" };

  // 1 jeton : le nom et l'adresse suffisent pour le compte
  const company = await fetch(`${base}/lookup/${kvkNumber}`, { headers })
    .then((r) => r.json());
  return { ok: true, company };
}

Dans un tunnel d’inscription classique, une bonne part des tentatives ne dépasse jamais le formulaire : fautes de frappe, saisies de test, parcours abandonnés. Chacune d’elles coûtait auparavant un jeton et ne coûte plus rien. Vous pouvez aussi intercepter les pires fautes de frappe avant tout appel, grâce aux règles de somme de contrôle et de format.

Le traitement par lots économise des allers-retours, pas des jetons

POST /v1/lookup/batch accepte jusqu’à 25 numéros KVK par requête et convient parfaitement aux imports. Il ne rend toutefois pas les recherches moins chères : chaque numéro du lot est facturé au prix de la variante demandée, donc 25 recherches enrichies coûtent 50 jetons, que vous les envoyiez une par une ou ensemble. L’appel par lots vérifie qu’il vous reste assez de jetons pour toute la liste avant de commencer et la refuse sinon, ce qui est pratique car vous ne vous retrouvez jamais avec un import à moitié terminé.

Ce que le lot économise, c’est du temps et de la limite de débit. L’offre gratuite autorise 10 requêtes par minute et l’offre Pro 300, donc 25 numéros par requête vont bien plus loin que 25 appels séparés. Pour une vision plus large du nettoyage d’une base clients, voir l’enrichissement en masse des données CRM.

Avant d’envoyer un lot, retirez de la liste les doublons et les numéros que vous avez déjà consultés récemment. Les données d’entreprise évoluent lentement, et les entreprises actives sont mises en cache pendant 24 heures de notre côté, donc redemander dans cette fenêtre ne vous apporte rien.

Cessez de poser des questions auxquelles les données ont déjà répondu

La plus grosse économie n’est souvent pas un appel moins cher, mais l’absence d’appel. Si vous vérifiez chaque nuit les mêmes 2 000 fournisseurs pour voir si quelque chose a changé, vous payez 2 000 recherches pour apprendre que presque rien n’a bougé. Une surveillance vous prévient quand une entreprise change réellement, et vous ne consultez que celles-là. Nous décrivons les deux options dans garder les données d’entreprise à jour avec les webhooks et le polling.

Conservez aussi ce que vous recevez. Gardez le numéro KVK comme clé, enregistrez les champs que vous utilisez avec la date de leur récupération, et ne les rechargez que lorsque l’enregistrement est plus ancien que votre propre limite ou qu’un événement métier, comme une nouvelle facture au-dessus d’un seuil, justifie une vérification fraîche.

Un audit rapide à faire dès aujourd’hui

Ouvrez vos journaux et comptez les appels par endpoint et par variante sur les 30 derniers jours. Cherchez trois choses : des appels enrichis ou de profil complet sur des fonctionnalités qui n’affichent qu’un nom, des recherches qui suivent une validation de formulaire échouée, et le même numéro demandé plus d’une fois par jour. Chacun de ces cas est un endroit où un appel moins cher ou un résultat stocké fait le même travail.

Envie de voir à quoi ressemble votre propre usage ? Créez un compte KVKBase gratuit, faites tourner votre flux avec l’endpoint verify d’abord et comparez le nombre de jetons au bout d’une semaine.