Descripción General

finalitixspeiapi es la API privada que actúa como intermediario entre el backend principal de Finalitix y el proveedor bancario STP (Sistema de Transferencias y Pagos Interbancarias, institución 00000) en México.

Stack tecnológico

Componente	Tecnología	Versión
Runtime	Node.js	18+
Framework	Express	4.19.2
ORM	Sequelize	6.29.0
Base de datos	MySQL	vía mysql2 3.9.7
Logging	Winston + CloudWatch	3.18.3
Trazabilidad	AWS X-Ray	3.11.0
Mensajería	AWS SQS	aws-sdk 2.x

Responsabilidades

Esta API tiene dos grupos de rutas con propósitos distintos:

/api/v1/* — Operaciones iniciadas por Finalitix

El backend de Finalitix llama estos endpoints para ejecutar operaciones bancarias: crear cuentas, enviar transferencias, consultar saldos y conciliaciones.

/stp/v1/* — Notificaciones entrantes de STP

STP llama estos endpoints directamente para informar cambios de estado: activación de cuentas, abonos recibidos y actualizaciones de transacciones.

Diagrama de componentes principales

finalitixspeiapi
├── routes/
│   ├── connectionRoutes.js      → /api/v1/*
│   └── notificationRoutes.js    → /stp/v1/*
├── controllers/
│   ├── connectionController.js  → dispatcher hacia AccountController y TransactionController
│   ├── notificationController.js → dispatcher hacia TransactionNotificationController
│   ├── AccountController.js
│   ├── TransactionController.js
│   └── TransactionNotificationController.js
├── models/                      → acceso a MySQL vía Sequelize
├── lib/
│   ├── cryptoHandler.js         → firmas RSA-SHA256
│   ├── bankHelper.js            → cliente HTTP hacia STP
│   ├── helper.js                → AWS SDK (Lambda, SQS, Secrets Manager)
│   └── logger.js                → Winston + CloudWatch
└── middleware/
    └── latencyLogger.js         → métricas de latencia en CloudWatch

Puerto de ejecución

Ambiente	Puerto
Desarrollo	3010 (fijo)
Producción	process.env.PORT

Instrumentación

• AWS X-Ray: segmento Finalitix-STP-API aplicado globalmente como middleware
• CloudWatch Metrics: namespace /finalitix/stp-api/performance, dimensiones Endpoint, Method, StatusCode
• CloudWatch Logs: grupo finalitixSpeiAPILogs, stream {EC2_INSTANCE_ID}-{fecha}