El código QR de ZATCA explicado: los 9 campos TLV, Fase 1 frente a Fase 2 y cómo verificarlo

Qué es realmente el código QR

El código QR de una factura electrónica saudí no es un enlace ni una imagen de la factura. Es un bloque corto de datos, codificado en Base64, que un teléfono puede leer sin conexión a internet.

Los datos internos usan un formato llamado TLV: Tag, Length, Value (etiqueta, longitud, valor). Cada campo se escribe en tres partes, una tras otra:

• Etiqueta (tag): un byte que indica qué campo es (1 para el nombre del vendedor, 2 para el número de IVA, etc.).
• Longitud (length): un byte que indica cuántos bytes ocupa el valor.
• Valor (value): el campo en sí, codificado en UTF-8.

Todos los campos se unen sin espacios ni separadores, y la cadena de bytes completa se codifica luego en Base64. La guía técnica de ZATCA fija un límite de 700 caracteres para la cadena Base64 final.

Los 9 campos TLV

Las etiquetas 1 a 5 son texto plano legible. Las etiquetas 6 a 9 son datos criptográficos, por lo que un decodificador las muestra como cadenas codificadas, no como palabras.

El hash de la factura en la etiqueta 6 es un hash SHA-256 de la factura XML. El estándar de seguridad de ZATCA explica que el hash excluye las extensiones UBL, el bloque de firma y el propio elemento QR, lo cual tiene sentido: el QR no puede contener un hash de sí mismo.

Fase 1 frente a Fase 2

ZATCA implantó la facturación electrónica en dos fases, y el código QR cambió con ellas.

La Fase 1 (generación) comenzó el 4 de diciembre de 2021. Las facturas debían emitirse con un sistema conforme, y las facturas tributarias simplificadas (B2C) debían llevar un código QR con los cinco campos básicos. Las guías detalladas de ZATCA dicen claramente que en esta fase el código QR no era obligatorio en las facturas tributarias estándar (B2B).

La Fase 2 (integración) comenzó el 1 de enero de 2023 y se aplica por oleadas. Los contribuyentes se incorporan según umbrales de ingresos. Si su empresa está en el grupo más reciente, consulte nuestra nota sobre la Ola 25 para SAP Business One. En la Fase 2 el código QR incorpora las etiquetas 6 a 9, y las reglas dependen del tipo de factura:

La conclusión práctica para B2B: su factura impresa o en PDF debe usar el código QR que devuelve ZATCA tras la autorización, no uno que su sistema generó antes de enviarla. En B2C, su sistema construye el QR completo en el momento de la venta.

Un ejemplo práctico

Esta es una cadena QR al estilo de la Fase 1 para una factura de SAR 1,000 más 15% de IVA, construida con los valores de ejemplo de la tabla anterior:

AQ9BbCBOb29yIFRyYWRpbmcCDzMwMDAwMDAwMDAwMDAwMwMUMjAyNi0xMC0xNlQxMDoxNTowMFoEBzExNTAuMDAFBjE1MC4wMA==

Si decodifica los primeros bytes, verá 01 0F seguido del nombre del vendedor. 01 es la etiqueta 1. 0F es 15 en hexadecimal, el número de bytes de “Al Noor Trading”. Luego viene 02 0F y el número de IVA de 15 dígitos, y así sucesivamente hasta la etiqueta 5.

Pegue esa cadena en nuestro decodificador gratuito de códigos QR de ZATCA y verá los cinco campos desglosados uno por uno.

Cómo verificar el código QR de su factura

Use estos pasos cuando un cliente se queje de que su escáner muestra “invalid QR” (QR no válido), o cuando pruebe un nuevo formato de factura.

1. Obtenga la cadena original. Escanee el QR impreso con cualquier aplicación de escaneo, o copie el valor almacenado en el registro de la factura en su ERP.
2. Decodifíquela. Pásela por un decodificador TLV. Si el decodificador falla de inmediato, probablemente la cadena no es Base64 o se le añadieron caracteres extra (espacios, saltos de línea, un prefijo de URL).
3. Compare las etiquetas 1 a 5 con la factura. El nombre del vendedor y el número de IVA deben coincidir con su registro de IVA. La etiqueta 4 debe ser igual al total de la factura con IVA. La etiqueta 5 debe ser igual al IVA total de la factura.
4. Revise la fecha y hora. La etiqueta 3 debe coincidir con la fecha y hora de emisión de la factura. Una fecha de otro día suele indicar que el QR se construyó con el campo equivocado.
5. Cuente las etiquetas. Una factura simplificada de la Fase 2 debe mostrar 9 etiquetas. Una factura estándar autorizada debe llevar el QR devuelto por ZATCA. Si ve solo 5 etiquetas en una factura de la Fase 2, su formato de impresión está mostrando un valor antiguo de la Fase 1.
6. Revise la longitud. La cadena Base64 debe tener como máximo 700 caracteres.

La decodificación confirma la estructura y los campos legibles. No demuestra que la firma de las etiquetas 7 y 9 sea auténtica. Esa comprobación requiere el XML firmado y la validación propia de ZATCA, que se realiza en el SDK o en la plataforma durante la autorización previa y el reporte.

Errores comunes en el QR

La guía técnica de ZATCA enumera algunos errores que aparecen una y otra vez. Nosotros vemos los mismos cuando revisamos formatos de factura:

• Nombre del vendedor en árabe sin codificar en UTF-8. El nombre aparece al escanear como signos de interrogación o caracteres ilegibles.
• Longitud contada en caracteres, no en bytes. Un nombre árabe de 10 letras ocupa unos 20 bytes. Si el byte de longitud dice 10, todas las etiquetas posteriores se leen mal.
• Separadores entre campos. Comas, espacios o relleno entre los conjuntos TLV rompen la decodificación. No debe haber ninguno.
• Importes que no coinciden con la factura. A menudo el QR se construye con el subtotal o con las cifras anteriores a un descuento a nivel de documento.
• Imprimir el QR equivocado en facturas B2B. En la Fase 2, el QR autorizado por ZATCA debe ser el que figure en el documento.

En SAP Business One, el valor del QR normalmente se almacena en la factura de clientes (en un campo definido por el usuario o en los datos del documento electrónico) y se imprime mediante Crystal Reports o el Print Layout Designer como código de barras o imagen. Cuando el código impreso falla, revise primero el valor almacenado con un decodificador TLV. Si el valor almacenado es correcto, el problema está en el formato de impresión, no en la integración.

Dónde encaja esto en la Fase 2

El código QR es la parte visible de un proceso más largo: XML UBL 2.1, cálculo del hash, firma con su CSID y autorización previa o reporte mediante las API de ZATCA. Si alguno de esos pasos falla, el QR normalmente también estará mal. Nuestra guía de facturación electrónica ZATCA cubre el flujo completo, y la calculadora de IVA saudí le ayuda cuando necesita comprobar a mano las etiquetas 4 y 5.

Si sus facturas de SAP Business One imprimen un código QR que los clientes o ZATCA rechazan, envíenos una muestra y le diremos qué parte está fallando.

Fuentes

• ZATCA: E-Invoicing Detailed Technical Guideline, Version 2 (nov. 2022) (guía técnica detallada)
• ZATCA: Detailed Guidelines for E-Invoicing, Version 2 (may. 2023) (guías detalladas)
• ZATCA: Electronic Invoice Security Features Implementation Standards (19 de mayo de 2023)
• Comunidad de desarrolladores de ZATCA: estructura del código QR de las facturas tributarias electrónicas
• ZATCA: página de guías de facturación electrónica

Servicios relacionados

• Integración de facturación electrónica
• Desarrollo para SAP Business One