verifactu — librería open source para VeriFactu (AEAT)

Qué es

VeriFactu es el reglamento antifraude (Ley 11/2021 · RD 1007/2023 · Orden HAC/1177/2024) que obliga a que el software de facturación garantice la inalterabilidad de los registros mediante una huella encadenada y un QR verificable por la AEAT. Entra en vigor el 1-ene-2027 (sociedades) y 1-jul-2027 (resto).

verifactu implementa ese núcleo de forma abierta para que cualquiera lo integre y compruebe que cumple.

Cómo funciona

VeriFactu es un sistema antifraude: una vez emites una factura, no debe poderse alterar ni borrar sin que quede rastro. El mecanismo:

Un registro por factura. Al emitir o anular, el software genera un registro con los datos clave (emisor, nº de serie, fecha, desglose de IVA, importe y destinatario).
Huella encadenada. A cada registro se le calcula una huella SHA-256 sobre sus campos más la huella del registro anterior. Si alguien altera una factura del pasado, las huellas siguientes dejan de cuadrar → la manipulación se detecta.
QR de cotejo. La factura lleva un QR con una URL a la AEAT y la leyenda «VERI*FACTU» para que cualquiera compruebe que está declarada.
Dos formas de cumplir. Veri*Factu: remitir cada registro en tiempo real al web service de la AEAT (certificado, TLS mutuo). No Veri*Factu: conservar los registros y firmarlos con XAdES.

verifactu implementa cada paso y añade un verificador que comprueba el cumplimiento antes de enviar.

Qué hace

Huella encadenada

SHA-256 canónica sobre los campos del registro + la huella anterior. Verificada dígito a dígito contra el vector oficial de la AEAT.

QR de cotejo

URL al servicio ValidarQR de la AEAT (pruebas/producción) con los 4 parámetros y formato exactos, nivel M.

Verificador `lint`

Cumplimiento completo: NIF con dígito de control, desglose de IVA, coherencia de importes, destinatarios, rectificativas y la cadena de huellas. CLI y API.

XML ✓ XSD oficial

Genera el RegFactuSistemaFacturacion (alta, anulación y lotes) con orden y namespaces correctos. Valida contra el SuministroLR.xsd oficial.

Envío + consulta

Remite al web service por TLS mutuo: registro único, lotes ≤1000 y series que se trocean solas. Más consulta de lo remitido.

Firma XAdES

Para el modo No Veri*Factu: firma enveloped del registro (XAdES) con tu certificado.

Atajos DX

crearAlta() y SerieManager encadenan la serie solos y sellan la hora (evitan el error AEAT 2004). Persistencia en memoria o fichero.

Servidor MCP

Binario verifactu-mcp incluido en el paquete: expone huella, lint, QR, validación de NIF y XML como herramientas para Claude y clientes MCP.

Skill de Claude

Guía la integración en cualquier repo y ejecuta el verificador de cumplimiento.

Instalar

# publicada en npm
npm install @inoguerols/verifactu

import { computeHuellaAlta, qrUrl, lint, xmlRegistroAlta, enviar } from '@inoguerols/verifactu'

// huella encadenada del registro de alta
const huella = computeHuellaAlta({
  IDEmisorFactura: '89890001K', NumSerieFactura: '12345678/G33',
  FechaExpedicionFactura: '01-01-2024', TipoFactura: 'F1',
  CuotaTotal: '12.35', ImporteTotal: '123.45',
  huellaAnterior: '', FechaHoraHusoGenRegistro: '2024-01-01T19:20:30+01:00',
})

// verificar el cumplimiento de una serie
const informe = lint(serie) // → { ok, incidencias[] }

O verifica una serie desde la terminal:

npx verifactu lint serie.json

Pruébalo

Calcula la huella canónica y el QR de cotejo en tu navegador (con crypto.subtle, igual que la librería). Nada sale de tu equipo.

NIF emisor (IDEmisorFactura)

Nº serie (NumSerieFactura)

Fecha expedición (dd-mm-yyyy)

Tipo factura

Cuota total

Importe total

Huella anterior (vacío = 1er registro)

Fecha-hora generación (ISO con huso)

Cadena canónica (lo que se hashea)

Huella · SHA-256 hex mayúsculas

URL de cotejo AEAT (entorno pruebas)

Escanea el QR o abre la URL: el QR que imprimes en la factura lleva exactamente este enlace.

El envío al web service de la AEAT necesita certificado (TLS mutuo) y no puede hacerse desde el navegador. Para eso usa el cliente enviar() en Node — ver el README.

Verificar el cumplimiento

El lint recalcula la cadena completa y marca lo que la AEAT rechazaría. Ejemplo de salida sobre una serie con un registro manipulado:

$ npx verifactu lint serie-manipulada.json
[error] #1 cadena-rota: La Huella no coincide con el recálculo (registro alterado)
NO CUMPLE — 2 registros, 1 errores, 0 avisos

Nivel	Qué prueba	Sin AEAT
Huella	Reproduce el vector oficial AEAT	✅
lint	Cadena intacta / registros sin alterar	✅
QR	URL y formato de cotejo correctos	✅
XML	Valida contra el XSD oficial	✅ (xmllint)
Web service	La AEAT acepta y registra el envío (CSV)	✅ (verificado en preproducción)