Puente ZATCA Fase 2 para SAP Business One
El reto
Los usuarios de SAP B1 en Arabia Saudita tenían un servicio de Windows para ZATCA que funcionaba, pero era difícil de operar: sin estado claro, sin configuración sencilla y con los errores escondidos en los logs.
Contexto
ZATCA Fase 2 (la fase de integración de la facturación electrónica saudí) exige que cada factura fiscal se genere como XML UBL 2.1, firmada con un sello criptográfico, enlazada con la factura anterior mediante su hash y con un código QR. Las facturas fiscales estándar (B2B) deben ser validadas (clearance) por ZATCA antes de compartirse con el comprador, y las facturas simplificadas (B2C) deben reportarse dentro de las 24 horas. Antes de poder enviar, un sistema debe incorporarse con un CSID de cumplimiento, superar las pruebas de cumplimiento y luego recibir un CSID de producción.
Los usuarios de SAP Business One en Arabia Saudita ya tenían un servicio de Windows que hacía este trabajo, pero era difícil de operar. No había una pantalla de estado clara, la configuración implicaba editar archivos a mano y, cuando ZATCA rechazaba una factura, el motivo quedaba enterrado en los archivos de log. Para un equipo de finanzas que debe emitir facturas conformes todos los días, un rechazo que nadie nota se convierte rápidamente en un problema de cumplimiento y de flujo de caja.
Qué construimos
- Interfaz web en ASP.NET Core con un asistente de configuración guiado de 6 pasos
- Proceso en segundo plano que sincroniza los documentos de SAP B1 con ZATCA y escribe los resultados de vuelta
- Inspector de envíos, historial de ejecuciones y mensajes de error legibles
- Secretos cifrados en reposo; licencia vinculada al hardware con modo de prueba
- Se ejecuta como servicio de Windows o en IIS
Cómo encaja todo
- El proceso en segundo plano lee las nuevas facturas y notas de crédito de la sociedad de SAP B1 a través de la DI API.
- Cada documento se convierte en XML conforme a ZATCA, se firma y se envía a la API de ZATCA Fatoora para su validación (B2B) o reporte (B2C).
- La respuesta de ZATCA (estado, advertencias, errores y el resultado validado) se escribe de vuelta en el documento de SAP B1, para que los usuarios vean el resultado dentro de SAP.
- Una base de datos SQLite local, a la que se accede mediante EF Core, guarda la configuración, los envíos y el historial de ejecuciones; los certificados y demás secretos se cifran en reposo.
- Encima funciona una interfaz web en ASP.NET Core MVC: el asistente de configuración de 6 pasos, el inspector de envíos y los mensajes de error legibles.
- La misma aplicación se ejecuta como servicio de Windows o en IIS, y una licencia vinculada al hardware con modo de prueba controla la activación.
Cómo lo entregamos
- Levantamiento y alcance. Revisar el servicio de Windows existente, los tipos de documento de SAP B1 en uso (facturas, notas de crédito, facturas simplificadas) y cómo se incorpora el cliente en ZATCA. Acordar el alcance de la fase.
- Desarrollo en una sociedad de prueba y el sandbox de ZATCA. Construir el asistente de configuración, el proceso de sincronización y la escritura de vuelta sobre una sociedad de prueba de SAP B1, y enviar solo a los entornos de desarrollo y simulación de ZATCA hasta superar las pruebas de cumplimiento.
- Pruebas. Pasar por el puente facturas normales, notas de crédito y documentos con errores intencionales. Verificar que cada rechazo muestre un mensaje claro en el inspector de envíos y que se pueda corregir y reenviar.
- Salida en vivo. Solicitar el CSID de producción, cambiar el puente al endpoint de producción, instalarlo como servicio de Windows o en IIS y activar la licencia. Revisar los primeros envíos en vivo junto con el equipo de finanzas.
- Soporte. Después de la salida en vivo, el soporte cubre nuevos casos de rechazo, actualizaciones de las reglas de ZATCA y preguntas de los usuarios.
Resultado
- Una configuración guiada reemplaza la configuración manual
- Las facturas rechazadas se ven y se corrigen desde una sola pantalla
La configuración que antes requería ajustes manuales es ahora un asistente guiado, y el equipo de finanzas puede ver y corregir las facturas rechazadas desde una sola pantalla en lugar de buscar en archivos de log.
Lecciones para un proyecto similar
- Planifique temprano la incorporación en ZATCA: el CSID de cumplimiento, las pruebas de cumplimiento y el CSID de producción son pasos separados y cada uno requiere acceso al portal Fatoora.
- Mantenga la cadena de hash de facturas y el contador en un solo lugar; reenviar u omitir documentos sin cuidado rompe la cadena.
- Haga visibles los rechazos para los usuarios de finanzas, no solo para TI. Un error legible junto al documento ahorra más tiempo que cualquier archivo de log.
Tecnología
Servicios utilizados
Realizado por Zain Abbas, Kodenova.
¿Quiere algo similar?
Cuéntenos lo que necesita. Recibirá una respuesta técnica clara, un alcance definido y un precio fijo, normalmente en 24 horas.
