Download the PHP package iberfacil/es-aeat-vnif without Composer

es-aeat-vnif

Comprueba desde PHP que un NIF existe en el censo de la Agencia Tributaria y que corresponde al nombre que te han dado, usando tu certificado electrónico. Sin framework, con línea de comandos y con adaptador opcional para Laravel.

English version

Creado por Marco Gavilán, de IBERFÁCIL.

Para qué sirve (si no eres técnico)

Cuando una gestoría, un despacho, una empresa o un departamento de cumplimiento recibe los datos de un cliente, un proveedor o un tercero, casi siempre le llega un NIF y un nombre escritos a mano, copiados de un correo o dictados por teléfono. Antes de facturar, contratar, dar de alta a ese cliente, presentar un escrito o incluirlo en una declaración informativa conviene saber dos cosas:

• que ese NIF existe en el censo de la Agencia Tributaria, y
• que corresponde al nombre que te han dado (o a qué nombre corresponde en realidad).

La AEAT ofrece un servicio para eso: el «Servicio de verificación de NIF de terceros» (VNifV2). Este paquete lo usa por ti. Le das el NIF y el nombre, y te devuelve una de estas respuestas:

Ejemplos de uso reales:

• Una gestoría recibe 300 clientes nuevos en un fichero y quiere saber cuáles tienen el NIF mal o el nombre incompleto antes de darlos de alta.
• Un despacho va a presentar un escrito y necesita el nombre exacto del interesado tal como consta en la AEAT.
• Un departamento de facturación quiere evitar emitir facturas con un NIF inexistente, que luego darán problemas en el 347 o en el SII.
• Un comercio online da de alta proveedores y quiere comprobar que la razón social corresponde al CIF.

Qué necesitas: un certificado electrónico (de sello de entidad, de representante de persona jurídica o personal) en formato .p12 o .pfx, con su contraseña. Es el mismo que usas para entrar en la sede electrónica. El paquete no guarda la contraseña ni el certificado en ningún sitio.

¿Qué certificado me sirve?

Cualquiera de los tres que emite la FNMT u otra autoridad reconocida:

Si eres autónomo, no necesitas nada especial: exporta tu certificado personal desde el navegador (o desde la FNMT) a un fichero .p12 o .pfx con contraseña y ya está. El comando doctor te dice qué tipo ha detectado.

Ten en cuenta que las consultas quedan hechas con tu identidad: úsalo solo para tus propios clientes, proveedores y trámites.

Qué NO hace: no acredita que la persona que te da los datos sea quien dice ser. Solo te confirma que ese NIF y ese nombre existen juntos en el censo. La identificación de la persona es otra cosa (documento, vídeo-identificación, firma electrónica…).

Para desarrolladores

Requisitos

• PHP 8.2 o superior con las extensiones openssl, curl, dom, libxml y mbstring (todas habituales). intl es opcional pero recomendable.
• Un certificado electrónico admitido por la AEAT, en .p12/.pfx (o en PEM).
• Acceso HTTPS al endpoint https://www1.agenciatributaria.gob.es/wlpl/BURT-JDIT/ws/VNifV2SOAP.

Instalación

Puesta en marcha en cinco minutos

1. Sube tu certificado al servidor, fuera del repositorio y fuera de cualquier carpeta pública. Por ejemplo /etc/aeat/certificado.p12 con permisos 0600.

2. Pon la contraseña en el entorno, nunca en el código ni en el repositorio:

   Si no defines AEAT_VNIF_CERT_PASSWORD, el ejecutable la pedirá por teclado sin eco.

3. Ejecuta el diagnóstico. Comprueba extensiones, lee el certificado, mira la caducidad y abre una conexión TLS con el endpoint. No consulta ningún NIF.

4. Haz tu primera consulta.

(Los NIF y nombres de esta documentación son inventados.)

Uso manual con el ejecutable

Formato del CSV, una línea por contribuyente:

Se admite una cabecera que empiece por NIF, líneas vacías y comentarios con #.

Códigos de salida: 0 consulta realizada (sea cual sea el resultado de la AEAT), 1 error de uso o de configuración, 2 fallo transitorio (red, timeout, NO PROCESADO), 3 fallo definitivo.

Opciones: --endpoint=, --timeout=, --retries=, --batch-size=, --json, --no-probe (en doctor). También se leen de AEAT_VNIF_ENDPOINT, AEAT_VNIF_TIMEOUT, AEAT_VNIF_RETRIES y AEAT_VNIF_BATCH_SIZE.

Uso en código

Las opciones se pasan con VnifOptions:

Excepciones, todas bajo Iberfacil\AeatVnif\Exceptions\AeatVnifException:

Ninguna excepción incluye la contraseña, el contenido del certificado, el XML ni el texto que devuelva la AEAT.

Cómo interpretar cada resultado

CheckResult expone result (enum IdentificationResult), aeatResult (el literal), sentName, censusName, nameWasCorrected(), censusNameHasAccents(), raw y failure.

• IDENTIFICADO con el nombre corregido. Comprobado contra el servicio real: si envías «LUMINA ZEFIRA» y en el censo consta «LUMINÁ PERALVILLO ZÉFIRA», la AEAT responde IDENTIFICADO y devuelve el nombre censal completo, con tildes y a veces con espacios de relleno. Por eso el paquete casa la respuesta por NIF, nunca por nombre, y nameWasCorrected() devuelve true cuando las letras difieren (tildes y relleno solos no cuentan; para eso está censusNameHasAccents()). Guarda censusName si necesitas el nombre exacto.
• NO IDENTIFICADO-SIMILAR. El NIF existe; el nombre se parece pero no lo bastante. censusName trae el nombre censal y nameWasCorrected() es true. Suele ser un apellido mal escrito o un nombre compuesto a medias.
• NO IDENTIFICADO. censusName es null. O el NIF no existe o el nombre no se parece en nada.
• IDENTIFICADO-BAJA / IDENTIFICADO-REVOCADO. isIdentified() es true, pero mira result antes de dar el NIF por operativo.
• NO PROCESADO. En checkBatch() llega como resultado con failure (no tira el lote); en check() se lanza TransientFailure.

Uso en Laravel

El proveedor se autodescubre. Publica la configuración si quieres tocarla:

.env:

O inyecta Iberfacil\AeatVnif\VnifClient donde lo necesites. Comandos:

Eventos (Iberfacil\AeatVnif\Laravel\Events\*): VnifRequestStarting, VnifRequestCompleted y VnifRequestFailed, uno por petición HTTP, con el hash del XML, los NIF enviados y el recuento de resultados. Desactívalos con AEAT_VNIF_EVENTS=false.

Para sustituir el transporte, el normalizador o la caché, haz bind de Contracts\Transport, Contracts\NameNormalizer o Contracts\ResultCache en tu proveedor antes de que se resuelva el cliente.

Personalización

Antes y después de cada consulta (auditoría a tu manera):

O implementa Contracts\CheckObserver en una clase. VnifRequest expone los NIF y nombres enviados por si tu auditoría los necesita; decide tú qué guardas.

Caché (interfaz Contracts\ResultCache): Cache\InMemoryResultCache para una ejecución, Cache\Psr16ResultCache sobre cualquier PSR-16, o la tuya. Nunca se guarda un NO PROCESADO.

Normalizador de nombres (interfaz Contracts\NameNormalizer): el de serie pasa a mayúsculas, quita tildes y diéresis (conserva la Ñ), convierte guiones en espacios, elimina puntuación y compacta espacios. Si necesitas otras reglas, inyecta el tuyo.

Transporte (interfaz Contracts\Transport): el de serie es Transport\CurlTransport (mTLS, solo HTTPS, sin redirecciones, timeout de conexión y total, proxy y bundle CA opcionales). Implementa la interfaz para usar tu cliente PSR-18 o Guzzle. Para tests, Transport\FakeTransport encola respuestas y registra lo enviado.

Certificado (interfaz Contracts\Certificate): Certificate\Pkcs12Certificate y Certificate\PemCertificate, o CertificateLoader::fromFile() que decide por ti. El certificado se convierte en memoria a PEM temporales en un directorio 0700 con ficheros 0600, la clave se reexporta cifrada con una frase aleatoria, y todo se borra en finally (y en el destructor, por si acaso).

Límites y buenas prácticas

• El servicio admite hasta 10 000 contribuyentes por petición; el paquete trocea automáticamente. En un mismo lote, un NIF repetido con nombre distinto va en peticiones separadas (la respuesta se casa por NIF).
• No hagas consultas desde una petición web síncrona: ponlas en una cola o un proceso de fondo. El endpoint puede tardar.
• Base legitimadora. Consultar el censo trata datos personales del tercero. Necesitas una base legítima (normalmente el cumplimiento de obligaciones tributarias o contractuales) y un fin concreto. No lo uses para curiosear.
• Minimización. Consulta solo los NIF que necesitas, y guarda solo lo que necesites del resultado.
• Evidencia. Conserva fecha, NIF, resultado, nombre censal si lo usas y el hash SHA-256 del XML enviado (lo tienes en VnifRequest). Sirve para justificar por qué diste un NIF por bueno.
• Nunca guardes la contraseña del certificado en el código, en el repositorio ni en logs; nunca la pases como argumento en la línea de comandos.
• El paquete no registra nada por sí mismo. Lo que se audita lo decides tú con los observadores.

Cómo actualizar

El paquete sigue versionado semántico: las versiones 1.x no rompen la API pública; los cambios están en CHANGELOG.md. Tras actualizar, vuelve a ejecutar aeat-vnif doctor.

Desarrollo

Las pruebas no tocan la red: usan FakeTransport, respuestas de ejemplo con NIF y nombres inventados, y un certificado autofirmado que se genera en memoria durante los tests. Ver AGENTS.md.

Licencia

MIT. Copyright (c) 2026 Marco Gavilán — IBERFÁCIL. Ver LICENSE.