Tabla de Contenidos
Vamos a aclarar un gran malentendido de inmediato: No puede generar una factura electrónica saudí oficial simplemente escribiendo datos en un generador de códigos QR en línea.
Construir un sistema ERP o POS que cumpla con la Autoridad Zakat, Impuestos y Aduanas (ZATCA) de Arabia Saudita es un esfuerzo de ingeniería de software complejo. Como Arquitecto de Sistemas que recientemente diseñó soluciones técnicas vinculando la Fase 1 a la Fase 2, puedo decirle que el verdadero desafío no es renderizar el gráfico QR, es la estricta lógica criptográfica requerida para generar la cadena subyacente.
La Realidad del Cumplimiento ZATCA
Si un cliente escanea su recibo impreso con la aplicación móvil oficial de ZATCA y muestra un error de "Código QR Inválido", el problema no es su impresora. El problema está en su código.
ZATCA requiere que su ERP tome datos específicos de la factura (Nombre de la empresa, Número de IVA, Marca de tiempo, Monto total y Monto de IVA), los codifique en un arreglo de bytes preciso utilizando el método Tag-Length-Value (TLV), los aplique hash, los firme y finalmente convierta todo ese arreglo de bytes en una cadena Base64. Solo entonces esa cadena Base64 se convierte en un código QR.
La Anatomía de la Codificación TLV
En la Fase 1, el requisito era relativamente sencillo. Tenía que construir un arreglo de bytes mapeando 5 etiquetas principales. TLV funciona exactamente como suena:
- Tag (Etiqueta) (1 byte): El identificador (ej.,
01para el Nombre del Vendedor). - Length (Longitud) (1 byte): La longitud del valor en bytes (ej.,
0Fpara 15 bytes). - Value (Valor) (Variable): Los datos reales codificados en UTF-8 (ej.,
Mahwar KSA).
def get_tlv_hex(tag: int, value: str) -> str:
val_bytes = value.encode('utf-8')
tag_hex = f"{tag:02x}"
length_hex = f"{len(val_bytes):02x}"
val_hex = val_bytes.hex()
return tag_hex + length_hex + val_hex
El Cambio Criptográfico en la Fase 2 (Integración)
La Fase 2 (la Fase de Integración) conecta su ERP directamente al portal FATOORA. Las reglas de generación de códigos QR se volvieron exponencialmente más difíciles. ZATCA ahora requiere etiquetas adicionales (Etiquetas 6-9) para garantizar la autenticidad y secuencia de la factura:
- Etiqueta 6 (Hash de Factura XML): Un hash SHA-256 de la factura XML generada.
- Etiqueta 7 (Firma ECDSA): Una firma criptográfica generada utilizando la clave privada del contribuyente.
- Etiqueta 8 (Clave Pública ECDSA): La clave pública correspondiente a la clave privada utilizada para firmar la factura.
- Etiqueta 9 (Sello Criptográfico): Proporcionado por el propio ZATCA tras la autorización exitosa de la API.
Si su arreglo de bytes tiene un solo carácter de diferencia, o si intenta codificar la cadena utilizando ASCII estándar en lugar de conversiones hexadecimales estrictas UTF-8, la cadena Base64 resultante será rechazada por la aplicación de escaneo de ZATCA.
El Dilema de Pruebas QA para Desarrolladores
Cuando escriba la lógica de backend en Odoo, Salla o un wrapper personalizado de Python, generará cientos de cadenas Base64 de prueba. Para asegurar que su criptografía es correcta, debe escanear físicamente los códigos QR resultantes con la app móvil oficial de ZATCA. ¿Pero cómo se prueban rápidamente 500 cadenas Base64 sin construir su propia herramienta de renderizado front-end desde cero?
Pruebas por Lotes de Cadenas Base64 a Nivel Local
Aquí es exactamente donde el Generador BulkBarcode actúa como un entorno de pruebas (sandbox) crítico para los desarrolladores.
No creamos esta herramienta para hacer facturas. La construimos para que los ingenieros de software puedan realizar pruebas QA rápidamente a la salida de su ERP. Al usar nuestro espacio de trabajo del lado del cliente, su equipo puede evitar la molestia de escribir scripts de renderizado locales y centrarse puramente en corregir su criptografía.
El Flujo de Trabajo de Prueba Seguro:
- Extraer los Hashes: Consulte su base de datos ERP y extraiga una lista de 500 cadenas Base64 de prueba.
- Pegar y Renderizar: Pegue esa lista directamente en nuestro espacio de trabajo "Pegar SKU". Debido a que nuestro motor funciona completamente en WebAssembly dentro de su navegador, sus hashes y datos de prueba internos nunca abandonan su computadora.
- Escanear y Verificar: El espacio de trabajo renderiza instantáneamente 500 códigos QR de alta resolución en su pantalla. Puede tomar su teléfono, abrir la aplicación oficial de ZATCA y escanearlos directamente desde el monitor.
Una vez que su software pase las pruebas de control de calidad (QA), su ERP manejará la facturación electrónica de ZATCA automáticamente. Luego, puede reservar nuestro espacio de trabajo para lo que hace mejor: formatear etiquetas de estanterías, rastreo de GS1 y logística de cadena de frío.
Prueba de QA de sus Hashes Base64
Pegue la salida Base64 de su ERP en nuestro motor seguro de renderizado del lado del cliente para generar instantáneamente códigos QR escaneables.