PORTICO

Middleware de integración para la Facturación Electrónica (SIFEN) en Paraguay.

Descripción

PORTICO es una solución de software orientada a empresas paraguayas y desarrolladores que permite la integración transparente con el Sistema Integrado de Facturación Electrónica Nacional (SIFEN).

El proyecto fue desarrollado para resolver la complejidad técnica de la generación, firma y envío de Documentos Electrónicos (DE) mediante una arquitectura modular y escalable.

Problema

Las empresas que necesitan emitir facturas electrónicas en Paraguay suelen depender de procesos manuales o implementaciones ad-hoc que generan errores de validación, problemas con la firma XML (XMLSec) y cuellos de botella en la comunicación con SIFEN.

Este proyecto busca centralizar y automatizar ese proceso, reduciendo tiempos de implementación, garantizando la validez criptográfica de los documentos y estandarizando la interacción con los servicios de la DNIT (Dirección Nacional de Ingresos Tributarios).

Solución

PORTICO actúa como un middleware (Monolito Modular) que orquesta el ciclo de vida completo del Documento Electrónico.

Las principales capacidades del sistema son:

• Generación y estructuración de XML según las normativas vigentes de SIFEN.
• Firma digital de documentos utilizando certificados criptográficos (XMLDSig).
• Comunicación asíncrona y síncrona con los web services de SIFEN.
• Generación del KuDE (Documento de Representación Gráfica).

Características

Funcionalidades principales

• Construcción de Documentos Electrónicos (DE) válidos.
• Firma criptográfica de XML de alta eficiencia.
• Envío de documentos y consulta de estado de lotes.
• Renderizado de representación gráfica (KuDE) en PDF.

Funcionalidades técnicas

• Arquitectura de Monolito Modular.
• Procesamiento de XML mediante JAXB.
• Seguridad y firma XML a través de Apache Santuario.
• Exposición de API REST para integración fluida con sistemas ERP de terceros.

Arquitectura

El proyecto utiliza una arquitectura de Monolito Modular basada en Spring Boot, dividida en dominios específicos de negocio y técnicos.

                    ┌─────────────────┐
                    │  Cliente / ERP  │
                    └────────┬────────┘
                             │
                    ┌────────▼────────┐
                    │   modulo-api    │
                    └────────┬────────┘
                             │
              ┌──────────────┼──────────────┐
              │              │              │
       ┌──────▼─────┐ ┌──────▼─────┐ ┌──────▼─────┐
       │ modulo-xml │ │modulo-kude │ │modulo-sifen│
       └──────┬─────┘ └──────┬─────┘ └────────┬───┘
              │              │                │
              └──────┬───────┴────────┬───────┘
                     │                │
              ┌──────▼──────┐  ┌──────▼──────┐
              │modulo-crypto│  │ modulo-core │
              └─────────────┘  └─────────────┘

Principios arquitectónicos

• Modularidad: Separación estricta de responsabilidades mediante módulos Maven.
• Bajo acoplamiento: Los módulos se comunican a través de interfaces definidas sin depender de implementaciones concretas.
• Seguridad por diseño: Aislamiento de las operaciones criptográficas y manejo seguro de claves.

Stack tecnológico

• Java 21
• Spring Boot 3.4.0
• Apache Maven
• Apache Santuario (XMLSec) 3.0.3
• JAXB 4.0.2

Estructura del proyecto

portico/
├── modulo-api      # Controladores REST, configuraciones web y entry point de la aplicación.
├── modulo-core     # Entidades, repositorios y lógica base compartida entre módulos.
├── modulo-crypto   # Gestión de keystores, certificados y firmas digitales seguras.
├── modulo-kude     # Lógica para la generación de la representación gráfica (KuDE).
├── modulo-sifen    # Clientes para la comunicación SOAP/REST con los servicios de SIFEN.
├── modulo-xml      # Generación, serialización y validación de estructuras XML.
├── docs/           # Documentación técnica, manuales y arquitectura.
└── temp/           # Archivos temporales de depuración e intercambio.

Requisitos

• Java 21 (JDK)
• Maven 3.8+
• Certificado digital válido (.p12) emitido por un prestador cualificado.

Instalación

1. Clonar el repositorio:

   git clone https://github.com/ThianR/Portico.git

2. Compilar el proyecto con Maven:

   cd portico
   mvn clean install

Configuración

Las configuraciones específicas del entorno (certificados, contraseñas, URLs de endpoints) deben definirse mediante variables de entorno o archivos externos.

El repositorio contiene un archivo .env.example que detalla las variables requeridas. Las credenciales y secretos nunca deben almacenarse en el repositorio.

Uso

1. Copiar .env.example a .env y configurar las variables de entorno.
2. Iniciar la aplicación.
3. Acceder a la documentación y/o endpoints de la API.
4. Enviar payloads con los datos de las transacciones.
5. El sistema procesará el envío y devolverá el estado junto con el XML firmado y el enlace al KuDE.

API

La interacción principal se da a través de endpoints REST. (Nota: Se requiere la actualización de la tabla con los endpoints exactos implementados en modulo-api).

Método	Endpoint	Descripción
POST	/api/v1/documentos	Generar, firmar y enviar Documento Electrónico
GET	/api/v1/documentos/{id}/estado	Consultar estado de procesamiento en SIFEN
GET	/api/v1/documentos/{id}/kude	Obtener representación gráfica (KuDE)

Base de datos

El proyecto cuenta con un script inicial schema_sifen.sql para el esquema de la base de datos necesaria para persistir auditorías, transacciones y metadatos de los envíos a SIFEN.

Pruebas

Ejecutar todas las pruebas del monolito modular:

mvn test

Para ejecutar pruebas de un módulo específico:

mvn test -pl modulo-xml

Seguridad

El proyecto contempla:

• Manejo aislado de certificados digitales.
• Las credenciales y secretos nunca deben almacenarse en el repositorio (usar entorno o bóveda).
• Validación de entradas y esquemas XML previo a la firma.

Despliegue

La aplicación Spring Boot se despliega típicamente empaquetando un .jar ejecutable generado en el modulo-api.

Ejemplo de ejecución del artefacto:

java -jar modulo-api/target/portico-api-1.0.0-SNAPSHOT.jar

Documentación

La documentación técnica extendida se encuentra en:

docs/
├── arquitectura/
├── operaciones/
└── sifen/

• Adicionalmente, el proyecto incluye un manual.pdf en su raíz.

Estado del proyecto

Estado actual:

Development

Roadmap

• Estructura modular Maven
• Generación de entidades JAXB
• Implementación completa firma XML (Apache Santuario)
• Clientes de integración SIFEN
• Generación KuDE
• Preparación para producción

Versionado

El proyecto utiliza Semantic Versioning.

Formato: MAJOR.MINOR.PATCH

Contribución

Las contribuciones son bienvenidas. Antes de realizar cambios:

1. Crear una rama.
2. Implementar los cambios asegurando la calidad del código.
3. Ejecutar las pruebas.
4. Verificar que el proyecto compile exitosamente.
5. Crear un Pull Request detallando los cambios.

Autor

ThianR

Software Developer

• GitHub: ThianR

Nota

Este proyecto es un middleware diseñado específicamente para el ecosistema de facturación electrónica de Paraguay (SIFEN - DNIT).