API-integraties · 14 min lezen
BTW-nummer valideren met de VIES API — retry-logica en caching
Door Alex · Gepubliceerd 17 april 2026
Een BTW-nummer kun je syntactisch valideren met een regex, maar dat zegt niets over of het nummer actief is en daadwerkelijk bij een geregistreerde ondernemer hoort. Voor die laatste stap bestaat één Europese bron: het VIES-systeem van de Europese Commissie. Dit artikel behandelt de structuur van de Nederlandse BTW-identificatie, het gebruik van de REST-API van VIES, typische foutcodes (MS_UNAVAILABLE, MS_MAX_CONCURRENT_REQ, TIMEOUT) en een pragmatische caching-strategie zodat je niet bij elke request de EU belast.
1. Wat is VIES?
VIES staat voor VAT Information Exchange System. Het is een gratis dienst van de Europese Commissie waarmee je kunt controleren of een BTW-identificatienummer uit een van de 27 lidstaten (of Noord-Ierland, landcode XI) op dit moment geldig is. VIES zelf beheert géén database: het doorzoekt de nationale registers (in Nederland de Belastingdienst) via een gestandaardiseerd protocol en geeft een ja/nee-antwoord terug, eventueel met naam en adres van de houder als de lidstaat dat publiceert.
Lange tijd was SOAP de gangbare interface (WSDL op ec.europa.eu/taxation_customs/vies/checkVatService.wsdl). Inmiddels biedt de Commissie ook een REST-API met JSON en een openbare Swagger-beschrijving. Voor nieuwe integraties is die eenvoudiger dan SOAP-envelopes opbouwen.
2. Structuur van een Nederlands BTW-nummer
Een Nederlands BTW-identificatienummer bestaat uit 14 tekens, in twee soorten:
NL + 9 cijfers + B + 2 cijfers
─── ───────── ─── ─────
│ │ │ │
landcode │ letter rechtspersoon: volgnummer (meestal 01)
│ eenmanszaak: controlegetal (mod 97)
│
rechtspersoon: RSIN (elfproef)
eenmanszaak: nummer los van het BSNBij rechtspersonen en samenwerkingsverbanden vormen de negen cijfers het Rechtspersonen en Samenwerkingsverbanden Informatienummer (RSIN), dat aan de elfproef voldoet. Eenmanszaken hadden tot 2020 een btw-nummer met hun BSN erin. Sinds 1 januari 2020 krijgen zij een apart BTW-identificatienummer dat losstaat van het BSN, om privacyredenen. Het oude nummer blijft in gebruik als omzetbelastingnummer voor het contact met de Belastingdienst.
De letter B staat vast. Bij rechtspersonen zijn de laatste twee cijfers een volgnummer, meestal 01; het is geen vestigingsnummer. Bij het btw-id van een eenmanszaak zijn ze een controlegetal: het hele nummer, met N=23, L=21 en B=11, geeft modulo 97 de rest 1 (bijvoorbeeld NL000099998B57). Voor VIES-validatie stuur je het volledige nummer zonder "NL" als vatNumber en apart "NL" als countryCode.
Fictieve nummers van beide soorten, voor je formaat- en controletests, maak je met de btw-nummer generator. Voor de VIES-koppeling zelf gebruik je de testservice uit sectie 3.
3. VIES REST-endpoint
Het gedocumenteerde endpoint is een POST met een JSON-body:
POST https://ec.europa.eu/taxation_customs/vies/rest-api/check-vat-number
Content-Type: application/json
{
"countryCode": "NL",
"vatNumber": "123456782B01",
"requesterMemberStateCode": "NL",
"requesterNumber": "JOUW_BTW_ID_ZONDER_NL"
}De requester-velden zijn optioneel. Er bestaat ook een GET-variant (…/rest-api/ms/NL/vat/123456782B01) die de VIES-website zelf gebruikt, maar die staat niet in de Swagger-beschrijving. Een geldig antwoord heeft ongeveer deze vorm (ingekort):
{
"countryCode": "NL",
"vatNumber": "123456782B01",
"requestDate": "2026-09-25T10:22:13.517Z",
"valid": true,
"requestIdentifier": "(consultatienummer)",
"name": "VOORBEELD B.V.",
"address": "HOOFDSTRAAT 1\n1234 AB AMSTERDAM"
}De velden name en address kunnen "---" bevatten: lidstaten beslissen zelf of zij die gegevens vrijgeven (Duitsland doet dat bijvoorbeeld niet). Het veld requestIdentifier is alleen gevuld als je de requester-velden met je eigen btw-id meestuurt. Dat consultatienummer is het bewijsstuk dat je bewaart om aan te tonen dat je het BTW-identificatienummer op het moment van de transactie hebt gecontroleerd. Voor tests is er een aparte testservice (/check-vat-test-service): vatNumber 100 geeft geldig, 200 ongeldig, en 300 of 301 geven SERVICE_UNAVAILABLE en MS_UNAVAILABLE.
4. TypeScript implementatie
Een type-safe basisimplementatie, zonder retry of cache — die komen in de volgende twee secties:
export interface ViesResult {
countryCode: string;
vatNumber: string;
requestDate: string;
valid: boolean;
requestIdentifier?: string;
name?: string;
address?: string;
}
interface ViesErrorBody {
actionSucceed: false;
errorWrappers: { error: string; message?: string }[];
}
const VIES_URL =
'https://ec.europa.eu/taxation_customs/vies/rest-api/check-vat-number';
export async function checkVatNumber(
countryCode: string,
vatNumber: string, // zonder landcode, bv. 123456782B01
): Promise<ViesResult> {
const res = await fetch(VIES_URL, {
method: 'POST',
headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
body: JSON.stringify({
countryCode: countryCode.toUpperCase(),
vatNumber: vatNumber.replace(/[\s.-]+/g, '').toUpperCase(),
}),
});
const body = (await res.json().catch(() => null)) as
| ViesResult
| ViesErrorBody
| null;
if (!body) throw new ViesApiError(`HTTP_${res.status}`, res.status);
// Fouten komen als errorWrappers-lijst, ook bij HTTP 200
if ('errorWrappers' in body) {
throw new ViesApiError(body.errorWrappers[0]?.error ?? 'UNKNOWN', res.status);
}
return body;
}
export class ViesApiError extends Error {
constructor(public code: string, public status: number) {
super(`VIES returned ${code}`);
}
}Drie dingen om op te merken. Spaties, punten en streepjes moeten eruit (gebruikers plakken regelmatig een BTW-nummer met opmaak). Fouten komen als errorWrappers-lijst, en in onze tests gaf VIES daarbij gewoon status 200; kijk dus niet alleen naar de statuscode. En valid: false betekent "niet geldig volgens de lidstaat", niet "VIES was niet bereikbaar". De interface gebruikt ? voor velden die niet altijd gevuld zijn.
5. Fouten en retry-logica
VIES bevraagt de registers van 27 lidstaten plus Noord-Ierland. Elk register kan tijdelijk uitvallen; VIES geeft dan een foutcode terug in de errorWrappers-lijst. De voornaamste antwoorden:
| Antwoord | Betekenis | Retry? |
|---|---|---|
| valid: false | Nummer niet (meer) geldig volgens de lidstaat | Nee |
| INVALID_INPUT | Ongeldig verzoek, bijvoorbeeld een onbekende landcode | Nee |
| MS_MAX_CONCURRENT_REQ | Te veel gelijktijdige verzoeken voor die lidstaat | Ja, met backoff |
| MS_UNAVAILABLE | Register van de lidstaat tijdelijk niet bereikbaar | Ja, met backoff |
| SERVICE_UNAVAILABLE | VIES zelf niet beschikbaar | Ja, met backoff |
| TIMEOUT | Lidstaat antwoordde niet op tijd | Ja, met backoff |
Exponential backoff met jitter is een veilige default. Een compacte implementatie:
const RETRYABLE = new Set([
'MS_UNAVAILABLE',
'MS_MAX_CONCURRENT_REQ',
'GLOBAL_MAX_CONCURRENT_REQ',
'SERVICE_UNAVAILABLE',
'TIMEOUT',
]);
export async function checkVatNumberWithRetry(
countryCode: string,
vatNumber: string,
maxAttempts = 4,
): Promise<ViesResult> {
let lastError: unknown;
for (let attempt = 0; attempt < maxAttempts; attempt++) {
try {
return await checkVatNumber(countryCode, vatNumber);
} catch (err) {
lastError = err;
const retryable =
err instanceof ViesApiError && RETRYABLE.has(err.code);
if (!retryable || attempt === maxAttempts - 1) throw err;
// Exponential backoff: 500ms, 1s, 2s — plus jitter
const base = 500 * 2 ** attempt;
const jitter = Math.random() * 250;
await new Promise((r) => setTimeout(r, base + jitter));
}
}
throw lastError;
}Let op: de Commissie publiceert geen vaste rate limit. Wie te veel verzoeken tegelijk stuurt, krijgt MS_MAX_CONCURRENT_REQ of GLOBAL_MAX_CONCURRENT_REQ terug, en VIES kent ook de code IP_BLOCKED. Beperk het aantal gelijktijdige verzoeken en gedraag je als een nette API-client.
6. Caching-strategie
Drie redenen om te cachen: latency (elk verzoek gaat via VIES naar het register van een lidstaat), gelijktijdigheidslimieten (een backoffice die bij elke factuur VIES aanroept, loopt tegen MS_MAX_CONCURRENT_REQ aan) en robuustheid (als een lidstaat uitvalt, wil je niet dat je facturatie daarmee stilvalt).
Hoe snel een nieuwe registratie of een intrekking in VIES zichtbaar is, verschilt per lidstaat. Een TTL van één week dekt de meeste usecases, en een TTL van 30 dagen is acceptabel voor niet-kritische workflows (bv. marketing-leads kwalificeren).
Aanbevolen TTL per usecase:
- Intracommunautaire factuur (0 % btw toepassen): hooguit 24 uur — juridisch belang groot
- CRM / leads: 7 dagen — acceptabel
- Bewijs per transactie: niet cachen, live controleren met requester-velden en het
requestIdentifierbij de factuur bewaren
Een simpel Redis- of Cloudflare-KV-patroon:
const TTL_SECONDS = 7 * 24 * 60 * 60; // 7 dagen
export async function checkVatCached(
countryCode: string,
vatNumber: string,
kv: { get(k: string): Promise<string | null>; put(k: string, v: string, opts: { expirationTtl: number }): Promise<void> },
): Promise<ViesResult> {
const key = `vies:${countryCode}:${vatNumber}`;
const cached = await kv.get(key);
if (cached) return JSON.parse(cached) as ViesResult;
const fresh = await checkVatNumberWithRetry(countryCode, vatNumber);
// Negatieve antwoorden korter cachen — de registratie kan net ingaan
const ttl = fresh.valid ? TTL_SECONDS : 60 * 60;
await kv.put(key, JSON.stringify(fresh), { expirationTtl: ttl });
return fresh;
}Twee bewust gemaakte keuzes: negatieve antwoorden krijgen een kortere TTL (1 uur), zodat een net-geregistreerd BTW-nummer niet een week in de cache blijft staan. En de sleutel bevat landcode en nummer afzonderlijk, zodat je per lidstaat kunt invalideren als je weet dat die partij onderhoud heeft gehad.
7. Juridische context — wanneer moet je valideren?
Voor intracommunautaire leveringen geldt dat de leverancier 0 % BTW mag factureren als de afnemer in een andere lidstaat geregistreerd is als ondernemer. Sinds de zogenaamde "quick fixes" die met ingang van 2020 in de BTW-richtlijn (Richtlijn 2006/112/EG, artikel 138) zijn opgenomen, is een geldig btw-id van de afnemer, dat hij aan de leverancier heeft meegedeeld, een materiële voorwaarde geworden voor het nultarief. VIES is de gangbare manier om dat te controleren. Voorheen gold het btw-id vooral als formele voorwaarde die met ander bewijs kon worden aangevuld. Daarnaast moet de levering correct in de opgaaf intracommunautaire prestaties (ICP) staan.
Concreet betekent dit: als je factureert zonder BTW en achteraf blijkt het btw-id ongeldig of ingetrokken, kan de Belastingdienst de Nederlandse btw alsnog naheffen, bij de leverancier. De bewijslast ligt bij de ondernemer. Het requestIdentifier dat VIES teruggeeft, samen met de timestamp van de controle, is in die discussie een sterk bewijsstuk. Bewaar het minimaal zeven jaar samen met de factuur.
Artikel 138 schrijft daarnaast voor dat het vervoer van de goederen aantoonbaar moet zijn, en artikel 139–141 regelen uitzonderingen zoals de driehoekstransactie. Voor de toepassing van 0 % BTW is een VIES-check dus noodzakelijk maar niet voldoende.
8. Bronnen
- Europese Commissie — VIES on-the-web, met technische informatie en de Swagger-beschrijving van de REST-API, via ec.europa.eu/taxation_customs/vies.
- Richtlijn 2006/112/EG van de Raad van 28 november 2006 betreffende het gemeenschappelijke stelsel van belasting over de toegevoegde waarde, artikelen 138–141 (intracommunautaire leveringen), zoals gewijzigd door Richtlijn (EU) 2018/1910 ("quick fixes").
- Uitvoeringsverordening (EU) 282/2011, met name artikel 18 over het vaststellen van de hoedanigheid van belastingplichtige afnemer, en artikel 45 bis over het bewijs van vervoer.
- Belastingdienst — toelichting op het nieuwe BTW-identificatienummer voor eenmanszaken (invoering 2020).
Fout gevonden of aanvullende bron? Mail via contact.
Gerelateerde tools
- BTW-nummer Generator — genereer fictieve NL BTW-nummers voor tests
- KVK-nummer Generator — genereer fictieve KVK-nummers (vaak samen gebruikt met BTW-nummers)
- De elfproef ontleed — het RSIN in btw-nummers van rechtspersonen gebruikt dezelfde controle als het BSN