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
| Registro | Campos, en este orden |
|---|---|
| Alta | IDEmisorFactura · NumSerieFactura · FechaExpedicionFactura · TipoFactura · CuotaTotal · ImporteTotal · Huella (del registro anterior; vacía en el primero) · FechaHoraHusoGenRegistro |
| Anulación | IDEmisorFacturaAnulada · 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
- Concatena los campos como
nombre=valor, en el orden de la tabla, separados por&. - 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 lleva12.35, la cadena lleva12.35). - En el primer registro del obligado, deja vacío el valor de
Huella(Huella=). - Aplica SHA-256 a la cadena codificada en UTF-8.
- Pasa el resultado a hexadecimal en mayúsculas: 64 caracteres. Esa es la huella que va en el elemento
Huelladel registro, conTipoHuella01.
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.
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
→ 3C464DAF61ACB827C65FDA19F352A4E3BDC2C640E9E9FC4CC058073F38F12F60IDEmisorFactura=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
→ F7B94CFD8924EDFF273501B01EE5153E4CE8F259766F88CF6ACB8935802A2B97El cálculo en PHP, Python y C#
<?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";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)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.
{
"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
| Error | Síntoma | Solución |
|---|---|---|
| Calcular sobre valores escapados | La huella no coincide si hay & u otros caracteres especiales | Calcula sobre el valor sin escapar |
| Formato de importes distinto del XML | La huella no cuadra con el registro | Usa en la cadena el mismo texto que en el XML (12.35 no es 12.350) |
FechaHoraHusoGenRegistro distinta de la del XML | La huella no cuadra con el registro | Usa el mismo valor en la cadena y en el registro |
| Dos registros simultáneos que leen la misma huella anterior | Dos registros apuntan al mismo anterior y la cadena se bifurca | Genera los registros de cada NIF de uno en uno |
| Perder la huella del último registro | No puedes encadenar el siguiente | Guarda 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.
Otros tutoriales de Verifactu
Preguntas sobre la huella de Verifactu
Más preguntas sobre la API Verifactu¿Qué algoritmo usa la huella de Verifactu?
TipoHuella 01), expresado en hexadecimal y mayúsculas.¿La huella va impresa en la factura?
¿Qué pasa si se rompe la cadena?
¿El encadenamiento es lo mismo que la numeración correlativa?
¿Tengo que guardar la huella si uso la API?
Deja la huella a la API
Prueba con la cuenta gratuita: la respuesta trae la huella ya encadenada.