Hash (huella) and chaining in Verifactu: how they are computed

The Verifactu hash (huella) is a SHA-256 hash, in uppercase hexadecimal, computed over specific fields of each invoicing record joined as name=value pairs separated by &. One of those fields is the hash of the same taxpayer's previous record, which forms the chain. With the Verifactu API you don't compute it: Verifacti generates it and returns it in the response.

The hash and the chaining are required by RD 1007/2023 and Order HAC/1177/2024, in force; the AEAT details the computation in its hash specification (v0.1.2).

What the rules require

The rules aim at integrity and traceability: each invoicing record carries its own hash and the previous record's. If someone alters a record, its hash no longer matches the one stored in the next. Don't confuse chaining with the sequential numbering of invoices: they are different things. What an invoicing record is and what it holds, in the Verifactu XML structure.

Which fields go into the hash

Fields that go into the Verifactu hash
RecordFields, in this order
Registration (alta)IDEmisorFactura · NumSerieFactura · FechaExpedicionFactura · TipoFactura · CuotaTotal · ImporteTotal · Huella (of the previous record; empty in the first) · FechaHoraHusoGenRegistro
Cancellation (anulación)IDEmisorFacturaAnulada · NumSerieFacturaAnulada · FechaExpedicionFacturaAnulada · Huella (of the previous record) · FechaHoraHusoGenRegistro

AEAT, technical specification of the hash (v0.1.2)

How it is computed, step by step

  1. Join the fields as name=value, in the order of the table, separated by &.
  2. Use each value as the AEAT stores it: unescaped (&, not &), with no leading or trailing spaces and the same amount format as in the XML (if the XML has 12.35, the string has 12.35).
  3. In the taxpayer's first record, leave the Huella value empty (Huella=).
  4. Apply SHA-256 to the UTF-8 encoded string.
  5. Write the result in uppercase hexadecimal: 64 characters. That is the hash in the record's Huella element, with TipoHuella 01.

Example to check your computation

The first record is the example in the AEAT specification; the second is chained to it. If your code produces these two hashes, it computes correctly.

First record (empty Huella)
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
Second record (Huella of the first)
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

The computation in PHP, Python and 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));

How the chain works

A taxpayer's first record carries PrimerRegistro with value S and an empty previous hash. The following ones carry RegistroAnterior with the IDEmisorFactura, NumSerieFactura, FechaExpedicionFactura and Huella of the previous record. There is one chain per taxpayer (NIF) and invoicing system, and it includes both registrations and cancellations, in the order they are generated. Where each element goes, in the XML structure.

Hash of a cancellation record

A cancellation has its own fields: IDEmisorFacturaAnulada, NumSerieFacturaAnulada, FechaExpedicionFacturaAnulada, the previous record's Huella and FechaHoraHusoGenRegistro. It is computed like a registration's, and the next registration chains to it.

Hash and chaining with the Verifactu API

The POST /verifactu/create response includes the huella. Verifacti keeps the last hash of each NIF and generates its records one at a time, so the chain never forks even if you send invoices in parallel. If you change the NIF's invoicing-system identity (sistema_informatico), a new chain starts. Every case, in the Verifactu examples.

POST /verifactu/create response · 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"
}

Mistakes that break the chain

Mistakes that break the Verifactu hash chain
MistakeSymptomFix
Computing over escaped valuesThe hash doesn't match when there is an & or another special characterCompute over the unescaped value
Amount format different from the XMLThe hash does not match the recordUse the same text in the string as in the XML (12.35 is not 12.350)
FechaHoraHusoGenRegistro different from the XMLThe hash does not match the recordUse the same value in the string and the record
Two simultaneous records reading the same previous hashTwo records point to the same previous one and the chain forksGenerate each NIF's records one at a time
Losing the hash of the last recordYou cannot chain the next oneStore each NIF's last hash

The errors returned by the API and the AEAT, in Verifactu errors.

Next step

With the Verifactu API you don't compute the hash or keep the chain: Verifacti does it per NIF and returns the hash in the response. Start with the quick start guide or the documentation.

Test environment and test NIF included

Questions about the Verifactu hash

More questions about the Verifactu API

Which algorithm does the Verifactu hash use?

SHA-256 (TipoHuella 01), written in uppercase hexadecimal.

Is the hash printed on the invoice?

No. The invoice carries the QR. The hash goes in the invoicing record sent to the AEAT.

What happens if the chain breaks?

The AEAT accepts those records with errors (hash mismatch, wrong chaining) and they have to be corrected. Fix the source (the previous hash that was used) before sending more.

Is chaining the same as sequential numbering?

No. Sequential numbering is about invoices; chaining links each invoicing record to the previous one through its hash.

Do I need to store the hash if I use the API?

Not for chaining: Verifacti does it per NIF. You can keep it as a reference, since it comes in the response.

Leave the hash to the API

Try it with the free account: the response carries the hash, already chained.

Test environment and test NIF includedRead the documentation