Huella (hash) y encadenamiento en Verifactu: cómo se calculan

La huella de Verifactu es un hash SHA-256, en hexadecimal y mayúsculas, que se calcula sobre unos campos concretos de cada registro de facturación concatenados como nombre=valor separados por &. Entre esos campos está la huella del registro anterior del mismo obligado, y así queda la cadena (encadenamiento). Con la API Verifactu no la calculas tú: Verifacti la genera y te la devuelve en la respuesta.

La huella y el encadenamiento los exigen el RD 1007/2023 y la Orden HAC/1177/2024, en vigor; el cálculo lo detalla la AEAT en sus especificaciones de la huella (v0.1.2).

Qué exige la norma

La norma busca integridad y trazabilidad: cada registro de facturación lleva su propia huella y la del registro anterior. Si alguien altera un registro, su huella deja de cuadrar con la que guarda el siguiente. No confundir el encadenamiento con la numeración correlativa de las facturas: son cosas distintas. Qué es un registro de facturación y qué contiene, en la estructura del XML de Verifactu.

Qué campos entran en la huella

Campos que entran en la huella de Verifactu
RegistroCampos, en este orden
AltaIDEmisorFactura · NumSerieFactura · FechaExpedicionFactura · TipoFactura · CuotaTotal · ImporteTotal · Huella (del registro anterior; vacía en el primero) · FechaHoraHusoGenRegistro
AnulaciónIDEmisorFacturaAnulada · NumSerieFacturaAnulada · FechaExpedicionFacturaAnulada · Huella (del registro anterior) · FechaHoraHusoGenRegistro

AEAT, especificaciones técnicas de la huella o hash (v0.1.2)

Cómo se calcula, paso a paso

  1. Concatena los campos como nombre=valor, en el orden de la tabla, separados por &.
  2. Usa cada valor tal como lo registra la AEAT: sin escapar (&, no &), sin espacios al principio ni al final y con el mismo formato de importe que en el XML (si el XML lleva 12.35, la cadena lleva 12.35).
  3. En el primer registro del obligado, deja vacío el valor de Huella (Huella=).
  4. Aplica SHA-256 a la cadena codificada en UTF-8.
  5. Pasa el resultado a hexadecimal en mayúsculas: 64 caracteres. Esa es la huella que va en el elemento Huella del registro, con TipoHuella 01.

Ejemplo para comprobar tu cálculo

El primer registro es el ejemplo de las especificaciones de la AEAT; el segundo se encadena a él. Si tu código da estas dos huellas, calcula bien.

Primer registro (Huella vacía)
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

→ 3C464DAF61ACB827C65FDA19F352A4E3BDC2C640E9E9FC4CC058073F38F12F60
Segundo registro (Huella del primero)
IDEmisorFactura=89890001K&NumSerieFactura=12345679/G34&FechaExpedicionFactura=01-01-2024&TipoFactura=F1&CuotaTotal=12.35&ImporteTotal=123.45&Huella=3C464DAF61ACB827C65FDA19F352A4E3BDC2C640E9E9FC4CC058073F38F12F60&FechaHoraHusoGenRegistro=2024-01-01T19:20:35+01:00

→ F7B94CFD8924EDFF273501B01EE5153E4CE8F259766F88CF6ACB8935802A2B97

El cálculo en PHP, Python y C#

PHP
<?php
function huellaAlta(array $r, string $anterior): string
{
    $cadena = 'IDEmisorFactura=' . $r['IDEmisorFactura']
        . '&NumSerieFactura=' . $r['NumSerieFactura']
        . '&FechaExpedicionFactura=' . $r['FechaExpedicionFactura']
        . '&TipoFactura=' . $r['TipoFactura']
        . '&CuotaTotal=' . $r['CuotaTotal']
        . '&ImporteTotal=' . $r['ImporteTotal']
        . '&Huella=' . $anterior
        . '&FechaHoraHusoGenRegistro=' . $r['FechaHoraHusoGenRegistro'];
    return strtoupper(hash('sha256', $cadena));
}

$primera = huellaAlta([
    'IDEmisorFactura' => '89890001K',
    'NumSerieFactura' => '12345678/G33',
    'FechaExpedicionFactura' => '01-01-2024',
    'TipoFactura' => 'F1',
    'CuotaTotal' => '12.35',
    'ImporteTotal' => '123.45',
    'FechaHoraHusoGenRegistro' => '2024-01-01T19:20:30+01:00',
], '');
echo $primera . "\n"; // 3C464DAF61ACB827C65FDA19F352A4E3BDC2C640E9E9FC4CC058073F38F12F60

$segunda = huellaAlta([
    'IDEmisorFactura' => '89890001K',
    'NumSerieFactura' => '12345679/G34',
    'FechaExpedicionFactura' => '01-01-2024',
    'TipoFactura' => 'F1',
    'CuotaTotal' => '12.35',
    'ImporteTotal' => '123.45',
    'FechaHoraHusoGenRegistro' => '2024-01-01T19:20:35+01:00',
], $primera);
echo $segunda . "\n";
Python
import hashlib


def huella_alta(r, anterior):
    cadena = "&".join([
        f"IDEmisorFactura={r['IDEmisorFactura']}",
        f"NumSerieFactura={r['NumSerieFactura']}",
        f"FechaExpedicionFactura={r['FechaExpedicionFactura']}",
        f"TipoFactura={r['TipoFactura']}",
        f"CuotaTotal={r['CuotaTotal']}",
        f"ImporteTotal={r['ImporteTotal']}",
        f"Huella={anterior}",
        f"FechaHoraHusoGenRegistro={r['FechaHoraHusoGenRegistro']}",
    ])
    return hashlib.sha256(cadena.encode("utf-8")).hexdigest().upper()


primera = huella_alta({
    "IDEmisorFactura": "89890001K",
    "NumSerieFactura": "12345678/G33",
    "FechaExpedicionFactura": "01-01-2024",
    "TipoFactura": "F1",
    "CuotaTotal": "12.35",
    "ImporteTotal": "123.45",
    "FechaHoraHusoGenRegistro": "2024-01-01T19:20:30+01:00",
}, "")
print(primera)  # 3C464DAF61ACB827C65FDA19F352A4E3BDC2C640E9E9FC4CC058073F38F12F60

segunda = huella_alta({
    "IDEmisorFactura": "89890001K",
    "NumSerieFactura": "12345679/G34",
    "FechaExpedicionFactura": "01-01-2024",
    "TipoFactura": "F1",
    "CuotaTotal": "12.35",
    "ImporteTotal": "123.45",
    "FechaHoraHusoGenRegistro": "2024-01-01T19:20:35+01:00",
}, primera)
print(segunda)
C# (.NET 6+)
using System.Security.Cryptography;
using System.Text;

static string HuellaAlta(Dictionary<string, string> r, string anterior)
{
    var cadena = $"IDEmisorFactura={r["IDEmisorFactura"]}"
        + $"&NumSerieFactura={r["NumSerieFactura"]}"
        + $"&FechaExpedicionFactura={r["FechaExpedicionFactura"]}"
        + $"&TipoFactura={r["TipoFactura"]}"
        + $"&CuotaTotal={r["CuotaTotal"]}"
        + $"&ImporteTotal={r["ImporteTotal"]}"
        + $"&Huella={anterior}"
        + $"&FechaHoraHusoGenRegistro={r["FechaHoraHusoGenRegistro"]}";
    return Convert.ToHexString(SHA256.HashData(Encoding.UTF8.GetBytes(cadena)));
}

var registro = new Dictionary<string, string>
{
    ["IDEmisorFactura"] = "89890001K",
    ["NumSerieFactura"] = "12345678/G33",
    ["FechaExpedicionFactura"] = "01-01-2024",
    ["TipoFactura"] = "F1",
    ["CuotaTotal"] = "12.35",
    ["ImporteTotal"] = "123.45",
    ["FechaHoraHusoGenRegistro"] = "2024-01-01T19:20:30+01:00",
};
var primera = HuellaAlta(registro, "");
Console.WriteLine(primera); // 3C464DAF61ACB827C65FDA19F352A4E3BDC2C640E9E9FC4CC058073F38F12F60

registro["NumSerieFactura"] = "12345679/G34";
registro["FechaHoraHusoGenRegistro"] = "2024-01-01T19:20:35+01:00";
Console.WriteLine(HuellaAlta(registro, primera));

Cómo se encadena

El primer registro de un obligado lleva PrimerRegistro con valor S y la huella anterior vacía. Los siguientes llevan RegistroAnterior con el IDEmisorFactura, el NumSerieFactura, la FechaExpedicionFactura y la Huella del registro anterior. Hay una cadena por obligado (NIF) y sistema informático, y en ella entran tanto las altas como las anulaciones, en el orden en que se generan. Dónde va cada elemento, en la estructura del XML.

Huella de un registro de anulación

La anulación tiene sus propios campos: IDEmisorFacturaAnulada, NumSerieFacturaAnulada, FechaExpedicionFacturaAnulada, la Huella del registro anterior y FechaHoraHusoGenRegistro. Se calcula igual que la de un alta, y la siguiente alta se encadena a ella.

Huella y encadenamiento con la API Verifactu

La respuesta de POST /verifactu/create incluye la huella. Verifacti guarda la última huella de cada NIF y genera sus registros de uno en uno, para que la cadena no se bifurque aunque envíes facturas en paralelo. Si cambias la identidad del sistema informático de facturación del NIF (sistema_informatico), empieza una cadena nueva. Cada caso, en los ejemplos de Verifactu.

Respuesta de POST /verifactu/create · 200
{
  "estado": "Pendiente",
  "uuid": "b018ced3-b362-4494-8776-9eefff1c160c",
  "url": "https://prewww2.aeat.es/wlpl/TIKE-CONT/ValidarQR?nif=B12345674&numserie=A1&fecha=19-11-2026&importe=242.00",
  "qr": "iVBORw0KGgoAAAANSUhEUgAAASIAAAEi...",
  "huella": "B11F3A015173AD99075E2720F61E2DE1FF08CBFEDD85C6F73C77AD835301B2A3"
}

Errores que rompen la cadena

Errores que rompen la cadena de huellas de Verifactu
ErrorSíntomaSolución
Calcular sobre valores escapadosLa huella no coincide si hay & u otros caracteres especialesCalcula sobre el valor sin escapar
Formato de importes distinto del XMLLa huella no cuadra con el registroUsa en la cadena el mismo texto que en el XML (12.35 no es 12.350)
FechaHoraHusoGenRegistro distinta de la del XMLLa huella no cuadra con el registroUsa el mismo valor en la cadena y en el registro
Dos registros simultáneos que leen la misma huella anteriorDos registros apuntan al mismo anterior y la cadena se bifurcaGenera los registros de cada NIF de uno en uno
Perder la huella del último registroNo puedes encadenar el siguienteGuarda la huella del último registro de cada NIF

Los errores que devuelven la API y la AEAT, en errores de Verifactu.

Siguiente paso

Con la API Verifactu no calculas la huella ni guardas la cadena: Verifacti lo hace por cada NIF y te devuelve la huella en la respuesta. Empieza con la guía rápida o la documentación.

Entorno de test y NIF de prueba incluidos

Preguntas sobre la huella de Verifactu

Más preguntas sobre la API Verifactu

¿Qué algoritmo usa la huella de Verifactu?

SHA-256 (TipoHuella 01), expresado en hexadecimal y mayúsculas.

¿La huella va impresa en la factura?

No. En la factura va el QR. La huella va en el registro de facturación que se envía a la AEAT.

¿Qué pasa si se rompe la cadena?

La AEAT acepta esos registros con errores (huella que no coincide, encadenamiento incorrecto) y hay que subsanarlos. Corrige el origen (la huella anterior que se usó) antes de seguir enviando.

¿El encadenamiento es lo mismo que la numeración correlativa?

No. La numeración correlativa es de las facturas; el encadenamiento une cada registro de facturación con el anterior mediante su huella.

¿Tengo que guardar la huella si uso la API?

No para encadenar: lo hace Verifacti por cada NIF. Puedes guardarla como referencia, porque viene en la respuesta.

Deja la huella a la API

Prueba con la cuenta gratuita: la respuesta trae la huella ya encadenada.

Entorno de test y NIF de prueba incluidosLee la documentación