Qué publican en GitHub los proyectos Verifactu de código abierto, y cuánto cumple

Auditamos los registros de facturación Verifactu que publican en GitHub los proyectos de código abierto. De los 35 ficheros que pretenden ser registros válidos, 10 tienen al menos un error, y el más repetido es el más delicado: una huella que no coincide con los datos del propio registro. Lo grave es otra cosa: casi nadie publica una cadena de registros ni un ejemplo hecho para fallar. Si tu proyecto se prueba contra lo que circula, se prueba contra muy poco.

Por qué mirar lo que publican los demás

Desde el 29 de julio de 2025, quien fabrica un sistema informático de facturación tiene que poder declarar que cumple el RD 1007/2023 y la Orden HAC/1177/2024. El núcleo de esa obligación es técnico: cada registro de facturación lleva una huella SHA-256 calculada sobre ocho de sus campos (cinco en un registro de anulación), entre ellos la huella del registro anterior. Así la secuencia queda encadenada y cualquier alteración se nota.

Buena parte del software Verifactu que se escribe hoy es pequeño y abierto: módulos para ERP libres y librerías en PHP, Python, Go, C# o TypeScript. Esos proyectos publican ejemplos, ficheros de test y salidas de sus generadores, y otros desarrolladores los copian como referencia. Quisimos saber si esos registros cumplen la norma y, cuando no, qué reglas fallan.

Cómo lo hicimos

Recorrimos GitHub con sus dos buscadores. Con el de código buscamos los elementos del registro (RegistroAlta, RegistroAnulacion, RegistroEvento…) en ficheros XML; con el de repositorios, la palabra «verifactu». De cada repositorio bajamos todos sus XML, fijados a un commit.

Antes de auditar nada clasificamos cada fichero. No es lo mismo un ejemplo que pretende ser válido que un test escrito para fallar, una respuesta de la AEAT o una plantilla con huecos. Solo los primeros cuentan. Después los pasamos por verifactu-lint, el linter de código abierto que mantenemos en EasyByte.

Dos advertencias antes de seguir. La primera: EasyByte desarrolla esa herramienta y ofrece servicios relacionados con Verifactu, así que tenemos interés en el tema. La segunda: el estudio lo han hecho agentes de IA, desde la recogida hasta la redacción. El agente revisó uno a uno los errores contra el texto literal de la norma y recalculó cada huella con una implementación independiente. Ninguna persona experta ha revisado los hallazgos. Por eso publicamos el método, los scripts y los datos: cualquiera puede repetirlo.

Casi nadie publica registros reales

De los 1.008 repositorios que hablan de Verifactu, solo 19 publican al menos un registro que pretenda ser válido.

Lo más numeroso son plantillas: 91 ficheros con valores de relleno, la mayoría copias de los ejemplos del documento de la AEAT que describe el servicio web. Esos ejemplos son ilustrativos y se nota: en la huella pone literalmente <Huella>Huella</Huella> y el NIF es AAAA o NNNN. Muchos están guardados en carpetas tests/, fixtures/ o examples/, al lado de los ficheros de prueba de verdad.

No es un error de quien los copia, ni de la AEAT. Pero un test que «parsea el ejemplo oficial» pasa igual tanto si el cálculo de la huella del proyecto está bien como si no.

Unas tres de cada diez referencias reales fallan

Quedaron 35 ficheros que sí pretenden ser registros válidos, con 36 registros entre todos: 21 altas, 4 anulaciones y 11 eventos. De esos ficheros, 10 tienen al menos un error (28,6 %; intervalo de confianza del 95 %: 16,3–45,1 %), 4 tienen algún aviso y 15 no tienen ningún hallazgo.

Por repositorios, 6 de los 19 (31,6 %; IC 95 %: 15,4–54,0 %) publican al menos un registro de referencia con algún error, siempre en un fichero que no aparece en ningún repositorio más antiguo del corpus. Con 19 repositorios los intervalos son anchos y no se puede afinar más.

La huella, de lejos el error más repetido

En 5 de los 19 repositorios, la huella declarada no coincide con la que sale de los campos del propio registro. Las causas que pudimos reconstruir son poco espectaculares:

• Una huella copiada de la documentación de la AEAT y puesta en un registro con otros datos.
• Un generador que escribe la huella en minúsculas, cuando la AEAT pide hexadecimal en mayúsculas, y que además genera la fecha y hora sin huso horario.
• Una anulación escrita con los nombres de elemento de un alta: los campos que entran en la huella quedan vacíos.

Un sexto repositorio usa una estructura inventada que no se parece al esquema oficial, con la huella metida en un elemento que no existe. De ahí salen el resto de errores: falta la identificación del sistema, el tipo de factura o el desglose. Hubo además una cuota que no sale de su base y su tipo, y una factura completa (F1) sin destinatario, que la AEAT exige.

Los errores de huella no se detectan validando contra el XSD: el esquema comprueba que haya un campo Huella de hasta 64 caracteres, pero no calcula ningún SHA-256. Y la AEAT tampoco rechaza el registro. Según sus validaciones, devuelve «un aviso de error (no generará rechazo)». El registro entra marcado y solo lo ve quien lo envía.

Lo que no está en los ejemplos

La cadena casi no aparece. De los 35 ficheros válidos, 34 contienen un solo registro, y 11 vienen de un mismo repositorio. Los ejemplos XML públicos casi nunca contienen una cadena, así que no sirven de referencia para ella. No medimos si los proyectos prueban el encadenamiento en su código.

No hay ejemplos hechos para fallar. En ninguno de los 63 repositorios de terceros encontramos un registro deliberadamente inválido, guardado para comprobar que un validador lo rechaza. Los cuatro que nuestra primera clasificación tomó por tests negativos resultaron ser ficheros de referencia válidos.

Lo que el estudio dice de nuestra propia herramienta

El agente revisó los 22 errores y no encontró ningún falso positivo. No son 22 casos independientes: 10 salen de dos ficheros del mismo generador. Contando las 12 situaciones distintas (repositorio y regla), la tasa de falsos positivos queda por debajo del 24 % con un 95 % de confianza; no se puede afirmar que sea cero. La implementación independiente la escribió el mismo equipo: descarta fallos de programación, pero no una lectura equivocada de la especificación que compartan las dos.

También encontramos seis mejoras para verifactu-lint:

• dos huecos de cobertura: no revisa el formato de las fechas ni si la hora lleva huso horario;
• dos diagnósticos engañosos;
• un aviso que debería ser «no determinable»;
• una mejora de usabilidad.

Están publicadas con el estudio: encontrar los límites del propio instrumento también es un resultado.

Límites

• Cobertura de los buscadores: los de GitHub no lo ven todo. Solo la rama principal, ficheros de menos de 384 KB y, en general, ningún fork.
• Ejemplos, no producción: lo que se publica como ejemplo no es lo que un sistema emite en producción. El estudio mide las referencias que circulan, no la facturación de nadie.
• Cotas inferiores: la herramienta cubre solo una parte de la norma, así que las tasas de error son cotas inferiores.
• Anonimato: los repositorios aparecen anonimizados y no hemos contactado a sus mantenedores.

Para cerrar

Ninguna corrección individual cambiaría mucho este panorama. Falta un conjunto compartido y con licencia abierta de cadenas de varios registros, unas válidas y otras rotas a propósito, cada una con el error que debe producir. Así cada proyecto podría probar su generador contra algo más exigente que un ejemplo con la palabra «Huella» donde debería ir un hash.

Si quieres comprobar los registros que genera tu programa, el validador de registros Verifactu corre verifactu-lint en tu navegador y el XML no sale de tu equipo. El método completo, los scripts y los datos agregados están en el estudio S1 de EasyByte Lab.

Las cifras corresponden a lo publicado en GitHub a 2 de octubre de 2026.