Skip to content

mat1520/api-facturacion-electronica-ecuador

BranchesTags

Repository files navigation

🇪🇨 API de Facturación Electrónica para Ecuador

Ecuador Version License Node Status

🚀 API RESTful para la generación, firma y autorización de facturas electrónicas según los requisitos del SRI de Ecuador

🌐 DEMO EN VIVO | 📖 DOCUMENTACIÓN | 🤝 CONTRIBUIR | 💝 DONAR

🎯 Prueba la API ahora mismo:

curl https://api-facturacion-electronica-ecuador.onrender.com/health

Deploy to Render Deploy to Railway

🌟 Características Principales

✅ Funcionalidades Implementadas

  • 🎯 Generación de XML según estándares SRI
  • 🔢 Cálculo automático de clave de acceso
  • 🛡️ Autenticación por API Key
  • ✅ Validación completa de datos
  • 📊 API RESTful profesional
  • 🔄 Manejo robusto de errores
  • 📱 Respuestas estructuradas JSON

⚠️ Modo Demostración

  • 🟢 XML válido según SRI
  • 🟢 Clave de acceso calculada
  • 🟢 Estructura completa de datos
  • 🟡 Firma digital simplificada
  • 🟡 Envío al SRI simulado
  • 🟡 Autorización simulada

🚀 Demo en Vivo

🌐 API Desplegada: https://api-facturacion-electronica-ecuador.onrender.com

Endpoint Método Descripción Auth
/health GET Health check ❌
/ GET Página demo ❌
/api/facturas GET Listar facturas ✅
/api/facturas POST Crear factura ✅
/api/facturas/:id GET Consultar factura ✅

🔑 API Key para pruebas: render_demo_api_key_2025_ecuador_sri

🧪 Prueba Rápida con cURL:

# Health Check
curl https://api-facturacion-electronica-ecuador.onrender.com/health

# Crear Factura
curl -X POST https://api-facturacion-electronica-ecuador.onrender.com/api/facturas \
  -H "Content-Type: application/json" \
  -H "x-api-key: render_demo_api_key_2025_ecuador_sri" \
  -d '{
    "infoFactura": {
      "razonSocialComprador": "CLIENTE DEMO S.A.",
      "identificacionComprador": "0987654321001",
      "totalSinImpuestos": "100.00",
      "importeTotal": "112.00"
    },
    "detalles": [{
      "descripcion": "Producto de prueba",
      "cantidad": "1",
      "precioUnitario": "100.00",
      "precioTotalSinImpuesto": "100.00"
    }]
  }'

# Listar Facturas
curl -H "x-api-key: render_demo_api_key_2025_ecuador_sri" \
     https://api-facturacion-electronica-ecuador.onrender.com/api/facturas

🔥 Prueba con JavaScript:

// Crear una factura
const response = await fetch('https://api-facturacion-electronica-ecuador.onrender.com/api/facturas', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'x-api-key': 'render_demo_api_key_2025_ecuador_sri'
    },
    body: JSON.stringify({
        "infoFactura": {
            "razonSocialComprador": "CLIENTE DEMO S.A.",
            "identificacionComprador": "0987654321001",
            "totalSinImpuestos": "100.00",
            "importeTotal": "112.00"
        },
        "detalles": [{
            "descripcion": "Producto de prueba",
            "cantidad": "1",
            "precioUnitario": "100.00",
            "precioTotalSinImpuesto": "100.00"
        }]
    })
});

const factura = await response.json();
console.log('Factura creada:', factura);

📦 Stack Tecnológico

Node.js Express PostgreSQL Docker Render

Categoría Tecnología Propósito
Backend Node.js + Express.js Servidor web y API REST
XML Processing xmlbuilder Generación de XML según SRI
Firma Digital node-forge Manejo de certificados P12
Web Services soap Comunicación con SRI
Base de Datos PostgreSQL Persistencia (preparado)
Seguridad API Key + Helmet Autenticación y protección
Deploy Render/Railway Hosting en la nube

🏗️ Estructura del Proyecto

api-facturacion-electronica-ecuador/
├── 📂 controllers/          # Lógica de controladores
│   └── factura.controller.js
├── 📂 routes/              # Definición de rutas API
│   └── factura.routes.js
├── 📂 services/            # Lógica de negocio
│   ├── sri.service.js
│   └── sri-webservices.js
├── 📂 utils/               # Utilidades y helpers
│   └── xmldsig.js
├── 📂 database/            # Esquemas de base de datos
│   └── schema.sql
├── 📂 public/              # Archivos estáticos
│   └── index.html
├── 📄 app.js               # Punto de entrada principal
├── 📄 package.json         # Dependencias y scripts
├── 📄 Dockerfile           # Containerización
├── 📄 ejemplo-factura.json # Datos de prueba
└── 📄 README.md           # Este archivo

🚀 Instalación y Uso Local

⚡ Inicio Rápido:

# 1. Clonar el repositorio
git clone https://github.com/mat1520/api-facturacion-electronica-ecuador.git
cd api-facturacion-electronica-ecuador

# 2. Instalar dependencias
npm install

# 3. Configurar variables de entorno
cp .env.example .env

# 4. Ejecutar en desarrollo
npm run dev

# 5. ¡Listo! API corriendo en http://localhost:3000

🔧 Variables de Entorno:

# Configuración del Servidor
PORT=3000

# Configuración del SRI
SRI_ENVIRONMENT=PRUEBAS
EMISOR_RUC=1234567890001
EMISOR_RAZON_SOCIAL=MI EMPRESA S.A.
EMISOR_NOMBRE_COMERCIAL=MI EMPRESA
EMISOR_DIRECCION_MATRIZ=Av. Principal 123 y Secundaria

# API Key para seguridad
API_KEY=demo_api_key_2025_ecuador_sri

# Certificado P12 (opcional para demo)
P12_BASE64=
P12_PASSWORD=

📖 Documentación de la API

🔐 Autenticación

Todas las solicitudes a /api/facturas requieren el header:

x-api-key: render_demo_api_key_2025_ecuador_sri

📋 Endpoints Disponibles

🏥 Health Check

GET /health

Respuesta:

{
  "status": "OK",
  "message": "API de Facturación Electrónica Ecuador funcionando correctamente",
  "timestamp": "2025-07-09T03:45:21.123Z"
}

📄 Crear Factura

POST /api/facturas
Content-Type: application/json
x-api-key: render_demo_api_key_2025_ecuador_sri

Body de ejemplo:

{
  "infoFactura": {
    "fechaEmision": "08/07/2025",
    "razonSocialComprador": "EMPRESA DEMO S.A.",
    "identificacionComprador": "0987654321001",
    "tipoIdentificacionComprador": "04",
    "totalSinImpuestos": "100.00",
    "totalDescuento": "0.00",
    "totalConImpuestos": [
      {
        "codigo": "2",
        "codigoPorcentaje": "2",
        "baseImponible": "100.00",
        "valor": "12.00"
      }
    ],
    "importeTotal": "112.00",
    "moneda": "DOLAR"
  },
  "detalles": [
    {
      "codigoPrincipal": "PROD001",
      "descripcion": "Producto de prueba",
      "cantidad": "1.00",
      "precioUnitario": "100.00",
      "descuento": "0.00",
      "precioTotalSinImpuesto": "100.00",
      "impuestos": [
        {
          "codigo": "2",
          "codigoPorcentaje": "2",
          "tarifa": "12.00",
          "baseImponible": "100.00",
          "valor": "12.00"
        }
      ]
    }
  ]
}

Respuesta exitosa:

{
  "mensaje": "Factura procesada exitosamente",
  "resultado": {
    "claveAcceso": "0807202501123456789000110010010316726391234567814",
    "estado": "AUTORIZADA",
    "fechaProceso": "2025-07-08T10:30:00.000Z",
    "autorizacion": {
      "numeroAutorizacion": "0807202501123456789000110010010316726391234567814",
      "fechaAutorizacion": "2025-07-08T10:30:00.000Z",
      "estado": "AUTORIZADO"
    }
  }
}

📋 Listar Facturas

GET /api/facturas
x-api-key: render_demo_api_key_2025_ecuador_sri

🔍 Consultar Factura

GET /api/facturas/{claveAcceso}
x-api-key: render_demo_api_key_2025_ecuador_sri

🛠️ Despliegue

🌐 Deploy en Render (Recomendado)

Deploy to Render

  1. Haz clic en el botón "Deploy to Render"
  2. Conecta tu cuenta de GitHub
  3. ¡Automáticamente se desplegará!

🚄 Deploy en Railway

Deploy on Railway

🐳 Deploy con Docker

# Construir imagen
docker build -t api-facturacion-ecuador .

# Ejecutar contenedor
docker run -p 3000:3000 \
  -e API_KEY=tu_api_key \
  -e SRI_ENVIRONMENT=PRUEBAS \
  api-facturacion-ecuador

📊 Estado del Proyecto

✅ Implementado:

  • Generación de XML según estándares SRI
  • Cálculo de clave de acceso con módulo 11
  • API RESTful completa
  • Autenticación por API Key
  • Validación de datos de entrada
  • Manejo de errores robusto
  • Despliegue en la nube
  • Documentación completa

🚧 En Desarrollo:

  • Firma XMLDSig real (requiere certificado P12)
  • Integración con web services reales del SRI
  • Base de datos PostgreSQL
  • Sistema de logs avanzado
  • Tests unitarios y de integración

🔮 Roadmap:

  • Autenticación JWT
  • Rate limiting
  • Dashboard web
  • Notificaciones automáticas
  • Exportación a PDF
  • API versioning

🤝 Contribuir

¡Las contribuciones son bienvenidas! 🎉

🔄 Proceso:

  1. Fork el repositorio
  2. Crea una rama feature (git checkout -b feature/nueva-caracteristica)
  3. Commit tus cambios (git commit -m 'feat: nueva característica')
  4. Push a la rama (git push origin feature/nueva-caracteristica)
  5. Abre un Pull Request

🐛 Reportar Bugs:

Abre un issue en GitHub con:

  • Descripción del bug
  • Pasos para reproducir
  • Comportamiento esperado vs actual
  • Screenshots (si aplica)

💡 Sugerir Features:

¡Todas las ideas son bienvenidas! Abre un issue con la etiqueta enhancement.

📞 Soporte y Contacto

🔧 Soporte Técnico

Telegram GitHub Issues

Para dudas técnicas, contacta por Telegram: @MAT3810

📚 Recursos Adicionales:

💝 Apoya el Proyecto

☕ ¿Te gusta este proyecto?

¡Ayúdanos a mantenerlo y mejorarlo!

PayPal

Tu donación nos ayuda a:

  • 🚀 Mantener la API funcionando 24/7
  • 🔧 Desarrollar nuevas características
  • 🐛 Corregir bugs y mejorar la calidad
  • 📚 Crear mejor documentación
  • 🆓 Mantener el proyecto gratuito y open source

PayPal Donation

🌟 Otras formas de apoyar:

  • ⭐ Dale una estrella a este repositorio
  • 🐦 Comparte el proyecto en redes sociales
  • 📢 Recomienda la API a otros desarrolladores
  • 🤝 Contribuye con código o documentación

📄 Licencia

MIT License

Este proyecto está bajo la Licencia MIT

Ver el archivo LICENSE para más detalles.

🏆 Reconocimientos

💎 Desarrollado por:

  • @mat1520 - Creador y desarrollador principal

🙏 Agradecimientos especiales:

  • Comunidad de desarrolladores ecuatorianos 🇪🇨
  • Servicio de Rentas Internas (SRI) por las especificaciones técnicas
  • Contribuidores del proyecto open source

🎯 Inspiración:

Este proyecto nace de la necesidad de democratizar la facturación electrónica en Ecuador, proporcionando herramientas gratuitas y de calidad para todos los desarrolladores.

🇪🇨 Hecho con ❤️ para Ecuador

Desarrollado con pasión para la comunidad ecuatoriana de desarrolladores

Ecuador Open Source

⭐ Si este proyecto te ayudó, ¡dale una estrella! ⭐

© 2025 @mat1520 - Todos los derechos reservados

About

API REST para la gestión de facturación electrónica en Ecuador, cumpliendo con todos los requisitos técnicos del SRI.

api-facturacion-electronica-ecuador.onrender.com

Topics

api facturacion sri ecuador facturas facturacion-electronica facturacion-electronica-ecuador

Resources

Readme

License

MIT license
Activity

Stars

8 stars

Watchers

0 watching

Forks

2 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages