GM Fiscal — Introducción
GM Fiscal Backend es el sistema de gestión fiscal centralizado de GM Transporte. Resuelve el problema de volumen y trazabilidad que enfrentan las empresas de transporte medianas y grandes ante el SAT: una sola empresa puede emitir y recibir decenas de miles de Comprobantes Fiscales Digitales por Internet (CFDIs) por período. Descargarlos, cruzarlos contra el ERP y generar los reportes declaratorios de forma manual no es viable ni confiable.
Propósito del sistema
El sistema automatiza tres procesos fiscales interdependientes que cubren el ciclo SAT completo:
Descarga de CFDIs. Obtiene los comprobantes fiscales directamente del SAT a través de dos proveedores intercambiables: Prodigia (HTTP REST, conector legado) y GM Hades Bóveda Fiscal (gRPC, alta escala). El proveedor activo se selecciona mediante la variable de entorno INVOICE_PROVIDER. Con Hades, el sistema descarga XMLs vía SFTP en lotes paralelos, los parsea con 50 goroutines concurrentes y los almacena en caché dual (PostgreSQL + Azure Blob) para que las consultas posteriores no requieran contactar el SAT.
Conciliación fiscal. Cruza las facturas del ERP interno contra las facturas oficiales del SAT. La función central MakeConciliacion es pura: sin efectos secundarios, determinística, verificable en tests sin infraestructura. Clasifica cada comprobante en cuatro categorías —presente en ambas fuentes, solo en ERP, solo en SAT, o cancelado— y preserva los impuestos de cada origen en arrays separados para detectar discrepancias exactas de tasas y montos.
Generación de reportes. Produce el reporte R21 (declaración mensual de IVA) y el RAMCI (reporte anual de movimientos) en formato Excel compatible con el SAT. El procesamiento es asincrónico: el sistema acepta la solicitud, responde 202, genera el reporte en segundo plano y notifica al cliente en tiempo real vía WebSocket.
Capacidades principales
| Capacidad | Descripción |
|---|---|
| Descarga masiva CFDI | Hasta 50,000 CFDIs por solicitud con paralelismo interno |
| Caché dual | PostgreSQL 5434 + Azure Blob para evitar reconsultas al SAT |
| Conciliación pura | Función determinística sin efectos secundarios |
| Reportes fiscales | R21 mensual + RAMCI anual en Excel formato SAT |
| Notificaciones en tiempo real | WebSocket por RFC de empresa |
| RFC multi-empresa | Tres RFC distintos por empresa (BD, SAT, ERP) |
| Procesamiento asincrónico | Workers con semáforos y backoff exponencial |
Stack tecnológico
| Componente | Tecnología | Versión |
|---|---|---|
| Lenguaje | Go | 1.24.5 |
| Router HTTP | gorilla/mux | 1.8.1 |
| ORM | GORM | 1.30.0 |
| Driver PostgreSQL | pgx v5 | 5.7.5 |
| gRPC | google.golang.org/grpc | 1.79.1 |
| Protocol Buffers | google.golang.org/protobuf | 1.36.11 |
| WebSocket | gorilla/websocket | 1.5.3 |
| Excel | xuri/excelize | 2.9.1 |
| Azure Blob Storage | azure-storage-blob-go | 0.15.0 |
| JWT | golang-jwt/jwt | 5.3.1 |
| BDD | cucumber/godog | 0.15.1 |
| Testing | stretchr/testify | 1.10.0 |
| Base de datos principal | PostgreSQL 16 | puerto 5433 |
| Caché CFDI | PostgreSQL 16 | puerto 5434 |
Ecosistema de sistemas
GM Fiscal Backend no es un sistema aislado. Se integra con varios servicios del ecosistema GM Transporte:
graph TB
subgraph Usuarios["Usuarios del sistema"]
Contador["Contador (uso diario)"]
Admin["Administrador (configuración)"]
end
subgraph GMFiscal["GM Fiscal Backend (puerto 8046)"]
API["API REST /api/..."]
end
subgraph Internos["Sistemas internos GM Transporte"]
ERP["ERP Contabilidad"]
Servicios["GM Servicios (auth JWT)"]
Hades["Hades Bóveda Fiscal (gRPC)"]
GMLogs["GM Logs (auditoría)"]
end
subgraph Externos["Sistemas externos"]
SAT["SAT México"]
Prodigia["Prodigia (conector SAT legado)"]
Azure["Azure Blob Storage"]
end
subgraph Datos["Bases de datos"]
PG["PostgreSQL principal (5433)"]
PGCache["PostgreSQL caché CFDI (5434)"]
end
Contador --> API
Admin --> API
API --> ERP
API --> Servicios
API --> Hades
API --> Prodigia
API --> GMLogs
Hades --> SAT
Prodigia --> SAT
API --> Azure
API --> PG
API --> PGCache
Modelo de concurrencia
El sistema está diseñado para procesar 50,000 o más CFDIs por consulta, donde cada XML tiene un tamaño promedio de 15 KB, lo que equivale a aproximadamente 750 MB por consulta completa. Cada componente tiene un modelo de concurrencia explícito con límites definidos para evitar saturación.
| Componente | Modelo | Límite |
|---|---|---|
| Descarga blob caché | Semáforo + goroutines | 50 goroutines |
| Parseo XML | Semáforo + goroutines | 50 goroutines |
| Descarga SFTP Hades | Semáforo de lotes | 5 lotes × 30 UUIDs |
| Pre-enriquecimiento | 2 goroutines × 4 chunks | 8 consultas DB en paralelo |
| Worker de reportes | Semáforo | 3 reportes simultáneos |
| Worker de descargas | Pool adaptativo | mín. 2 / máx. 8 workers |
Puerto y entornos
El servidor HTTP escucha en el puerto 8046. El sistema soporta cuatro perfiles de entorno configurables mediante Docker Compose: dev, qa, staging y prod. El perfil activo determina el archivo .env que se carga al iniciar.
Resumen
- GM Fiscal Back automatiza el ciclo SAT completo: descarga de CFDIs, conciliación ERP↔SAT y generación de reportes R21/RAMCI.
- El proveedor de facturas es intercambiable entre Prodigia (HTTP REST, legado) y GM Hades (gRPC, alta escala) mediante variable de entorno.
- El sistema escala hasta 50,000 CFDIs por consulta con paralelismo interno controlado por semáforos y goroutines.
- La función
MakeConciliaciones pura y determinística, lo que la hace completamente verificable sin infraestructura. - Los reportes se generan de forma asincrónica con notificación en tiempo real por WebSocket.