API Facturación Electrónica SRI — Ecuador 🇪🇨

API REST completa para emitir, firmar y gestionar comprobantes electrónicos ante el SRI Ecuador.
Facturas, Notas de Crédito/Débito, Retenciones y Guías de Remisión — en una sola integración.

---

¿Qué hace esta API?

Integra tu sistema (ERP, POS, e-commerce, SaaS) con el Servicio de Rentas Internas (SRI) de Ecuador mediante un único endpoint REST. Ella se encarga de todo el flujo complejo por ti:

Tu sistema  →  POST /sri/factura/emitir  →  Genera XML  →  Firma XAdES-BES
            →  Envía al SRI (SOAP)       →  Obtiene autorización
            →  Genera RIDE (PDF+QR)      →  Notifica via Webhook  →  Guarda en DB

Sin librerías adicionales. Sin entender SOAP. Sin XML a mano. Solo JSON.

---

📋 Tabla de Contenidos

• Por qué esta API
• Funcionalidades
• Inicio Rápido
• Ejemplo Real
• Arquitectura
• API Endpoints
• Variables de Entorno
• Docker
• Autenticación y Roles
• Estructura del Proyecto
• Scripts Disponibles
• Changelog
• Contribuciones
• Licencia
• Contacto

---

🎯 Por qué esta API

La mayoría de soluciones de facturación electrónica para Ecuador son librerías PHP o Java que requieren integración manual con los Web Services SOAP del SRI. Esta API resuelve eso diferente:

Característica	Esta API	Otras soluciones
Lenguaje	TypeScript / NestJS	PHP, Java, Python
Tipo	API REST completa y desplegable	Librería que debes integrar
Multi-tenant	✅ Múltiples empresas en una instancia	❌
Autenticación JWT	✅ Con roles y refresh tokens	❌
Cola asíncrona	✅ BullMQ + Redis	❌
Webhooks	✅ Notificaciones automáticas	❌
RIDE (PDF)	✅ Plantillas Word/Excel + QR	❌
Firma XAdES-BES	✅ Integrada	Manual / externa
Docker	✅ Producción lista	Raramente
Swagger UI	✅ Incluido	❌

---

✨ Funcionalidades

Comprobantes Electrónicos SRI

• 🧾 Factura Electrónica — tipo 01
• 📋 Nota de Crédito — tipo 04
• 📋 Nota de Débito — tipo 05
• 🚚 Guía de Remisión — tipo 06
• 🏦 Comprobante de Retención — tipo 07

Firma y Seguridad

• 🔐 Firma XAdES-BES con certificado P12 — estándar oficial del SRI
• 🔑 Autenticación JWT con roles (SUPERADMIN, ADMIN, USER)
• 🔄 Rotación de Refresh Tokens — sesiones seguras
• 🛡️ Cifrado AES-256 para datos sensibles (passwords de certificados, tokens)

Integraciones y Automatización

• ⚡ Webhooks — notifica tu sistema automáticamente cuando el SRI autoriza o rechaza
• 📤 Cola BullMQ + Redis — emisión asíncrona con reintentos automáticos
• 🌐 Ambientes SRI — pruebas (celcer.sri.gob.ec) y producción (cel.sri.gob.ec) configurables por variable de entorno

Generación de Documentos

• 📄 RIDE en PDF — desde plantillas Word/Excel con Carbone.io
• ✍️ Firma digital de PDFs — con @signpdf y certificado P12
• 📷 Código QR embebido automáticamente en el RIDE

Multi-Tenant

• 🏢 Múltiples empresas (tenants) en una sola instancia de API
• 🏬 Sucursales y Puntos de Emisión por empresa
• 🔢 Secuenciales automáticos por punto de emisión y tipo de comprobante

Observabilidad

• 📊 Health Check en /status — PostgreSQL, Redis y filesystem
• 📝 Auditoría — log inmutable de todas las acciones sensibles
• 🔍 Swagger UI interactivo en /api con autorización JWT persistida

---

🚀 Inicio Rápido

Requisitos

Herramienta	Versión mínima
Node.js	22+
npm	10+
PostgreSQL	14+
Redis	7+
Docker (opcional)	24+

Instalación

# 1. Clonar el repositorio
git clone https://github.com/AngeloBarzolaVillamar/open-api-facturacion-sri.git
cd open-api-facturacion-sri

# 2. Instalar dependencias
npm install

# 3. Configurar variables de entorno
cp .env.example .env.development
# Edita .env.development con tu configuración (DB, Redis, JWT, etc.)

# 4. Inicializar la base de datos
psql -U postgres -d tu_db -f database/init.sql

# 5. Iniciar en modo desarrollo
npm run start:dev

La API estará disponible en: http://localhost:3001
Documentación Swagger interactiva en: http://localhost:3001/api

Con Docker (recomendado para desarrollo)

cp .env.example .env.docker
# Edita .env.docker con tu configuración

docker compose up -d --build

---

⚡ Ejemplo Real

1. Autenticarse

curl -X POST http://localhost:3001/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "superadmin@openapi-sri.com", "password": "Admin123!"}'

{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

2. Emitir una Factura Electrónica

curl -X POST http://localhost:3001/sri/factura/emitir \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <TU_ACCESS_TOKEN>" \
  -d '{
    "fechaEmision": "05/05/2026",
    "emisor": {
      "ruc": "0924383631001",
      "razonSocial": "MI EMPRESA S.A.",
      "nombreComercial": "MI EMPRESA",
      "dirMatriz": "Guayaquil, Av. Principal 123",
      "dirEstablecimiento": "Local 1, Guayaquil",
      "establecimiento": "001",
      "puntoEmision": "001",
      "obligadoContabilidad": "SI",
      "certificadoP12": "certificado.p12",
      "claveP12": "mi-clave-p12"
    },
    "comprador": {
      "tipoIdentificacion": "05",
      "identificacion": "0926789017",
      "razonSocial": "JUAN PEREZ"
    },
    "detalles": [
      {
        "codigoPrincipal": "PROD-001",
        "descripcion": "Servicio de desarrollo de software",
        "cantidad": 1,
        "precioUnitario": 1000.00,
        "descuento": 0,
        "impuestos": [
          {
            "codigo": "2",
            "codigoPorcentaje": "4",
            "tarifa": 15,
            "baseImponible": 1000.00,
            "valor": 150.00
          }
        ]
      }
    ],
    "pagos": [{ "formaPago": "01", "total": 1150.00 }]
  }'

Respuesta exitosa del SRI

{
  "success": true,
  "claveAcceso": "0505202601092438363100110010010000000011234567891",
  "estado": "AUTORIZADO",
  "numeroAutorizacion": "0505202601092438363100110010010000000011234567891",
  "fechaAutorizacion": "2026-05-05T14:30:00.000Z",
  "mensajes": []
}

---

🏛️ Arquitectura

                         ┌─────────────────────────────┐
                         │       Tu Sistema (ERP/POS)   │
                         └────────────┬────────────────┘
                                      │ REST JSON
                         ┌────────────▼────────────────┐
                         │   API Facturación SRI        │
                         │   NestJS + TypeScript        │
                         │   ┌─────────────────────┐   │
                         │   │  Módulos NestJS      │   │
                         │   │  - /auth  (JWT)      │   │
                         │   │  - /sri   (SRI)      │   │
                         │   │  - /webhooks         │   │
                         │   │  - /pdf   (Carbone)  │   │
                         │   │  - /signature (P12)  │   │
                         │   └──────────┬──────────┘   │
                         └─────────────┼───────────────┘
              ┌──────────┬─────────────┼──────────┬──────────┐
              ▼          ▼             ▼          ▼          ▼
        PostgreSQL     Redis        SRI SOAP   Carbone     Webhook
         (datos)      (cola/       (celcer/    (PDFs)    (tu URL)
                       caché)      cel.sri)

Flujo de emisión asíncrona

POST /sri/factura/emitir
        │
        ▼
  Validación DTO ──▶ Firma XAdES-BES ──▶ Envío SOAP SRI
        │                                      │
        ▼                                      ▼
  Guarda en DB                        ¿Autorizado?
        │                              │         │
        ▼                             SÍ         NO
  Encola BullMQ                        │         │
        │                         Genera RIDE  Reintento
        ▼                         (PDF + QR)   automático
  Procesador Redis                     │
        │                         Dispara Webhook
        ▼                         a tu sistema
  Webhook → Tu URL

---

🔌 API Endpoints

Documentación completa e interactiva en /api (Swagger UI).

Autenticación

Método	Endpoint	Descripción
POST	/auth/login	Iniciar sesión — retorna accessToken + refreshToken
POST	/auth/refresh	Renovar tokens con rotación automática
POST	/auth/register	Crear usuario (requiere rol SUPERADMIN)
PATCH	/auth/change-password	Cambiar contraseña

Comprobantes Electrónicos SRI

Método	Endpoint	Descripción
POST	/sri/factura/emitir	Emitir Factura Electrónica
POST	/sri/nota-credito/emitir	Emitir Nota de Crédito
POST	/sri/nota-debito/emitir	Emitir Nota de Débito
POST	/sri/retencion/emitir	Emitir Comprobante de Retención
POST	/sri/guia-remision/emitir	Emitir Guía de Remisión
GET	/sri/comprobantes	Listar comprobantes (paginado, filtrable)
GET	/sri/comprobantes/:claveAcceso	Detalle de un comprobante
GET	/sri/comprobantes/:claveAcceso/xml	Descargar XML autorizado
GET	/sri/verificar/:claveAcceso	Consultar estado en SRI en tiempo real
POST	/sri/sincronizar	Sincronizar comprobantes pendientes
POST	/sri/comprobantes/:clave/reintentar	Reintentar comprobante fallido
PATCH	/sri/comprobantes/:clave/anular	Anular comprobante localmente

Catálogos SRI

Método	Endpoint	Descripción
GET	/catalogos/impuestos	Tarifas IVA vigentes (0%, 5%, 15%)
GET	/catalogos/retenciones	Códigos de retención Renta e IVA
GET	/catalogos/formas-pago	Formas de pago SRI
GET	/catalogos/tipos-identificacion	Tipos de identificación
GET	/catalogos/documentos-sustento	Documentos sustento
GET	/catalogos/motivos-traslado	Motivos traslado (Guía de Remisión)

Webhooks

Método	Endpoint	Descripción
GET	/webhooks	Listar webhooks del Tenant
POST	/webhooks	Registrar URL de notificación
GET	/webhooks/logs	Historial de notificaciones (paginado)

Generación de RIDE (PDF)

Método	Endpoint	Descripción
POST	/generate-pdf/download/:templateId	Generar y descargar PDF
POST	/generate-pdf/save/:templateId	Generar y guardar en servidor