Documentatie

Basis-URL: https://api.klik-shop.nl. Alle antwoorden zijn JSON. Authenticatie met de header X-API-Key. Nog geen key? Maak er gratis een aan.

Snel starten

# Eén nummer
curl https://api.klik-shop.nl/v1/vat/NL004495445B01 \
  -H "X-API-Key: btw_jouw_key"

# Batch (max 50)
curl -X POST https://api.klik-shop.nl/v1/vat/batch \
  -H "X-API-Key: btw_jouw_key" -H "Content-Type: application/json" \
  -d '{"vat_numbers": ["NL004495445B01", "BE0403170701", "DE811191002"]}'

# Btw-tarieven en IBAN (geen key nodig)
curl https://api.klik-shop.nl/v1/rates/NL
curl https://api.klik-shop.nl/v1/iban/NL91ABNA0417164300

const res = await fetch("https://api.klik-shop.nl/v1/vat/" + encodeURIComponent(vatNumber), {
  headers: { "X-API-Key": process.env.BTW_API_KEY }
});
const data = await res.json();
if (res.ok) {
  console.log(data.valid ? "Geldig" : "Ongeldig", data.name);
} else if (res.status === 503) {
  // VIES storing: niet als ongeldig behandelen, later opnieuw proberen
  console.warn(data.error.advice);
} else {
  console.error(data.error.code, data.error.message);
}

<?php
$ch = curl_init("https://api.klik-shop.nl/v1/vat/" . rawurlencode($vatNumber));
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["X-API-Key: " . getenv("BTW_API_KEY")],
  CURLOPT_TIMEOUT => 15,
]);
$data = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($status === 200) {
  echo $data["valid"] ? "Geldig: " . $data["name"] : "Ongeldig";
} elseif ($status === 503) {
  // VIES storing: bestelling voorlopig accepteren en later opnieuw controleren
  error_log($data["error"]["advice"]);
}

Endpoints

Endpoint	Key	Wat
`GET /v1/vat/{btw-nummer}`	ja (1 check)	Controleert één nummer, bv. `NL004495445B01`. Spaties, punten en streepjes mogen. `GR` wordt `EL`; `XI` = Noord-Ierland.
`POST /v1/vat/batch`	ja (1 per nummer)	Body `{"vat_numbers": [...]}`, maximaal 50. Je krijgt per nummer `ok` plus het resultaat of een `error`. `charged` = aantal afgeschreven checks.
`GET /v1/rates`, `GET /v1/rates/{land}`	nee	Btw-tarieven (standaard, verlaagd, superverlaagd, parking) van de 27 EU-landen, met bron en datum.
`GET /v1/iban/{iban}`	nee	Controle van lengte en controlegetal (mod-97). Geen bankgegevens.
`GET /v1/status`	nee	Beschikbaarheid van VIES per land (5 min gecachet).
`GET /v1/account`	ja (gratis)	Verbruik deze maand, resterende gratis checks en tegoed.

Antwoordvelden

`valid`	`true`/`false` volgens VIES
`name`, `address`	Zoals geregistreerd, of `null` als het land dit niet deelt
`source`	`vies` (live), `cache` (< 24 uur oud) of `cache_stale` (VIES storing, laatst bekend resultaat tot 7 dagen, met `warning`)
`checked_at`, `cache_age_seconds`	Moment van de onderliggende VIES-controle

Fouten

Fouten hebben altijd de vorm {"error": {"code", "message", ...}}.

HTTP	code	Betekenis
400	`invalid_format`	Nummer past niet bij het formaat van het land (niet afgeschreven)
401	`missing_api_key`, `invalid_api_key`	Header ontbreekt of key onbekend
402	`quota_exceeded`	Gratis checks en tegoed op. Tegoed kopen
429	`rate_limited`	Meer dan 60 requests per minuut per key (zie `Retry-After`)
503	`service_unavailable`	VIES of de belastingdienst van het land is onbereikbaar. Niet afgeschreven. Zie advies hieronder.

{
  "error": {
    "code": "service_unavailable",
    "message": "VIES or the national VAT database of DE is temporarily unavailable (MS_UNAVAILABLE).",
    "advice": "This does NOT mean the number is invalid. Retry after about 60 seconds. ...",
    "vies_error": "MS_UNAVAILABLE",
    "retry_after_seconds": 60
  }
}

Advies bij 503: behandel het nummer niet als ongeldig. Probeer het na ongeveer 60 seconden opnieuw (header Retry-After). Accepteer in een checkout de bestelling voorlopig en controleer later opnieuw. Check GET /v1/status om te zien welk land storing heeft.

Limieten en verbruik

5 gratis checks per kalendermaand (UTC) per key, daarna gaat je prepaid tegoed op.
Maximaal 60 requests per minuut per key. Een batch-call telt als één request.
Response-headers: X-Quota-Remaining en X-RateLimit-Remaining.
Maximaal 3 nieuwe keys per netwerk per dag.

Bronnen

Btw-nummers: VIES, Europese Commissie. Tarieven: Taxes in Europe Database (TEDB), momentopname van 1 november 2026. Controleer tarieven voor je aangifte altijd bij de nationale belastingdienst.