Een btw-nummer valideren (VIES) bij het invoeren van een factuur
Een verkeerd ingetikt of niet-geregistreerd btw-nummer op een intracommunautaire factuur betekent een betwistbare verlegging. De controle hoort bij de invoer, niet bij de afsluiting.
Het probleem#
Wanneer je een klant uit een andere lidstaat factureert met verlegging van heffing, moet je nagaan of zijn btw-nummer geldig is. De Europese VIES-dienst maakt die controle mogelijk, maar ze met de hand doen voor elke nieuwe klant, en opnieuw wanneer een klant van nummer verandert, is het soort taak dat men vergeet.
Het juiste moment om te controleren is de invoer: in het formulier om een klant aan te maken, of wanneer de factuur wordt voorbereid. Een ongeldig nummer wordt dan meteen verbeterd, voor de factuur vertrekt.
De API-gegevens die antwoorden#
GET /vat/{vatNumber}: realtime validatie van een btw-nummer van de Europese Unie bij de VIES-dienst van de Europese Commissie.- Het antwoord vermeldt of het nummer geldig is, het land, het genormaliseerde nummer, de datum van het verzoek en, wanneer de lidstaat ze meedeelt, de naam en het adres van de houder.
- De invoer is tolerant:
BE1033022383,BE 1.033.022.383of1033022383(standaard België) worden aanvaard. - Voor een Belgische klant vult
GET /enterprise/{num}de controle aan met de registerfiche (status, rechtsvorm, zetel).
Voorbeeldverzoek#
curl https://companybelgium.be/api/v2/vat/BE1033022383 \
-H "X-API-Key: $API_BCE_KEY" -H "X-API-Secret: $API_BCE_SECRET"Antwoord voor een geldig nummer:
{
"success": true,
"data": {
"isValid": true,
"countryCode": "BE",
"vatNumber": "1033022383",
"requestDate": "...",
"name": "...",
"address": "..."
},
"timestamp": "...",
"meta": {
"responseTime": "..."
}
}Aanbevolen aanpak#
- Roep de validatie aan vanaf je server wanneer het btw-veld is ingevuld en toon het resultaat in het formulier.
- Stel de naam en het adres die VIES teruggeeft voor als invoerhulp, zonder te overschrijven wat de gebruiker al heeft ingegeven.
- Bewaar de datum van het verzoek bij het resultaat: die documenteert de controle op het moment van facturatie.
- Blokkeer de factuur niet wanneer VIES niet antwoordt: markeer de controle als „opnieuw te doen” en probeer later opnieuw.
Grenzen om te kennen#
- VIES is een dienst van de Europese Commissie die de nationale administraties bevraagt. Als een lidstaat onbereikbaar is, antwoordt de API met een 502-fout: het is geen ongeldig nummer.
- Een onleesbaar formaat geeft een 400-fout zonder VIES te bevragen.
- Sommige lidstaten delen naam noch adres mee: die velden komen dan leeg terug, ook voor een geldig nummer.
- Een nummer dat in VIES geldig is, bewijst de btw-registratie, niet de identiteit van wie de bestelling plaatst. Voor het openen van een account, zie de KYB-toepassing.
- De validatie vervangt je eigen analyse van het btw-regime van de verrichting niet.
Veelgestelde vragen#
Welke landen dekt de btw-validatie?
Alle lidstaten van de Europese Unie, aangezien de validatie via de VIES-dienst van de Europese Commissie loopt.
Wat als VIES niet antwoordt?
De API geeft een 502-fout terug. Houd de factuur in afwachting van de controle of probeer later opnieuw; een onbereikbare dienst betekent niet dat het nummer ongeldig is.
Is het landprefix nodig?
Niet voor een Belgisch nummer: zonder prefix wordt standaard België gebruikt. Voor andere landen geef je het prefix op (FR, NL, DE…).
Aan de slag
Maak een sleutel aan in het ontwikkelaarsportaal en volg daarna de referentiedocumentatie voor elk vermeld endpoint.
Referentiedocumentatie