QR code and the invoice PDF

An invoice issued with a billing system carries a QR code that lets its recipient check it with AEAT (article 6.5 of the RD 1619/2012, and articles 20 and 21 of the Orden HAC/1177/2024). BeeL. prints that QR on the PDF it generates — once, centred at the top of the first page, at the size QRC-003 The QR measures between 30 mm and 40 mm sets, with «QR tributario:» above it and the legend below, both centred too — and also returns the QR data on the invoice.

The QR exists from PENDING

The QR is produced when the record is submitted, not when AEAT accepts it. As soon as an invoice reads submission_status: PENDING, its verifactu block already carries:

• qr_url — the AEAT validation link the QR encodes;
• qr_base64 — the QR as a base64-encoded PNG, ready to embed;
• invoice_hash — the fingerprint of the record.

They stay on the invoice whatever AEAT answers — including after a rejection. Their presence says the record was built, not that AEAT accepted it: read submission_status for that.

Before you render a document of the invoice, make sure the QR data is there: read the invoice until verifactu.qr_url is present, or wait for the invoice.pdf.generated webhook — see QRC-002 Wait for the QR before you distribute the PDF.

In sandbox the QR points to AEAT's test validation service; see Testing in sandbox.

The PDF and the QR

For an invoice under VeriFactu, BeeL. renders the PDF with the QR once the QR data exists. The invoice.pdf.generated webhook tells you when it is ready, and downloading the PDF waits for it rather than making you poll. An invoice outside VeriFactu (verifactu.enabled: false) never waits: its PDF has no QR.

The PDF is generated once, with the QR, and is never modified afterwards. Voiding the invoice or issuing a corrective for it does not change it and does not send invoice.pdf.generated again: the new status is in status and verifactu.submission_status, not in the document. Emailing the invoice before its PDF exists answers 202, and the email goes out when the PDF is stored — see Sending email.

If the submission never reaches AEAT

When the registration never produces a record — the submission was refused before reaching AEAT, or the invoice stays NOT_SUBMITTED — there is no QR data to print. An invoice whose registration was refused before reaching AEAT, or that was voided without being registered, has no PDF: downloading it, previewing it or emailing it with the PDF answers 400 INVOICE_NOT_REGISTERED_NO_PDF. The fix is to get the invoice registered, not to render around it: see Handling AEAT rejections.

Rendering your own PDF

The API returns the QR data so that it is available to your software:

{
  "verifactu": {
    "enabled": true,
    "submission_status": "PENDING",
    "qr_url": "https://www2.agenciatributaria.gob.es/wlpl/TIKE-CONT/ValidarQR?nif=B27534239&numserie=S-2026-0001&fecha=19-09-2026&importe=121.00",
    "qr_base64": "iVBORw0KGgoAAAANSUhEUgAAAMgAAADI..."
  }
}

• qr_base64 is the QR as a PNG image.
• qr_url is the link the QR encodes.

The URL comes from the registered record: its importe is the total AEAT registers, which can differ from your invoice's total — see What AEAT receives. The number registered with AEAT is the invoice_number BeeL. assigned.

Any document that carries the QR is subject to these rules:

• QRC-003 The QR measures between 30 mm and 40 mm
• QRC-004 The QR follows ISO/IEC 18004 with error correction M
• QRC-005 Use qr_url exactly as returned
• QRC-007 «QR tributario:» goes just above the QR
• QRC-008 The QR goes once, at the start of the first page
• QRC-009 Keep a blank margin around the QR
• the legend goes next to it — see The legend next to the QR.

The QR data is available from PENDING, without waiting for ACCEPTED. The verifactu.status.updated webhook for the registration carries qr_url and qr_base64 too.

The legend next to the QR

Related