Validar un número de IVA (VIES) al introducir una factura
Un número de IVA mal escrito o no registrado en una factura intracomunitaria supone una inversión del sujeto pasivo discutible. El control corresponde al momento de la introducción, no al cierre.
El problema#
Cuando facturas a un cliente establecido en otro Estado miembro con inversión del sujeto pasivo, debes asegurarte de que su número de IVA es válido. El servicio europeo VIES permite este control, pero hacerlo a mano para cada cliente nuevo, y de nuevo cuando un cliente cambia de número, es el tipo de tarea que se olvida.
El buen momento para controlar es la introducción: en el formulario de alta del cliente o cuando se prepara la factura. Un número inválido se corrige entonces en el acto, antes de que salga la factura.
Los datos de la API que responden#
GET /vat/{vatNumber}: validación en tiempo real de un número de IVA de la Unión Europea ante el servicio VIES de la Comisión Europea.- La respuesta indica si el número es válido, el país, el número normalizado, la fecha de la consulta y, cuando el Estado miembro los comunica, el nombre y la dirección del titular.
- La entrada es tolerante: se aceptan
BE1033022383,BE 1.033.022.383o1033022383(Bélgica por defecto). - Para un cliente belga,
GET /enterprise/{num}completa el control con la ficha del registro (estado, forma jurídica, domicilio social).
Ejemplo de petición#
curl https://companybelgium.be/api/v2/vat/BE1033022383 \
-H "X-API-Key: $API_BCE_KEY" -H "X-API-Secret: $API_BCE_SECRET"Respuesta para un número válido:
{
"success": true,
"data": {
"isValid": true,
"countryCode": "BE",
"vatNumber": "1033022383",
"requestDate": "...",
"name": "...",
"address": "..."
},
"timestamp": "...",
"meta": {
"responseTime": "..."
}
}Implementación recomendada#
- Llama a la validación desde tu servidor cuando se rellena el campo de IVA y muestra el resultado en el formulario.
- Propón el nombre y la dirección devueltos por VIES como ayuda a la introducción, sin sobrescribir lo que el usuario ya ha escrito.
- Guarda la fecha de la consulta con el resultado: documenta el control realizado en el momento de facturar.
- No bloquees la factura cuando VIES no responde: marca el control como «por repetir» y vuelve a intentarlo más tarde.
Límites que conviene conocer#
- VIES es un servicio de la Comisión Europea que consulta a las administraciones nacionales. Cuando un Estado miembro no está disponible, la API responde con un error 502: no es un número inválido.
- Un formato ilegible devuelve un error 400 sin consultar VIES.
- Algunos Estados miembros no comunican ni nombre ni dirección: esos campos llegan entonces vacíos, incluso para un número válido.
- Un número válido en VIES prueba el registro a efectos del IVA, no la identidad de quien hace el pedido. Para abrir una cuenta, consulta el caso KYB.
- La validación no sustituye tu propio análisis del régimen de IVA aplicable a la operación.
Preguntas frecuentes#
¿Qué países cubre la validación de IVA?
Todos los Estados miembros de la Unión Europea, ya que la validación pasa por el servicio VIES de la Comisión Europea.
¿Qué hacer si VIES no responde?
La API devuelve un error 502. Deja la factura pendiente de control o vuelve a intentarlo más tarde; un servicio no disponible no significa que el número sea inválido.
¿Hace falta el prefijo del país?
No para un número belga: sin prefijo se usa Bélgica por defecto. Para otros países, indica el prefijo (FR, NL, DE…).
Llevarlo a la práctica
Crea una clave en el portal de desarrolladores y sigue después la documentación de referencia de cada endpoint citado.
Documentación de referencia