Skip to navigation

Generate VeriFactu QR (ES)

Generate the AEAT VeriFactu QR for a Spanish invoice. Returns the verification URL plus PNG (base64) and SVG renderings of the QR code.

Note: PNG is base64-encoded (no data: prefix) so clients can embed it directly or decode it to bytes — JSON keeps the response easy to consume without multipart.

Send environment: "production" when your invoicing system reports its records to the AEAT (VERIFACTU); environment: "test" gives the AEAT test environment. Omitted: the QR points at the AEAT host of the configured VERIFACTU endpoint; when VERI*FACTU is not active on this service there is no production host and the call answers 501 VERIFACTU_QR_NO_PRODUCTION_HOST. environment in the response says which host the QR points at, legend is the phrase to print below the QR. invoice-api does not report the invoice to the AEAT.

Only VERI*FACTU QR codes are built. A system that does not report its records needs the ValidarQRNoVerifactu URL of the AEAT QR specification §5.2; this endpoint does not serve it.

Authentication

AuthorizationBearer

API Key authentication. Use sk_live_* for production or sk_test_* for testing.

Request

Inputs to the AEAT VeriFactu QR builder.
sellerNifstringRequired

Seller NIF/CIF (Spanish tax ID), e.g., “B12345678”.

invoiceDatestringRequired

Invoice issue date in AEAT QR format DD-MM-YYYY.

totaldoubleRequired

Invoice total amount used as the importe query parameter. Negative totals are accepted for credit notes.

numSerieFacturastringOptionalformat: "^[\x20-\x7E]{1,60}$"

Exactly the NumSerieFactura (series + number) your system reported to the AEAT for this invoice. It goes into the numserie parameter unchanged (AEAT QR specification v0.5.0 §6: up to 60 characters, ASCII 32–126; URL-encoded by the QR builder). Send either numSerieFactura or invoiceSeries + invoiceNumber, not both.

invoiceSeriesstringOptional

Older form: invoice series, joined with invoiceNumber as series/number into the numserie parameter (e.g. A + 2026-0042 ⇒ A/2026-0042). This only matches the AEAT record if your system reported the number in exactly that form — otherwise send numSerieFactura. Optional: without a series numserie is invoiceNumber alone.

invoiceNumberstringOptional

Older form: invoice number (with invoiceSeries, see there). Required unless numSerieFactura is sent.

environmentenumOptional

Which AEAT verification service the QR points at (QR specification v0.5.0 §5.1, ValidarQR). test: AEAT test environment (prewww2.aeat.es). production: AEAT production (www2.agenciatributaria.gob.es); send it when your invoicing system reports its records to the AEAT (VERIFACTU). Omitted: the QR points at the host of the configured VERIFACTU endpoint; when VERIFACTU is not active on this service there is no production host, and the call answers 501 VERIFACTU_QR_NO_PRODUCTION_HOST. Only VERIFACTU QR codes are built: a system that does not report its records needs the ValidarQRNoVerifactu URL of QR specification §5.2, which this endpoint does not serve.

Allowed values:
verifactuModebooleanOptionalDeprecated

Deprecated and ignored. The platform is VERI*FACTU-only (TipoUsoPosibleSoloVerifactu='S'), so the QR always points at the ValidarQR cotejo service. Whether that is the AEAT test or production host follows the deployment configuration (GOV_API_ES_AEAT_URL), not this flag. Accepted for backwards compatibility; will be removed.

Response

QR generated successfully
urlstring
AEAT verification URL embedded in the QR code.
pngstring

Base64-encoded PNG image of the QR code (no data URL prefix).

svgstring
SVG markup string for the QR code.
environmentenum
Which AEAT verification service the QR code points at.
Allowed values:
legendstring

The phrase that must appear directly below the QR code on an invoice from a VERIFACTU system (Orden HAC/1177/2024 art. 20.1.b). The order also allows the short form “VERIFACTU”.

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
500
Internal Server Error
501
Not Implemented Error