El QR de Verifactu para desarrolladores: URL, codificación, nivel M y tamaño

URLs

Parámetros

La codificación: el detalle que más falla

Los valores deben ir con «URL encoding» en UTF-8. La especificación lo ilustra con un número de serie que contiene «&»: 12345678&G33 debe escribirse 12345678%26G33. Sin codificar, la URL se parte y el cotejo falla.

El ejemplo oficial (apartado 4.1) está en Java y usa java.net.URLEncoder.encode(param, "UTF-8"). Esa función:

• deja sin codificar letras, dígitos y . - * _;
• convierte el espacio en +;
• codifica todo lo demás como %XX, incluidos /, (, ), ! y ~.

El encodeURIComponent de JavaScript difiere en cinco caracteres (! ' ( ) ~, que no codifica) y en el espacio (%20). Ambas formas se decodifican igual en un servidor estándar, pero si quieres un resultado idéntico al de la AEAT, usa estos fragmentos:

JavaScript

// Equivalente a java.net.URLEncoder.encode(valor, "UTF-8"), que usa el ejemplo oficial:
// deja sin codificar A-Z a-z 0-9 . - * _ y convierte el espacio en «+».
const javaUrlEncode = (v) =>
  encodeURIComponent(v)
    .replace(/[!'()~]/g, (c) => '%' + c.charCodeAt(0).toString(16).toUpperCase())
    .replace(/%20/g, '+');

const BASE = {
  produccion: 'https://www2.agenciatributaria.gob.es',
  pruebas: 'https://prewww2.aeat.es',
};

export function urlQr({ nif, numserie, fecha, importe }, { verifactu = true, entorno = 'produccion' } = {}) {
  const ruta = verifactu ? '/wlpl/TIKE-CONT/ValidarQR' : '/wlpl/TIKE-CONT/ValidarQRNoVerifactu';
  return `${BASE[entorno]}${ruta}?nif=${javaUrlEncode(nif)}&numserie=${javaUrlEncode(numserie)}` +
    `&fecha=${javaUrlEncode(fecha)}&importe=${javaUrlEncode(importe)}`;
}

console.log(urlQr({ nif: '89890001K', numserie: '12345678&G33', fecha: '01-01-2024', importe: '241.4' }, { entorno: 'pruebas' }));

Python

from urllib.parse import quote_plus

BASE = {
    ("verifactu", "produccion"): "https://www2.agenciatributaria.gob.es/wlpl/TIKE-CONT/ValidarQR",
    ("verifactu", "pruebas"): "https://prewww2.aeat.es/wlpl/TIKE-CONT/ValidarQR",
    ("no_verifactu", "produccion"): "https://www2.agenciatributaria.gob.es/wlpl/TIKE-CONT/ValidarQRNoVerifactu",
    ("no_verifactu", "pruebas"): "https://prewww2.aeat.es/wlpl/TIKE-CONT/ValidarQRNoVerifactu",
}


def url_qr(nif, numserie, fecha, importe, modo="verifactu", entorno="produccion"):
    # quote_plus con safe="*" equivale a java.net.URLEncoder.encode(valor, "UTF-8"),
    # que es lo que usa el ejemplo oficial: espacio -> "+", "&" -> "%26".
    enc = lambda v: quote_plus(v, safe="*", encoding="utf-8")
    return (
        f"{BASE[(modo, entorno)]}?nif={enc(nif)}&numserie={enc(numserie)}"
        f"&fecha={enc(fecha)}&importe={enc(importe)}"
    )


if __name__ == "__main__":
    # Ejemplo de la especificación del QR (v0.5.0): numserie con «&»
    print(url_qr("89890001K", "12345678&G33", "01-01-2024", "241.4", entorno="pruebas"))
    # https://prewww2.aeat.es/wlpl/TIKE-CONT/ValidarQR?nif=89890001K&numserie=12345678%26G33&fecha=01-01-2024&importe=241.4

Ambos se ejecutan en los tests de esta web y reproducen la URL de ejemplo de la especificación.

Requisitos de impresión

Códigos de error del cotejo

El parámetro formato=json devuelve la respuesta del cotejo en JSON para consultas desde programas, pero nunca puede ir en la URL del QR.