Sistema de Facturación Electrónica

API de Facturación Electrónica SRI

Motor de facturación electrónica para el SRI de Ecuador: genera el XML del comprobante, lo firma con certificado P12, lo envía por SOAP y gestiona la autorización de facturas, notas de crédito, notas de débito, retenciones y guías de remisión.

Desarrollador BackendFeb – Ago 2023Corporación Wolf S.A.
Proceso de emisión y autorización de comprobantes electrónicos ante el SRI: generar, firmar, enviar a recepción, comprobar estado, enviar a autorización, validar y notificar al receptor, con los retornos por comprobante devuelto o no autorizado
Diagrama de despliegue: pipeline de GitHub Actions con pruebas, migraciones y lint que despliega en AWS Elastic Beanstalk con EC2, balanceador de carga, RDS PostgreSQL, S3 y CloudWatch
Documentación OpenAPI de la API de facturación electrónica publicada con Redocly, mostrando el endpoint POST /invoices y el esquema JSON del comprobante

Contexto

Corporación Wolf necesitaba emitir comprobantes electrónicos válidos ante el Servicio de Rentas Internas (SRI) de Ecuador desde sus propios sistemas, sin pagar a un proveedor externo por cada documento. El flujo que exige el SRI es estricto: cada comprobante se genera como XML según el esquema XSD oficial, se firma digitalmente con un certificado P12, se envía al web service SOAP de recepción y después se consulta en el servicio de autorización, manejando ambientes de pruebas y producción con credenciales distintas. Un error en cualquiera de esos pasos deja la factura sin validez tributaria. El proyecto fue además mi tesis de grado en la ESPE, desarrollada con Karla Molina, y está publicada en el repositorio institucional (enlace en esta ficha).

Solución

Formé parte de un equipo de cinco personas (líder técnico, dos desarrolladores backend y dos frontend). Junto con otro desarrollador backend construimos la API completa en NestJS con TypeORM y PostgreSQL que cubre el ciclo del comprobante: construcción del XML con la clave de acceso de 49 dígitos y su dígito verificador módulo 11, firma XAdES-BES con el certificado P12, envío al web service SOAP del SRI, consulta de autorización y persistencia del comprobante autorizado junto con su historial de estados. La arquitectura sigue Clean Architecture (dominio, casos de uso e infraestructura separados), de modo que agregar un nuevo tipo de comprobante no toca la lógica de firma ni de envío. El despliegue corre por GitHub Actions con pruebas, verificación de migraciones y lint como puertas obligatorias, y en producción la API vive en AWS (Elastic Beanstalk con EC2 y balanceador, RDS PostgreSQL, S3 para los comprobantes y CloudWatch para logs). La API está documentada con OpenAPI y publicada con Redocly para que cualquier sistema cliente pueda integrarse sin leer el código.

Resultado

La API emite facturas, notas de crédito, notas de débito, retenciones y guías de remisión en los ambientes de pruebas y producción del SRI. La lógica de firma y envío se reutiliza para los cinco tipos de comprobante sin duplicación, y el equipo integra nuevos sistemas cliente solo con la documentación OpenAPI.

Funcionalidades clave

  • Generación de XML de comprobantes según el esquema XSD del SRI, con clave de acceso y dígito verificador módulo 11
  • Firma digital XAdES-BES de documentos con certificado P12
  • Envío automático al web service SOAP del SRI en ambientes de pruebas y producción
  • Consulta de autorización y almacenamiento del comprobante autorizado con historial de estados
  • Soporte para facturas, notas de crédito, notas de débito, retenciones y guías de remisión
  • Reintentos con backoff exponencial y cola de pendientes ante intermitencias del SRI
  • Pipeline CI/CD con GitHub Actions para pruebas y despliegues automatizados
  • Arquitectura modular basada en Clean Architecture
  • Documentación completa de la API con OpenAPI y Redocly

Retos y soluciones

El web service SOAP del SRI presenta intermitencias y responde con estados intermedios (RECIBIDA, DEVUELTA, EN PROCESO) que no siempre llegan en el orden esperado. Construimos un cliente SOAP propio que serializa el XML firmado en Base64, valida la estructura de cada respuesta y traduce los códigos de error del SRI a mensajes accionables para el usuario final. Para las caídas del servicio implementamos reintentos con backoff exponencial y una cola de comprobantes pendientes, así ningún documento se pierde y se reintenta automáticamente cuando el SRI vuelve a responder. La firma XAdES-BES fue el otro punto crítico: pequeñas diferencias en la canonicalización del XML invalidan la firma, por lo que la validamos de forma iterativa contra el ambiente de pruebas del SRI hasta obtener autorizaciones consistentes en todos los tipos de comprobante.