En Paraguay, integrar un sistema con el Sistema Integrado de Facturación Electrónica Nacional (SIFEN) implica mucho más que producir un archivo XML. Hay que respetar catálogos fiscales, construir correctamente el Código de Control (CDC), aplicar las reglas del Manual Técnico y sus notas técnicas, firmar digitalmente el Documento Electrónico y validar el resultado final contra los esquemas oficiales.
Con ese contexto estoy construyendo Egeek.Sifen, un core open source en .NET orientado a encapsular esa complejidad en componentes reutilizables. La meta es que pueda consumirse como librería, mediante una Web API o desde un host embebido, sin obligar a cada implementación a reconstruir desde cero la lógica fiscal y criptográfica.
El primer objetivo: una Factura Electrónica v150 completa
El primer flujo implementado se concentra en la Factura Electrónica (FE) del formato SIFEN v150. Actualmente el pipeline puede ejecutar, en orden, las siguientes operaciones:
- Resolver los datos del emisor, timbrado y certificado.
- Validar catálogos y reglas funcionales aplicables.
- Generar el CDC con su dígito verificador.
- Construir el XML
rDE/DEde la factura. - Firmar el Documento Electrónico mediante XMLDSig y RSA-SHA256.
- Verificar localmente la firma generada.
- Calcular el QR usando el
DigestValuede la firma. - Incorporar
gCamFuFDfuera del bloque firmado. - Validar el XML final contra el paquete XSD oficial DE v150.
El orden importa. Por ejemplo, la validación XSD definitiva debe ejecutarse después de la firma y del QR, porque la estructura final de rDE exige tanto ds:Signature como gCamFuFD.
Un modo stateless para integrarse sin imponer persistencia
Una de las decisiones principales fue separar el procesamiento fiscal de la persistencia. En modo stateless, el consumidor entrega los datos necesarios para la operación y recibe el resultado sin que el core tenga que almacenar obligatoriamente el documento.
El emisor, el timbrado y el certificado pueden proporcionarse directamente o resolverse mediante contratos implementados por el host. Esto permite integrar el core con distintas arquitecturas, bases de datos, gestores de secretos o esquemas multiempresa sin acoplar la lógica SIFEN a una infraestructura específica.
Firma digital y tratamiento del certificado
El pipeline trabaja con certificados PKCS#12 protegidos por contraseña. Antes de firmar comprueba que el certificado:
- pueda abrirse con la contraseña indicada;
- contenga una clave privada RSA;
- declare uso de firma digital o no repudio;
- esté vigente en el mismo instante utilizado para
dFecFirma.
La política predeterminada rechaza certificados vencidos. Existe una excepción configurable exclusivamente para diagnósticos en ambientes de prueba; nunca se habilita desde el request fiscal ni se aplica en producción.
Los certificados, contraseñas y demás secretos de prueba permanecen fuera del repositorio. Las pruebas que requieren material criptográfico real se activan mediante variables de entorno y se omiten de forma controlada cuando esas variables no están presentes.
Los XSD oficiales como parte reproducible del core
Otro avance importante fue integrar el paquete oficial de esquemas para el DE v150. El paquete contiene ocho archivos XSD y un manifiesto con sus hashes SHA-256. Los esquemas se distribuyen como recursos embebidos y se cargan completamente en memoria.
El proveedor verifica cada hash antes de entregar el paquete al validador. De esta manera, el comportamiento es reproducible, no depende de descargas durante la ejecución y evita que un cambio remoto silencioso modifique la validación de documentos en producción.
Durante esta integración apareció además un detalle relevante: DE_v150.xsd define el tipo complejo rDE, pero el elemento raíz se declara en siRecepDE_v150.xsd. Este último debe actuar como esquema principal para validar un documento completo.
Reglas funcionales y pruebas
Además de la estructura XML, el core ya incorpora validaciones derivadas del Manual Técnico v150 y de notas técnicas aplicables. Entre ellas se encuentran reglas del receptor, obligaciones afectadas, unidades de medida, precisión de cantidades y cálculos de descuentos, anticipos, bases gravadas, IVA y totales.
Al momento de este avance, la suite ejecuta 54 pruebas correctas cuando se habilita la integración con un certificado real. También existe una regresión negativa que confirma que, si el XML no supera el XSD oficial, el caso de uso devuelve un error de validación y no entrega el documento como XML firmado listo para enviar.
Qué falta por delante
Este hito completa una parte importante del camino, pero el proyecto todavía está en construcción. Los siguientes bloques incluyen:
- validación de cadena de confianza y revocación mediante CRL u OCSP;
- envío del XML firmado a los servicios de SIFEN;
- normalización de respuestas y errores del servicio;
- pruebas de aceptación en el ambiente de SIFEN;
- ampliación hacia otros documentos, eventos, consultas y lotes.
La intención de estas publicaciones es compartir el proceso de construcción, las decisiones de arquitectura y los problemas reales que aparecen al convertir una especificación fiscal extensa en una biblioteca mantenible y verificable.
En las próximas entregas profundizaré en la generación del CDC, la firma XMLDSig y la forma de validar un paquete XSD con dependencias sin permitir acceso a red durante la ejecución.
La documentación técnica oficial de SIFEN puede consultarse en el portal de la Dirección Nacional de Ingresos Tributarios.