API KVK avec PHP et Laravel : données d'entreprises néerlandaises
KVKBase Team

API KVK avec PHP et Laravel : données d'entreprises néerlandaises

Intégrez l'API KVKBase dans votre projet PHP ou Laravel : exemples avec Guzzle, WooCommerce et Laravel, remplissage de formulaire et gestion des erreurs.

kvkapiphplaravelwoocommercedéveloppeurs

PHP reste l’épine dorsale du web. Des extensions WordPress aux plateformes SaaS Laravel en passant par les boutiques WooCommerce, des millions de développeurs travaillent avec PHP chaque jour. Si vos clients professionnels doivent saisir les données de leur entreprise, l’API KVKBase est le moyen le plus rapide d’automatiser cette étape. Dans ce guide, nous vous montrons comment intégrer l’API KVK dans votre projet PHP ou Laravel.

Pourquoi PHP pour les intégrations KVK ?

PHP domine le paysage des CMS et de l’e-commerce. Plus de 70 % des sites web tournent sous PHP, et une grande partie d’entre eux sont des boutiques WooCommerce ou des applications Laravel sur mesure. Pour les boutiques B2B et les plateformes SaaS, le remplissage automatique des données d’entreprise fait gagner énormément de temps aux clients professionnels. Avec KVKBase, un seul appel d’API vous donne accès au nom de l’entreprise, à son adresse, à sa forme juridique et bien plus encore.

Installation

Ajoutez KVKBase à votre projet via Composer, ou utilisez la fonction native file_get_contents de PHP. Nous recommandons Guzzle pour disposer d’un client HTTP fiable :

composer require guzzlehttp/guzzle

Stockez votre clé d’API dans une variable d’environnement. Dans Laravel, utilisez le fichier .env :

KVKBASE_API_KEY=your_...

Récupérez votre clé d’API dans le tableau de bord KVKBase.

Intégration de base avec PHP (sans framework)

Voici une implémentation minimale avec curl pour les projets PHP sans framework, comme les extensions WordPress :

<?php

function kvkbase_lookup_company(string $kvkNumber): ?array {
    $apiKey = getenv('KVKBASE_API_KEY');
    $url    = "https://api.kvkbase.nl/api/v1/kvk/" . urlencode($kvkNumber);

    $ch = curl_init($url);
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER     => [
            "X-Api-Key: {$apiKey}",
            "Content-Type: application/json",
        ],
        CURLOPT_TIMEOUT        => 10,
    ]);

    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    if ($httpCode !== 200 || !$response) {
        return null;
    }

    $data = json_decode($response, true);
    return $data['succes'] ? $data['data'] : null;
}

Vous utilisez WordPress ? Ajoutez cette fonction à functions.php et appelez-la depuis un point d’accès REST ou un gestionnaire AJAX.

Intégration avec Laravel (Guzzle + classe de service)

Dans un projet Laravel, créez une classe de service propre. Votre code reste ainsi testable et facile à simuler :

<?php

namespace App\Services;

use GuzzleHttp\Client;
use GuzzleHttp\Exception\RequestException;
use Illuminate\Support\Facades\Cache;

class KvkBaseService
{
    protected Client $client;

    public function __construct()
    {
        $this->client = new Client([
            'base_uri' => 'https://api.kvkbase.nl/api/v1/',
            'timeout'  => 10,
            'headers'  => [
                'X-Api-Key'    => config('services.kvkbase.api_key'),
                'Content-Type' => 'application/json',
            ],
        ]);
    }

    public function lookupCompany(string $kvkNumber): ?array
    {
        // Mettre les résultats en cache pendant 1 heure
        return Cache::remember("kvk:{$kvkNumber}", 3600, function () use ($kvkNumber) {
            try {
                $response = $this->client->get("kvk/{$kvkNumber}");
                $data     = json_decode($response->getBody(), true);
                return $data['succes'] ? $data['data'] : null;
            } catch (RequestException $e) {
                if ($e->hasResponse() && $e->getResponse()->getStatusCode() === 404) {
                    return null;
                }
                throw $e;
            }
        });
    }
}

Déclarez la clé d’API dans config/services.php :

'kvkbase' => [
    'api_key' => env('KVKBASE_API_KEY'),
],

Contrôleur et route Laravel

Créez un contrôleur qui utilise le service :

<?php

namespace App\Http\Controllers;

use App\Services\KvkBaseService;
use Illuminate\Http\JsonResponse;
use Illuminate\Http\Request;

class CompanyController extends Controller
{
    public function __construct(protected KvkBaseService $kvkBase) {}

    public function lookup(Request $request): JsonResponse
    {
        $request->validate([
            'kvk_number' => 'required|digits:8',
        ]);

        $company = $this->kvkBase->lookupCompany($request->kvk_number);

        if (!$company) {
            return response()->json(['error' => 'Company not found'], 404);
        }

        return response()->json($company);
    }
}

Ajoutez la route dans routes/api.php :

Route::get('/company/{kvkNumber}', [CompanyController::class, 'lookup']);

Remplissage de formulaire avec Blade + Alpine.js

Le cas d’usage le plus utile consiste à remplir automatiquement les champs du formulaire dès qu’un utilisateur saisit son numéro KVK. Voici un composant Blade avec Alpine.js :

<div x-data="{
    kvkNumber: '',
    company: null,
    loading: false,
    async lookup() {
        if (this.kvkNumber.length !== 8) return;
        this.loading = true;
        const res = await fetch('/api/company/' + this.kvkNumber);
        if (res.ok) this.company = await res.json();
        this.loading = false;
    }
}">
    <input
        x-model="kvkNumber"
        @blur="lookup"
        type="text"
        name="kvk_number"
        placeholder="KVK number (8 digits)"
        maxlength="8"
    />

    <span x-show="loading">Loading company details...</span>

    <template x-if="company">
        <div>
            <input name="company_name" :value="company.naam" readonly />
            <input name="street" :value="company.adres.straat + ' ' + company.adres.huisnummer" readonly />
            <input name="postcode" :value="company.adres.postcode" readonly />
            <input name="city" :value="company.adres.plaats" readonly />
        </div>
    </template>
</div>

Cela fonctionne sans dépendance supplémentaire si Alpine.js est déjà chargé, ce qui est le cas dans la plupart des projets Laravel modernes qui utilisent Livewire.

Paiement B2B avec WooCommerce

Vous avez une boutique WooCommerce avec des clients professionnels ? Ajoutez un champ KVK à la page de paiement et remplissez automatiquement les données de facturation :

<?php
// À ajouter dans functions.php de votre thème WooCommerce

add_action('woocommerce_before_checkout_billing_form', function ($checkout) {
    woocommerce_form_field('billing_kvk', [
        'type'        => 'text',
        'class'       => ['form-row-wide'],
        'label'       => 'KVK number',
        'placeholder' => '12345678',
        'required'    => false,
    ], $checkout->get_value('billing_kvk'));
});

add_action('woocommerce_checkout_update_order_meta', function ($order_id) {
    if (!empty($_POST['billing_kvk'])) {
        update_post_meta($order_id, '_billing_kvk', sanitize_text_field($_POST['billing_kvk']));
    }
});

Combinez cela avec le remplissage automatique en JavaScript ci-dessus, et vos clients professionnels n’auront qu’un seul champ à remplir au moment du paiement.

Validation du numéro KVK

Validez le numéro KVK côté serveur avant d’appeler l’API. Un numéro KVK valide compte toujours exactement 8 chiffres. Pour en savoir plus sur les règles de validation, consultez notre article sur la validation du numéro KVK et le checksum.

function isValidKvkNumber(string $kvk): bool
{
    return (bool) preg_match('/^\d{8}$/', $kvk);
}

Dans Laravel, vous pouvez utiliser une règle de validation pratique :

$request->validate([
    'kvk_number' => ['required', 'regex:/^\d{8}$/'],
]);

Mise en cache dans Laravel

Les données KVK changent rarement. Utilisez le cache de Laravel pour éviter des appels d’API inutiles :

$company = Cache::remember("kvk:{$kvkNumber}", now()->addHours(6), function () use ($kvkNumber) {
    return $this->kvkBase->lookupCompany($kvkNumber);
});

Pour les sites à fort trafic, utilisez Redis comme pilote de cache. Cela accélère nettement votre processus de paiement et réduit vos coûts d’API.

Prochaines étapes

Avec cette intégration, vous avez tout ce qu’il faut pour utiliser l’API KVKBase dans votre projet PHP ou Laravel. À partir de là, vous pouvez aller plus loin avec :

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