verifactu-qr

URL del código QR tributario de VeriFactu (AEAT) y validación de NIF/CIF/NIE — sin dependencias, en una sola línea.

Herramienta en Python para generar la URL que debe llevar el QR obligatorio de las facturas españolas (RD 1007/2023 · Orden HAC/1177/2024) validando antes NIF, número de serie, fecha e importe, con los códigos de error oficiales de la AEAT (2001-2006). Incluye CLI y servidor MCP para agentes de IA.

Mantenido por Plataforma IA, consultora de automatización con IA para pymes en Madrid y toda España. Guía de plazos y preparación: VeriFactu 2027 para pymes.

Instalación

pip install verifactu-qr            # solo librería + CLI (0 dependencias)
pip install "verifactu-qr[svg]"     # + exportar el QR a SVG (segno)

Related MCP server: mcp-europe-business

Uso rápido (CLI)

$ verifactu-qr qr --nif 89890001K --numserie "12345678&G33" --fecha 01-01-2024 --importe 241.4
https://www2.agenciatributaria.gob.es/wlpl/TIKE-CONT/ValidarQR?nif=89890001K&numserie=12345678%26G33&fecha=01-01-2024&importe=241.4

# entorno de pruebas, sistema que NO remite registros (no VERI*FACTU) y QR en SVG
$ verifactu-qr qr --nif 89890001K --numserie "12345678&G33" --fecha 01-01-2024 --importe 241.4 \
    --pruebas --no-verifactu --svg qr.svg

$ verifactu-qr validar 89890001K
VALIDO: 89890001K (DNI)

Uso como librería

from verifactu_qr import build_qr_url, nif_valido, url_consulta_json

url = build_qr_url(
    nif="89890001K",
    numserie="12345678&G33",   # se codifica como 12345678%26G33 (URL encoding UTF-8)
    fecha="01-01-2024",        # o un datetime.date
    importe=241.4,             # o "241.40", Decimal
    verifactu=True,            # False -> .../ValidarQRNoVerifactu
    entorno="produccion",      # o "pruebas"
)
print(url)
print(url_consulta_json(url))   # añade &formato=json para parsear la respuesta de la AEAT

Errores con el código oficial: QRError.code ∈ {2001 NIF inválido, 2002 nº de serie demasiado largo, 2003 caracteres no permitidos, 2004 fecha inválida, 2005 importe inválido, 2006 importe demasiado largo}.

Uso como servidor MCP (agentes de IA)

{
  "mcpServers": {
    "verifactu-qr": { "command": "verifactu-qr-mcp" }
  }
}

Herramientas expuestas: verifactu_qr_url, validar_identificacion_fiscal, url_consulta_json. Probarlo a mano:

$ printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' | verifactu-qr-mcp

Qué cubre y qué no

• Cubre: los 4 parámetros obligatorios del QR (nif, numserie, fecha, importe), las 4 URLs base (producción/pruebas × VERI*FACTU/no verificable), el URL encoding con la misma semántica que java.net.URLEncoder (el detalle que más falla: & → %26, espacio → +), la validación con dígito de control de NIF/NIE/CIF y los códigos de error de la AEAT.

• No cubre: la huella (hash) de encadenamiento de registros, la firma electrónica XAdES, el envío SOAP de registros ni el diseño/maquetación del QR dentro del PDF (30-40 mm, nivel M). Para eso, ver pyverifactu o verifactu en PyPI.

Aviso: herramienta no oficial, sin vinculación con la AEAT. Verifica siempre el resultado con el portal de pruebas de la AEAT antes de producción.

Referencias

• Real Decreto 1007/2023, de 5 de diciembre (BOE-A-2023-24840).

• Orden HAC/1177/2024, arts. 20 y 21 (contenido del QR: NIF, serie y número, fecha, importe).

• AEAT, «Características del QR y especificaciones del servicio de cotejo» (sede electrónica).

Los tests incluyen el vector de ejemplo oficial de la AEAT (nif=89890001K, numserie=12345678&G33 → 12345678%26G33, fecha=01-01-2024, importe=241.4).

Tests

PYTHONPATH=src python -m unittest discover -s tests -v

Licencia

MIT — úsalo libremente en tu software de facturación.

English

verifactu-qr builds the URL that Spanish invoices must embed in their mandatory tax QR code (VeriFactu, RD 1007/2023) while validating the Spanish tax ID, invoice number, date and amount, returning the official AEAT error codes. Zero dependencies, plus a CLI and a stdio MCP server so AI agents can generate compliant QR URLs. Maintained by Plataforma IA, an AI automation consultancy based in Madrid, Spain.