API KVK en Python : numéro KVK, TVA et données d'entreprises
KVKBase Team

API KVK en Python : numéro KVK, TVA et données d'entreprises

Utilisez l'API KVK de KVKBase en Python : recherche par numéro KVK, validation de TVA via VIES et données d'entreprises, avec exemples de code.

kvkapipythondonnées-entreprisestvapays-bas

Python est le langage le plus utilisé pour les intégrations de données, les scripts et les services backend. Lorsque vous travaillez avec des données d’entreprises néerlandaises, vous aurez tôt ou tard besoin d’une API KVK. Ce guide montre comment utiliser l’API KVK simple de KVKBase en Python pour rechercher les données d’une entreprise, valider des numéros KVK et vérifier des numéros de TVA via VIES, le tout via un seul point d’accès, sans complexité inutile.

Pourquoi Python et l’API KVK vont bien ensemble

La bibliothèque requests de Python simplifie la consommation d’API REST plus que presque tout autre langage. L’API de données d’entreprises néerlandaises de KVKBase renvoie des réponses JSON propres qui se transposent directement dans les structures de données natives de Python, les dataclasses ou les modèles Pydantic.

Cas d’usage typiques en Python :

  • Enrichissement de CRM par lots : parcourir une liste de numéros KVK et y ajouter les données d’entreprise
  • Validation à l’intégration : vérifier à l’inscription qu’un numéro KVK est actif
  • Conformité TVA : valider les numéros de TVA des clients via VIES avant de facturer
  • Pipelines de données : intégrer les données ouvertes du KVK dans des processus ETL ou des tableaux de bord analytiques

Installation et première requête

Vous n’avez besoin que de la bibliothèque requests. Elle est fournie avec la plupart des environnements Python ; sinon, installez-la avec :

pip install requests

Demandez ensuite une clé d’API gratuite sur kvkbase.nl et lancez votre premier appel :

import requests

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://api.kvkbase.nl/api/v1"

headers = {"Authorization": f"Bearer {API_KEY}"}

# Recherche par numéro KVK
response = requests.get(f"{BASE_URL}/lookup/12345678", headers=headers)
data = response.json()
print(data["tradeName"])   # Example B.V.
print(data["isActive"])    # True

C’est tout. Pas d’analyse XML, pas de flux OAuth, pas de SDK nécessaire.

Recherche par numéro KVK : exemple complet

Rechercher un numéro KVK via l’API de recherche KVK renvoie un profil d’entreprise complet :

import requests
from dataclasses import dataclass
from typing import Optional

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://api.kvkbase.nl/api/v1"

@dataclass
class Address:
    street: str
    house_number: str
    postal_code: str
    city: str

@dataclass
class Company:
    kvk_number: str
    trade_name: str
    legal_form: str
    address: Address
    is_active: bool
    vat_number: Optional[str] = None

def fetch_company(kvk_number: str) -> Company:
    url = f"{BASE_URL}/lookup/{kvk_number}"
    headers = {"Authorization": f"Bearer {API_KEY}"}
    
    response = requests.get(url, headers=headers)
    response.raise_for_status()
    d = response.json()
    
    return Company(
        kvk_number=d["kvkNumber"],
        trade_name=d["tradeName"],
        legal_form=d["legalForm"],
        address=Address(
            street=d["address"]["street"],
            house_number=d["address"]["houseNumber"],
            postal_code=d["address"]["postalCode"],
            city=d["address"]["city"],
        ),
        is_active=d["isActive"],
        vat_number=d.get("vatNumber"),
    )

# Utilisation
company = fetch_company("12345678")
print(f"{company.trade_name} - {company.address.city} - Active: {company.is_active}")

L’API de données d’entreprises néerlandaises renvoie, entre autres :

  • Le nom commercial et les éventuels noms enregistrés supplémentaires
  • L’adresse complète (de visite et postale)
  • La forme juridique (BV, NV, entreprise individuelle, fondation, etc.)
  • Les codes SBI avec indicateurs d’activité principale et secondaire
  • La date de constitution et le statut actif/inactif
  • Le numéro de TVA (lorsqu’il est disponible)

Recherche par nom d’entreprise

Vous n’avez pas encore le numéro KVK ? Utilisez l’API de recherche KVK pour chercher par nom :

def search_company(name: str) -> list[dict]:
    url = f"{BASE_URL}/search"
    headers = {"Authorization": f"Bearer {API_KEY}"}
    params = {"q": name}
    
    response = requests.get(url, headers=headers, params=params)
    response.raise_for_status()
    return response.json()["results"]

# Afficher les résultats
results = search_company("Coolblue")
for r in results[:5]:
    print(f"{r['kvkNumber']} - {r['tradeName']} - {r['city']}")

Validation d’un numéro de TVA via VIES en Python

La validation du numéro de TVA est une obligation légale pour les transactions intracommunautaires au sein de l’UE. L’API de validation VIES de KVKBase valide directement les numéros de TVA néerlandais et européens :

def validate_vat(vat_number: str) -> dict:
    """
    Valide un numéro de TVA via VIES.
    Renvoie : valid (bool), name, address
    """
    url = f"{BASE_URL}/validate/vat"
    headers = {"Authorization": f"Bearer {API_KEY}"}
    params = {"vatNumber": vat_number}
    
    response = requests.get(url, headers=headers, params=params)
    response.raise_for_status()
    return response.json()

# Exemple
result = validate_vat("NL123456789B01")
if result["valid"]:
    print(f"Valid VAT number for: {result['name']}")
else:
    print("VAT number is invalid or not active in VIES")

Pour approfondir les codes d’erreur de la validation de TVA, consultez notre guide sur la validation du numéro de TVA néerlandais via VIES.

Enrichissement par lots des données d’entreprises néerlandaises en Python

L’un des usages Python les plus puissants de l’API de données d’entreprises néerlandaises est l’enrichissement de listes. Supposons que vous ayez un CSV de numéros KVK et que vous vouliez y ajouter les noms commerciaux et les adresses :

import csv
import time
import requests

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://api.kvkbase.nl/api/v1"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

def enrich_csv(input_path: str, output_path: str):
    with open(input_path, newline="") as infile, \
         open(output_path, "w", newline="") as outfile:
        
        reader = csv.DictReader(infile)
        fields = reader.fieldnames + ["trade_name", "city", "postal_code", "is_active"]
        writer = csv.DictWriter(outfile, fieldnames=fields)
        writer.writeheader()
        
        for row in reader:
            kvk = row.get("kvk_number", "").strip()
            if not kvk:
                writer.writerow(row)
                continue
            
            try:
                resp = requests.get(
                    f"{BASE_URL}/lookup/{kvk}",
                    headers=HEADERS,
                    timeout=5
                )
                if resp.status_code == 200:
                    d = resp.json()
                    row["trade_name"] = d["tradeName"]
                    row["city"] = d["address"]["city"]
                    row["postal_code"] = d["address"]["postalCode"]
                    row["is_active"] = d["isActive"]
            except Exception as e:
                print(f"Error for KVK {kvk}: {e}")
            
            writer.writerow(row)
            time.sleep(0.1)  # Respecter les limites de débit

enrich_csv("customers.csv", "customers_enriched.csv")

C’est le schéma standard qu’utilisent les ingénieurs de données pour l’enrichissement de CRM, le scoring de prospects et le contrôle de conformité à partir des données d’entreprises néerlandaises.

Données ouvertes du KVK : que trouve-t-on ?

KVKBase donne accès aux données ouvertes du KVK issues du registre néerlandais du commerce. Ce sont les informations publiques que chaque entreprise néerlandaise immatriculée est tenue de maintenir. L’API de données d’entreprises du KVK expose :

  • Données de base : nom commercial, numéro KVK, numéro d’établissement
  • Adresse : rue, numéro, code postal, ville
  • Juridique : forme juridique, date de constitution
  • Activités : codes SBI avec descriptions
  • Statut : active ou dissoute

Pour situer KVKBase par rapport à l’API du registre officiel, consultez notre article comparatif des API KVK : officielle contre KVKBase.

Gestion des erreurs et logique de nouvelle tentative

Une intégration de niveau production gère les défaillances transitoires :

import requests
from requests.adapters import HTTPAdapter
from urllib3.util.retry import Retry

def create_session() -> requests.Session:
    session = requests.Session()
    retry = Retry(
        total=3,
        backoff_factor=0.5,
        status_forcelist=[429, 500, 502, 503, 504],
    )
    adapter = HTTPAdapter(max_retries=retry)
    session.mount("https://", adapter)
    return session

SESSION = create_session()

def safe_lookup(kvk_number: str) -> dict | None:
    try:
        resp = SESSION.get(
            f"https://api.kvkbase.nl/api/v1/lookup/{kvk_number}",
            headers={"Authorization": f"Bearer {API_KEY}"},
            timeout=10,
        )
        if resp.status_code == 404:
            return None  # Numéro KVK introuvable
        resp.raise_for_status()
        return resp.json()
    except requests.RequestException as e:
        print(f"API error for {kvk_number}: {e}")
        return None

Le widget KVKBase, une alternative pour les formulaires

Vous construisez une application web où les utilisateurs saisissent eux-mêmes le nom de leur entreprise ou leur numéro KVK ? Le widget intégrable KVKBase est la voie la plus rapide. Ajoutez une seule balise script et vous obtenez immédiatement un champ de recherche d’entreprise fonctionnel :

<script src="https://widget.kvkbase.nl/embed.js"
        data-api-key="YOUR_API_KEY"
        data-target="#company-search">
</script>

Le widget est entièrement personnalisable en termes de style et fonctionne d’emblée. Vous pouvez l’associer à une validation côté serveur en Python : le widget gère l’interface, votre backend Python valide et stocke les données.

Pour commencer : l’API KVK simple en cinq minutes

L’API KVK simple de KVKBase est conçue pour être opérationnelle en quelques minutes, pas en plusieurs jours. Voici comment démarrer :

  1. Créez un compte gratuit sur kvkbase.nl
  2. Copiez votre clé d’API depuis le tableau de bord
  3. Installez requests : pip install requests
  4. Lancez votre première recherche avec le code d’exemple ci-dessus
  5. Passez à une formule payante dès que vous avez du trafic en production

La formule gratuite suffit largement pour les prototypes et les petites intégrations. À mesure que l’usage augmente, le passage à une formule supérieure se fait en un clic dans le tableau de bord : sans contrat, sans engagement minimum.

Une question sur une intégration Python précise ? Contactez-nous via kvkbase.nl, nous serons ravis de vous aider.