La huella de un registro Verifactu

1. El algoritmo y la cadena canónica

El algoritmo es SHA-256, y a día de hoy es el único permitido. La entrada es una cadena de texto codificada en UTF-8. La salida va en hexadecimal, en mayúsculas, y siempre ocupa 64 caracteres.

Los campos que entran en el cálculo se concatenan así:

nombreCampo1=valorCampo1&nombreCampo2=valorCampo2&…&nombreCampoN=valorCampoN

Uno de esos campos es Huella y contiene la huella del registro anterior. Ahí está el encadenamiento: el registro N incorpora el hash del N−1, así que alterar un registro pasado invalida todos los posteriores. En el primero de un sistema de facturación no hay anterior, así que el campo va vacío, pero la huella del registro sí debe calcularse e informarse igualmente.

// La huella de un registro de alta. El campo Huella es la del registro ANTERIOR:
// va vacío en el primero de la cadena.
const campos = [
  ["IDEmisorFactura", "89890001K"],
  ["NumSerieFactura", "12345678/G33"],
  ["FechaExpedicionFactura", "01-01-2024"],
  ["TipoFactura", "F1"],
  ["CuotaTotal", "12.35"],
  ["ImporteTotal", "123.45"],
  ["Huella", ""],
  ["FechaHoraHusoGenRegistro", "2024-01-01T19:20:30+01:00"],
];

const cadena = campos.map(([k, v]) => `${k}=${v}`).join("&");

const bytes = new TextEncoder().encode(cadena);          // UTF-8
const digest = await crypto.subtle.digest("SHA-256", bytes);

const huella = [...new Uint8Array(digest)]
  .map((b) => b.toString(16).padStart(2, "0"))
  .join("")
  .toUpperCase();                                        // 64 caracteres

// 3C464DAF61ACB827C65FDA19F352A4E3BDC2C640E9E9FC4CC058073F38F12F60

2. Los campos, y en qué orden van

El orden no es negociable: es el de aparición en los diseños de registro del anexo de la orden, y cualquier permuta da una huella distinta. Hay tres juegos de campos según el tipo de registro.

Registro de alta

Registro de anulación

Registro de evento

3. Reglas de formato de los valores

El valor de cada campo es el que lleva el XML, pero con tres matices que provocan casi todos los fallos de huella:

• Se recortan los espacios de los extremos, no los de dentro. Si el XML trae <NumSerieFactura> 12345678 / G33 </NumSerieFactura>, el valor es 12345678 / G33, con sus espacios interiores intactos.
• Un campo ausente o vacío escribe solo su nombre y el «=». Sin valor detrás: …&Huella=&FechaHoraHusoGenRegistro=…
• En los importes, una o dos posiciones decimales dan igual. La norma dice que los ceros a la derecha no son relevantes: 123.1 y 123.10 se consideran ambos válidos. Producen hashes distintos, pero la AEAT acepta los dos. Un verificador que solo pruebe el literal del XML dará falsos negativos.

4. Vectores de prueba oficiales

Son los tres ejemplos del documento de la AEAT. Si tu implementación reproduce estas tres huellas, el cálculo es correcto. Cotejo los tiene congelados como tests.

Fíjate en cómo la huella del caso 1 aparece dentro de la cadena del caso 2, y la del 2 dentro de la del 3. Eso es la cadena.

5. Fuentes oficiales

Todo lo anterior sale del documento de la AEAT, que es la fuente de verdad. Si algo de esta página lo contradice, mándanos un aviso: tiene razón él.

• Detalle de las especificaciones técnicas para generación de la huella o «hash» de los registros de facturación (v0.1.2, 27/08/2024)
• Sistemas Informáticos de Facturación (SIF) y VERI*FACTU, sede electrónica de la AEAT

El marco legal es el Real Decreto 1007/2023 y la Orden HAC/1177/2024.

La otra mitad de la norma es el código impreso en la factura: el código QR de Verifactu.