Integraciones externas

Objetivo

Documentar con qué sistemas externos habla sy-energy, en qué dirección, qué proceso lo dispara y qué falla cuando la integración se cae.

Audiencia

Soporte, infraestructura y desarrollo interno.

Estado documental

• Estado: Borrador
• Última actualización: 2026-08-02
• Owner: Pendiente
• SME requerido: integraciones e infraestructura
• Fuente resumida: configuración de servicios, colas, variables de ambiente y comandos del repositorio.

Corrección respecto a la versión anterior

Una versión previa listaba Supabase (Auth, Postgres, Storage) como integraciones de sy-energy. No lo son. El sistema usa MySQL propio y AWS. La contradicción quedó registrada en validaciones internas.

Resumen

Integración	Dirección	Qué la dispara
API de CENACE	Entrada	ecd:sync, ecd:sync-store, edocuenta:sync
Portal SIM de CENACE	Ambas	Bots vía bot:queue, ecd:upload_invoices, ecd:invoices_status
Factura.com	Salida	ecd:create_invoices, ecd:create_invoice, sync:service document
MEM	Entrada	sync:prices, produce:prices, consume:prices
CFE TX	Entrada	Worker de cola, sync:service cfe-tx
Servicio de demanda	Entrada	service:demand-sync
AWS SQS	Ambas	Todo el procesamiento asíncrono
AWS S3	Ambas	Facturas y documentos de CENACE
AWS Systems Manager	Entrada	Parámetros por ambiente

CENACE — API

Fuente de los Estados de Cuenta Diarios. Se consulta por fecha de operación y subcuenta.

• Autenticación: credenciales del participante, administradas fuera del código.
• Desfase: la sincronización diaria pide el ECD de hace 5 días, porque CENACE no publica de inmediato.
• Si falla: no llegan ECD, y en cascada no hay documentos que facturar. Es la integración de la que depende toda la cadena diaria.

CENACE — Portal SIM

No hay API: la operación se hace navegando el portal con bots. Detalle en Bots y automatizaciones.

• Credenciales: certificado (.cer), llave (.key), usuario y contraseña del participante.
• Transporte: una cola SQS por bot. sy-energy publica la petición; la Lambda responde.
• Fragilidad: al ser navegación de un portal, cualquier cambio de interfaz de CENACE rompe los bots sin previo aviso. Es la integración menos estable del sistema.
• Bloqueo típico: una notificación pendiente en el SIM impide navegar y hace fallar a todos los bots a la vez.

Factura.com

Proveedor de timbrado de CFDI.

• Transporte: API HTTP.
• Configuración: URL de la API, llave de API, llave secreta y versión de CFDI, todas por variable de ambiente.
• Qué se envía: los datos del comprobante a timbrar.
• Si falla: no se emiten facturas. Durante el cierre mensual es un bloqueo total del proceso.
• Dependencia única: no hay proveedor alterno configurado.

Reglas fiscales fijas de los comprobantes emitidos a CENACE (uso de CFDI, forma y método de pago, moneda, unidades y claves de producto) viven codificadas en la librería de CENACE del sistema, no en configuración.

MEM — Precios del mercado

Precios de nodos y zonas de carga, insumo de los cálculos pass-through.

• Almacenamiento: los nodos y precios se manejan en MongoDB.
• Acceso: credenciales dedicadas, separadas de las de la base principal.
• Comandos: sync:prices, produce:prices, consume:prices, remove:prices.
• Si falla: los cálculos de MDA y MTR quedan incompletos o en cero.

CFE TX

Mediciones de demanda de alta tensión provenientes de un SQL Server externo.

• Transporte: cfetx-microservice consulta la base externa y publica en SQS; un worker dedicado de sy-energy consume.
• Restricción: la base externa está protegida por autorización de IP. Solo responde a servidores autorizados.
• Comando relacionado: sync:service cfe-tx.

Servicio de demanda

Demanda de los centros de carga.

• Transporte: conexión a base de datos dedicada más cola interna.
• Comando: service:demand-sync, diario a las 06:00.
• Si falla: los estados de cuenta salen con demanda incompleta. Es un error que no se nota hasta el cierre mensual.

AWS

Servicio	Uso
SQS	Una cola por proceso: creación de facturas, carga de facturas, estatus, sincronización de ECD, balance de CENACE, cada bot del SIM y CFE TX. Las colas se nombran por participante.
S3	Buckets separados para facturas y para documentos de CENACE.
Systems Manager	Parámetros de configuración, con prefijo distinto por ambiente.

Las colas son el punto único de falla del procesamiento asíncrono: si las credenciales de AWS son incorrectas, los comandos de despacho fallan de inmediato; si el worker está caído, los comandos reportan éxito y nada se procesa.

Diagnóstico rápido

Síntoma	Integración a revisar
No llegan ECD	API de CENACE. Confirmar credenciales y disponibilidad del servicio.
Las facturas no se timbran	Factura.com.
Las facturas se crean pero no llegan al SIM	Bots del SIM y bucket de S3.
Los cálculos pass-through dan cero	Precios del MEM y completitud de los ECD.
Falta demanda	Servicio de demanda o CFE TX, según el centro de carga.
Todo lo asíncrono se detuvo	Workers de Supervisor y credenciales de AWS.

Riesgos y gaps

• La operación del SIM depende de navegación de portal: es frágil ante cambios de interfaz y no hay alternativa documentada.
• Proveedor único de timbrado, sin plan de contingencia documentado.
• No está documentado el vencimiento ni la rotación de las credenciales de CENACE por participante.
• No hay monitoreo documentado de disponibilidad de las integraciones; las fallas se detectan por sus efectos.
• Falta documentar el uso de colas DLQ y la política de reintentos por integración.

Próxima revisión

Al documentar los sistemas satélite que participan en cada cadena.