Validar NIF y CIF por API en Segundos: Verificación contra la AEAT

#Una factura con NIF incorrecto es una factura con problemas

Parece un detalle menor: un campo de 9 caracteres en un formulario. Pero un NIF incorrecto en una factura española puede significar:

• Factura fiscalmente inválida — no deducible para tu cliente
• Rechazo en VeriFactu — el registro en la AEAT falla
• Factura rectificativa obligatoria — trabajo extra para corregirla
• Sanciones — en casos de negligencia reiterada

La mayoría de aplicaciones validan el formato del NIF (regex + letra de control). Eso confirma que B12345678 tiene la estructura correcta. No confirma que exista en la AEAT ni que corresponda a una entidad activa.

La API de BeeL. incluye validación de NIF contra el registro de la Agencia Tributaria. Una llamada, respuesta en milisegundos.

#NIF, CIF, NIE: qué es cada uno

Antes de validar, conviene aclarar la terminología:

Desde 2008, el CIF se integró en el sistema NIF. Todos son “NIF” a efectos fiscales, pero la estructura varía. La API de BeeL. valida los tres formatos.

#Validación con el SDK (3 líneas)

import { BeeL } from '@beel_es/sdk';
 
const beel = new BeeL({ apiKey: process.env.BEEL_API_KEY! });
 
const result = await beel.nif.validate('B12345678');
 
console.log(result.valid); // true
console.log(result.name);  // "EMPRESA EJEMPLO SL"

Eso es todo. La API consulta el registro de la AEAT y devuelve si el NIF está registrado y el nombre fiscal asociado.

#Validación con fetch (sin SDK)

Si no usas Node.js o prefieres no instalar el SDK:

const response = await fetch('https://app.beel.es/api/v1/nif/validate', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer beel_sk_live_tu_api_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ nif: 'B12345678' }),
});
 
const { data } = await response.json();
console.log(data.valid, data.name);

#Con curl

curl -X POST https://app.beel.es/api/v1/nif/validate \
  -H "Authorization: Bearer beel_sk_live_tu_api_key" \
  -H "Content-Type: application/json" \
  -d '{"nif": "B12345678"}'

#Por qué la validación local no es suficiente

Un NIF tiene una letra de control que se calcula a partir de los dígitos. Es trivial verificar que la letra sea correcta:

// Esto solo valida el FORMATO, no la existencia
function isValidNifFormat(nif: string): boolean {
  const letters = 'TRWAGMYFPDXBNJZSQVHLCKE';
  const number = parseInt(nif.slice(0, -1), 10);
  return nif.charAt(nif.length - 1) === letters[number % 23];
}
 
isValidNifFormat('00000000T'); // true — formato correcto
// Pero ¿existe en la AEAT? ¿Es una entidad activa? No lo sabes.

La validación local sirve para filtrar errores evidentes (typos, longitud incorrecta). Pero para confirmar que un NIF es real y está activo, necesitas consultar la AEAT.

#Integración en un formulario de alta de clientes

El patrón más común: validar el NIF cuando el usuario lo introduce en el formulario.

// Backend: endpoint de tu API que valida antes de guardar
app.post('/api/customers', async (req, res) => {
  const { nif, name, email, address } = req.body;
 
  // 1. Validar NIF contra la AEAT
  const nifResult = await beel.nif.validate(nif);
 
  if (!nifResult.valid) {
    return res.status(422).json({
      error: 'NIF_INVALID',
      message: 'El NIF no está registrado en la AEAT',
    });
  }
 
  // 2. Opcional: comparar el nombre fiscal
  if (nifResult.name && nifResult.name !== name.toUpperCase()) {
    // Avisar pero no bloquear — puede ser un nombre comercial
    console.warn(`Nombre fiscal difiere: ${nifResult.name} vs ${name}`);
  }
 
  // 3. Crear cliente en BeeL. + tu base de datos
  const customer = await beel.customers.create({
    legal_name: nifResult.name || name,
    nif,
    email,
    address,
  });
 
  // 4. Guardar en tu BD con referencia a BeeL
  await db.customers.insert({
    ...req.body,
    beel_id: customer.id,
    nif_verified: true,
  });
 
  res.json({ customer });
});

#Casos de uso

#Checkout de e-commerce B2B

En un e-commerce B2B, el cliente introduce su NIF durante el checkout. Valídalo en tiempo real para evitar que complete la compra con datos incorrectos — y que después necesites una rectificativa.

#Onboarding de proveedores

Si gestionas una red de proveedores, valida sus NIFs al darlos de alta. Un NIF inválido significa facturas recibidas no deducibles.

#Migración de datos

Al migrar clientes de un sistema legacy, pasa todos los NIFs por la API para identificar cuáles están desactualizados o son incorrectos antes de importar.

#Prevención de fraude

Un NIF válido que devuelve un nombre fiscal diferente al proporcionado puede indicar suplantación. Útil como señal en sistemas de detección de fraude.

#Preguntas frecuentes

#¿Cuál es la diferencia entre validar formato y validar contra la AEAT?

Validar formato (regex + letra de control) confirma que el NIF tiene la estructura correcta. Validar contra la AEAT confirma que está registrado como contribuyente activo. Son complementarias: la primera es instantánea y local, la segunda requiere una consulta externa.

#¿La validación tiene coste adicional?

No. La validación de NIF está incluida en todos los planes de BeeL. sin coste adicional por consulta.

#¿Qué devuelve la API si el NIF no existe?

Devuelve { valid: false }. No devuelve nombre ni datos adicionales si el NIF no está registrado.

#¿Puedo validar NIFs de otros países de la UE?

Actualmente la API valida NIFs españoles (NIF, CIF, NIE) contra la AEAT. Para NIFs intracomunitarios (validación VIES), está en el roadmap.

#¿Hay límite de consultas?

Los planes de BeeL. incluyen un volumen generoso de validaciones. Si necesitas validación masiva (miles por día), contacta con nosotros para asegurarnos de que tu plan lo cubre.

¿Quieres integrar validación de NIF en tu aplicación? Instala el SDK de TypeScript (código fuente en GitHub), consulta la documentación de la API o la página de SDKs para quickstarts en otros lenguajes. También puedes automatizar la validación con n8n o integrarla en tu CRM.