Guía de integración · España · Última actualización: julio 2026

Verificar el NIF-IVA por API — número de consulta VIES automático

Si tu ERP, tu tienda online o tu software de facturación emite facturas B2B intracomunitarias exentas, debes verificar el NIF-IVA del comprador — y conservar la prueba de esa verificación. Ahí es donde la mayoría de integraciones deja un agujero.

Ante una consulta cualificada, el servicio VIES devuelve un número de consulta — una prueba oficial con marca de tiempo que la Agencia Tributaria (AEAT) acepta como justificante de la exención en entregas intracomunitarias (art. 25 LIVA, art. 138 Directiva 2006/112/CE). Sin ese número, en una inspección solo tienes una captura de pantalla — no un documento reconocido.

¿Qué es el número de consulta VIES?

El VIES (VAT Information Exchange System) es el sistema oficial de la UE para validar NIF-IVA. Cuando consultas un NIF-IVA indicando el tuyo (el "solicitante"), VIES genera un número de consulta con el formato WAPIAAAAW1234567.

Ese número documenta:

Qué NIF-IVA se verificó
Quién lo hizo (tu NIF-IVA como solicitante)
El momento exacto de la verificación
Que el resultado era "válido" en ese instante

Estar dado de alta en el ROI (censo VIES) es requisito para operar en régimen intracomunitario; el número de consulta es la prueba documental de haber realizado la verificación.

El problema: la mayoría de las API no devuelven el número de consulta

Las API de comprobación de IVA habituales — incluidas muchas integraciones en software de facturación populares — consultan VIES pero solo devuelven true o false. El número de consulta se pierde.

Resultado: sabes que un NIF-IVA era válido, pero no puedes demostrarlo. En una inspección no basta.

Vatnode: verifica el NIF-IVA y obtén el número de consulta en una sola llamada

Vatnode devuelve en cada solicitud el número de consulta completo — listo para guardar en tu base de datos o software de facturación:

cURL

curl -X POST https://vatnode.com/v1/validate \
  -H "x-api-key: vnd-tu-clave" \
  -H "Content-Type: application/json" \
  -d '{"vat_number":"ESA28015865","requester_vat":"ESB12345678"}'

Respuesta · JSON

{
  "valid": true,
  "vatNumber": "ESA28015865",
  "countryCode": "ES",
  "consultationNumber": "WAPIAAAAW1234567",  ← la prueba
  "name": "",  ← ES no publica nombre/dirección vía VIES
  "address": "",
  "requestDate": "2026-07-06+02:00",
  "timestamp": "2026-07-06T10:14:02.000Z"
}

Guarda consultationNumber y timestamp directamente en el registro de la factura: es tu prueba conforme a norma.

Nota honesta: España (igual que Alemania) solo publica la validez a través de VIES — nombre y dirección quedan vacíos por política del Estado miembro, no por limitación de la API. El número de consulta — la prueba que pide la inspección — se emite siempre para números españoles. Para la mayoría de los demás Estados (IE, NL, IT, PL, BE, FR…) la API sí devuelve nombre y dirección.

VIES a menudo no está disponible — ¿qué pasa?

VIES sufre caídas frecuentes por país. Cuando la base de datos del Estado miembro está caída, Vatnode devuelve un error claro y reintentable en lugar de un engañoso valid:false, para que no rechaces por error a un cliente real:

JSON

{ "error": "vies_unavailable", "retryable": true }

Implementa un breve reintento con backoff. El estado en vivo de los 27 países está en la página de estado de VIES.

Caso de uso: software de facturación

JavaScript (Node.js)

// Al crear una factura B2B para un cliente de la UE
async function validarYGuardar(nifIva, solicitante, facturaId) {
  const res = await fetch('https://vatnode.com/v1/validate', {
    method: 'POST',
    headers: { 'x-api-key': 'vnd-tu-clave', 'Content-Type': 'application/json' },
    body: JSON.stringify({ vat_number: nifIva, requester_vat: solicitante })
  });
  const data = await res.json();
  if (data.error) throw new Error(data.error);      // p. ej. vies_unavailable → reintento
  if (!data.valid) throw new Error('NIF-IVA no válido');

  await db.facturas.update(facturaId, {
    numero_consulta: data.consultationNumber,
    verificado_en: data.timestamp
  });
}

Cobertura

Vatnode cubre los 27 Estados miembros de la UE vía VIES, con captura del número de consulta y enriquecimiento (razón social + dirección, cuando VIES los facilita). Además valida países fuera de VIES mediante sus registros nacionales oficiales — Noruega ya disponible, Suiza próximamente. La lista completa está en la documentación de la API.

Pruébalo gratis

100 verificaciones al mes gratis — sin tarjeta. Precio de fundador garantizado para los primeros socios.

Sin spam. Precios para primeros usuarios garantizados.