Regulated QR Codes on Invoices & Payments

<dependencies>
  <dependency>
    <groupId>com.itextpdf</groupId>
    <artifactId>itext-core</artifactId>
    <version>9.8.0</version>
    <type>pom</type>
  </dependency>
  <dependency>
    <groupId>com.google.zxing</groupId>
    <artifactId>core</artifactId>
    <version>3.5.4</version>
  </dependency>
  <dependency>
    <groupId>com.google.zxing</groupId>
    <artifactId>javase</artifactId>
    <version>3.5.4</version>
  </dependency>
</dependencies>

package com.bookshelf.billing.qr;

import com.google.zxing.BarcodeFormat;
import com.google.zxing.BinaryBitmap;
import com.google.zxing.DecodeHintType;
import com.google.zxing.EncodeHintType;
import com.google.zxing.MultiFormatReader;
import com.google.zxing.NotFoundException;
import com.google.zxing.Result;
import com.google.zxing.ResultMetadataType;
import com.google.zxing.WriterException;
import com.google.zxing.client.j2se.BufferedImageLuminanceSource;
import com.google.zxing.client.j2se.MatrixToImageWriter;
import com.google.zxing.common.BitMatrix;
import com.google.zxing.common.HybridBinarizer;
import com.google.zxing.qrcode.QRCodeWriter;
import com.google.zxing.qrcode.decoder.ErrorCorrectionLevel;
import com.itextpdf.kernel.colors.ColorConstants;
import com.itextpdf.kernel.pdf.canvas.PdfCanvas;

import java.awt.image.BufferedImage;
import java.util.EnumMap;
import java.util.Map;

/** Shared helpers: encode text as a QR matrix, draw it as vector squares, decode it back for a self-check. */
public final class QrSupport {

    /** 1 mm expressed in PDF points (1 pt = 1/72 inch). */
    public static final float MM = 72f / 25.4f;

    private QrSupport() {
    }

    /** Encodes the text with the given error-correction level, UTF-8, and no quiet zone (the layout adds it). */
    public static BitMatrix encode(String text, ErrorCorrectionLevel level) throws WriterException {
        Map<EncodeHintType, Object> hints = new EnumMap<>(EncodeHintType.class);
        hints.put(EncodeHintType.ERROR_CORRECTION, level);
        hints.put(EncodeHintType.CHARACTER_SET, "UTF-8");
        hints.put(EncodeHintType.MARGIN, 0);
        // width/height 0 asks ZXing for the smallest matrix, one pixel per module
        return new QRCodeWriter().encode(text, BarcodeFormat.QR_CODE, 0, 0, hints);
    }

    /**
     * Draws the matrix as black squares so that the whole symbol measures exactly sizeMm millimetres.
     * (x, y) is the lower-left corner of the symbol in points.
     */
    public static void drawVector(PdfCanvas canvas, BitMatrix matrix, float x, float y, float sizeMm) {
        float module = sizeMm * MM / matrix.getWidth();
        canvas.saveState().setFillColor(ColorConstants.BLACK);
        for (int row = 0; row < matrix.getHeight(); row++) {
            for (int col = 0; col < matrix.getWidth(); col++) {
                if (matrix.get(col, row)) {
                    float top = y + sizeMm * MM - row * module;
                    canvas.rectangle(x + col * module, top - module, module, module);
                }
            }
        }
        canvas.fill().restoreState();
    }

    /** Decodes a matrix again and returns the text plus the error-correction level the reader found. */
    public static String[] decode(BitMatrix matrix) throws NotFoundException {
        BufferedImage image = MatrixToImageWriter.toBufferedImage(addQuietZone(matrix, 4));
        BinaryBitmap bitmap = new BinaryBitmap(new HybridBinarizer(new BufferedImageLuminanceSource(image)));
        Result result = new MultiFormatReader().decode(bitmap,
                Map.of(DecodeHintType.POSSIBLE_FORMATS, java.util.List.of(BarcodeFormat.QR_CODE),
                        DecodeHintType.CHARACTER_SET, "UTF-8"));
        Object level = result.getResultMetadata().get(ResultMetadataType.ERROR_CORRECTION_LEVEL);
        return new String[] {result.getText(), String.valueOf(level)};
    }

    private static BitMatrix addQuietZone(BitMatrix source, int modules) {
        // scale each module to 8 px and add a quiet zone so that the reader can lock on
        int scale = 8;
        int size = (source.getWidth() + 2 * modules) * scale;
        BitMatrix out = new BitMatrix(size, size);
        for (int row = 0; row < source.getHeight(); row++) {
            for (int col = 0; col < source.getWidth(); col++) {
                if (source.get(col, row)) {
                    out.setRegion((col + modules) * scale, (row + modules) * scale, scale, scale);
                }
            }
        }
        return out;
    }
}

package com.bookshelf.billing.qr;

import com.google.zxing.WriterException;
import com.google.zxing.common.BitMatrix;
import com.google.zxing.qrcode.decoder.ErrorCorrectionLevel;

import java.math.BigDecimal;
import java.math.RoundingMode;
import java.nio.charset.StandardCharsets;
import java.time.LocalDate;
import java.time.format.DateTimeFormatter;

/** Builds the content of the AEAT invoice QR (specification v0.5.0, 10/12/2025). */
public final class VerifactuQr {

    /** Pre-production ("Portal de Pruebas Externas") base URLs from section 5 of the AEAT specification. */
    public static final String PRE_VERIFIABLE = "https://prewww2.aeat.es/wlpl/TIKE-CONT/ValidarQR";
    public static final String PRE_NOT_VERIFIABLE = "https://prewww2.aeat.es/wlpl/TIKE-CONT/ValidarQRNoVerifactu";

    private static final DateTimeFormatter DATE = DateTimeFormatter.ofPattern("dd-MM-uuuu");

    private VerifactuQr() {
    }

    /**
     * Builds the URL. The four parameters are nif, numserie, fecha and importe, in that order, and each value is
     * percent-encoded as UTF-8 (the spec shows an ampersand in numserie becoming %26).
     */
    public static String url(String baseUrl, String nif, String numSerie, LocalDate issued, BigDecimal total) {
        if (nif == null || nif.length() != 9) {
            throw new IllegalArgumentException("nif must have 9 characters");
        }
        if (numSerie.isEmpty() || numSerie.length() > 60
                || numSerie.chars().anyMatch(c -> c < 32 || c > 126)) {
            throw new IllegalArgumentException("numserie: 1..60 characters, ASCII 32-126 only");
        }
        BigDecimal amount = total.setScale(2, RoundingMode.HALF_UP);
        if (amount.precision() - amount.scale() > 12) {
            throw new IllegalArgumentException("importe: at most 12 integer digits");
        }
        return baseUrl + "?nif=" + encode(nif)
                + "&numserie=" + encode(numSerie)
                + "&fecha=" + DATE.format(issued)
                + "&importe=" + amount.toPlainString(); // "." decimal separator, never a locale-dependent format
    }

    /** RFC 3986 percent-encoding of UTF-8 bytes: everything except unreserved characters is escaped. */
    static String encode(String value) {
        StringBuilder out = new StringBuilder();
        for (byte b : value.getBytes(StandardCharsets.UTF_8)) {
            char c = (char) (b & 0xff);
            if ((c >= 'A' && c <= 'Z') || (c >= 'a' && c <= 'z') || (c >= '0' && c <= '9')
                    || c == '-' || c == '.' || c == '_' || c == '~') {
                out.append(c);
            } else {
                out.append('%').append(String.format("%02X", b & 0xff));
            }
        }
        return out.toString();
    }

    public static void main(String[] args) throws WriterException, com.google.zxing.NotFoundException {
        // The AEAT specification's own worked example (NIF 89890001K is the documented sample value)
        String url = url(PRE_VERIFIABLE, "89890001K", "12345678&G33", LocalDate.of(2024, 1, 1), new BigDecimal("241.4"));
        System.out.println(url);
        // The example exactly as the specification prints it, with importe=241.4
        String specExample = "https://prewww2.aeat.es/wlpl/TIKE-CONT/ValidarQR"
                + "?nif=89890001K&numserie=12345678%26G33&fecha=01-01-2024&importe=241.4";
        int specAt = specExample.indexOf("&importe=") + "&importe=".length();
        int ourAt = url.indexOf("&importe=") + "&importe=".length();
        System.out.println("matches the spec example up to importe: "
                + url.substring(0, ourAt).equals(specExample.substring(0, specAt)));
        System.out.println("importe equal as an amount: "
                + (new BigDecimal(url.substring(ourAt)).compareTo(new BigDecimal(specExample.substring(specAt))) == 0));

        BitMatrix matrix = QrSupport.encode(url, ErrorCorrectionLevel.M);
        String[] decoded = QrSupport.decode(matrix);
        System.out.println("modules per side: " + matrix.getWidth());
        System.out.println("round trip ok: " + decoded[0].equals(url) + ", level read back: " + decoded[1]);
    }
}

https://prewww2.aeat.es/wlpl/TIKE-CONT/ValidarQR?nif=89890001K&numserie=12345678%26G33&fecha=01-01-2024&importe=241.40
matches the spec example up to importe: true
importe equal as an amount: true
modules per side: 45
round trip ok: true, level read back: M

package com.bookshelf.billing.qr;

import com.google.zxing.common.BitMatrix;
import com.google.zxing.qrcode.decoder.ErrorCorrectionLevel;
import com.itextpdf.io.font.constants.StandardFonts;
import com.itextpdf.kernel.font.PdfFont;
import com.itextpdf.kernel.font.PdfFontFactory;
import com.itextpdf.kernel.geom.PageSize;
import com.itextpdf.kernel.pdf.PdfDocument;
import com.itextpdf.kernel.pdf.PdfWriter;
import com.itextpdf.kernel.pdf.canvas.PdfCanvas;
import com.itextpdf.layout.Canvas;
import com.itextpdf.layout.Document;
import com.itextpdf.layout.element.Div;
import com.itextpdf.layout.element.Paragraph;
import com.itextpdf.layout.element.Table;
import com.itextpdf.layout.properties.TextAlignment;
import com.itextpdf.layout.properties.UnitValue;

import java.math.BigDecimal;
import java.nio.file.Path;
import java.time.LocalDate;

import static com.bookshelf.billing.qr.QrSupport.MM;

/** A one-page Bookshelf Billing invoice with the AEAT QR centred at the top of page 1. */
public final class VerifactuInvoice {

    static final float QR_MM = 35f;          // allowed range 30..40 mm
    static final float QUIET_MM = 6f;        // minimum 2 mm, 6 mm recommended
    static final float BLOCK_MM = 5f + QUIET_MM + QR_MM + QUIET_MM + 8f; // caption + quiet + QR + quiet + legend

    public static void main(String[] args) throws Exception {
        Path out = Path.of(args.length > 0 ? args[0] : "invoice-verifactu.pdf");

        // Fictitious data. 89890001K is the AEAT test NIF for its pre-production environment, not a real taxpayer.
        String nif = "89890001K";
        String numSerie = "BB-2026-0042";
        LocalDate issued = LocalDate.of(2026, 10, 9);
        BigDecimal total = new BigDecimal("48.40");

        String url = VerifactuQr.url(VerifactuQr.PRE_VERIFIABLE, nif, numSerie, issued, total);
        BitMatrix matrix = QrSupport.encode(url, ErrorCorrectionLevel.M);

        try (PdfDocument pdf = new PdfDocument(new PdfWriter(out.toString()));
             Document document = new Document(pdf, PageSize.A4)) {
            PdfFont regular = PdfFontFactory.createFont(StandardFonts.HELVETICA);
            PdfFont bold = PdfFontFactory.createFont(StandardFonts.HELVETICA_BOLD);
            document.setFont(regular).setFontSize(10);
            document.setMargins(20 * MM, 20 * MM, 20 * MM, 20 * MM);

            // 1) Reserve the block at the very top, before any invoice content
            Div reserved = new Div().setHeight(UnitValue.createPointValue(BLOCK_MM * MM));
            document.add(reserved);
            float pageWidth = PageSize.A4.getWidth();
            float qrSize = QR_MM * MM;
            float qrX = (pageWidth - qrSize) / 2;
            float qrBottom = PageSize.A4.getHeight() - (20 + 5 + QUIET_MM + QR_MM) * MM;

            PdfCanvas page = new PdfCanvas(pdf.getPage(1));
            QrSupport.drawVector(page, matrix, qrX, qrBottom, QR_MM);
            try (Canvas captions = new Canvas(page, PageSize.A4)) {
                captions.setFont(regular).setFontSize(10);
                // caption above the code: "QR tributario:" is always required
                captions.showTextAligned(new Paragraph("QR tributario:").setFont(bold), pageWidth / 2,
                        qrBottom + qrSize + QUIET_MM * MM + 2, TextAlignment.CENTER);
                // legend directly below the code (verifiable invoices only)
                captions.showTextAligned(new Paragraph("VERI*FACTU").setFont(bold), pageWidth / 2,
                        qrBottom - QUIET_MM * MM - 8, TextAlignment.CENTER);
            }

            // 2) Invoice content starts below the reserved block
            document.add(new Paragraph("Bookshelf Billing S.L. (fictitious)").setFont(bold).setFontSize(14));
            document.add(new Paragraph("Invoice " + numSerie + " of " + issued + " | NIF " + nif + " (sample)"));
            Table table = new Table(UnitValue.createPercentArray(new float[] {6, 1, 2})).useAllAvailableWidth();
            table.addHeaderCell("Item").addHeaderCell("Qty").addHeaderCell("Amount (EUR)");
            table.addCell("Catalogue hosting, October 2026").addCell("1").addCell("40.00");
            table.addCell("VAT 21 % (rounded)").addCell("").addCell("8.40");
            table.addCell(new Paragraph("Total").setFont(bold)).addCell("").addCell(new Paragraph(total.toPlainString()).setFont(bold));
            document.add(table);
        }
        System.out.println("QR content: " + url);
        System.out.println("written " + out.toAbsolutePath());
    }
}