Una API para la gestión, emisión y transmisión de Documentos Tributarios Electrónicos (DTE) que cumple con los requisitos establecidos por la autoridad fiscal.
📚 Documentación completa disponible en: chainedpixel.github.io/doc-api-facturacion-sv
- Emisión de facturas electrónicas
- Emisión de comprobantes de crédito fiscal (CCF)
- Emisión de comprobantes de retención
- Invalidación de documentos
- Manejo de contingencias
- Transmisión de documentos a Hacienda
- Monitoreo de métricas
- Autenticación JWT
- Firmado electrónico de documentos
Este proyecto está implementado siguiendo principios de:
- Arquitectura Hexagonal (Ports & Adapters): Separación clara entre lógica de dominio y acceso a recursos externos
- Domain Driven Design (DDD): Modelado de dominio basado en el negocio
- Dominio: Modelos, reglas de negocio y puertos (interfaces)
- Aplicación: Casos de uso y orquestación
- Infraestructura: Adaptadores para bases de datos, API, comunicación externa, etc.
- Bootstrap: Configuración e inicialización de dependencias
- Go 1.23: Lenguaje de programación principal
- Base de datos: Actualmente soporta MySQL y PostgreSQL
- Redis: Caché y almacenamiento de tokens
- Docker y Docker Compose: Contenerización y orquestación de servicios
- Gorilla Mux: Router HTTP
- GORM: ORM para acceso a base de datos
- JWT: Autenticación basada en tokens
- Docker y Docker Compose
- Go 1.23+ (sólo para desarrollo)
- Certificados de firma digital (para ambiente de producción o pruebas)
- Clonar el repositorio:
git clone https://github.com/chainedpixel/api-facturacion-sv.git
cd dte-microservice-
Colocar certificados de firma digital en la carpeta
scripts/temp(crear si no existe) -
Iniciar los servicios:
docker-compose up -ddocker-compose --profile dev up -dLas variables de entorno están predefinidas en el archivo docker-compose.yml. Modifícalo según tus necesidades.
El servicio expone las siguientes APIs:
POST /api/v1/auth/login: Autenticación de usuariosPOST /api/v1/auth/register: Registro de nuevos clientes
POST /api/v1/dte/invoices: Crear factura electrónicaPOST /api/v1/dte/ccf: Crear comprobante de crédito fiscalPOST /api/v1/dte/retention: Crear comprobante de retenciónPOST /api/v1/dte/creditnote: Crear nota de créditoPOST /api/v1/dte/invalidation: Invalidar documentoGET /api/v1/dte: Listar todos los documentos emitidos por el usuarioGET /api/v1/dte/{id}: Obtener documento específico por ID
GET /api/v1/test: Prueba los componentes del sistemaGET /api/v1/metrics: Obtener métricas de los endpointsGET /api/v1/health: Estado de salud del servicio
Nota: Para más detalles sobre los endpoints y ejemplos de uso, consulta la documentación completa.
El sistema maneja automáticamente contingencias cuando:
- Hay fallas de conexión con el sistema de Hacienda
- Hay problemas de conectividad a internet
- Hay fallas en el firmado digital de documentos
- Sistema de Hacienda no está disponible
Los documentos se almacenan y retransmiten según las reglas configuradas.
- Autenticación basada en tokens JWT
- Validación estricta de entradas
- Firmado digital de documentos
Este proyecto utiliza un pipeline de integración continua con dos ramas específicas para la generación de builds:
- release-amd64: Compilación y despliegue de la versión para arquitectura
amd64 - release-arm64: Compilación y despliegue de la versión para arquitectura
arm64
Cada rama se encarga de generar imágenes optimizadas para su respectiva arquitectura, asegurando compatibilidad en distintos entornos de ejecución.
Para contribuir a este proyecto:
- Analizar documentación antes de sugerir implementaciones
- Respetar la arquitectura establecida
- Mantener consistencia con implementaciones existentes
- Validar contra JSON Schema
- No asumir comportamientos no documentados