Plataforma de comisiones bancarias
Construí yo solo el ciclo mensual de comisiones de los asesores que venden los créditos de libranza de Banco GNB Sudameris: del Excel del banco a las cuentas de cobro firmadas y el archivo de pagos masivos del banco.
Problema
Lejarde & Ortiz S.A.S. es proveedor de Banco GNB Sudameris: sus asesores comerciales venden los créditos de libranza del banco y los coordinadores los supervisan por ciudad. Cada mes el banco envía un Excel con los créditos desembolsados, y cada asesor y coordinador cobra una comisión sobre ellos. Ese ciclo se hacía a mano: dividir el Excel, repartirlo a los coordinadores por WhatsApp y correo, recoger correcciones, aplicar descuentos y reintegros en una hoja de cálculo, perseguir las cuentas de cobro firmadas y teclear cada pago en el banco.
Qué construí
Una plataforma web que lleva todo el ciclo mensual, con un portal para cada rol: administración, coordinador y asesor.
- Carga y cruce del Excel. La administración sube el archivo del banco. El parser normaliza las variantes de cabecera, los importes y las fechas de Excel, y marca las filas inválidas con su motivo. Cada crédito se asigna a su asesor por el código de vendedor y a un coordinador según asignaciones con fecha; los códigos desconocidos esperan en una cola.
- Un ciclo auditado de cinco estados. Cada mes pasa de cargado a en revisión, en ajuste, listo para exportar y cerrado, y cada transición queda registrada. Los coordinadores aprueban créditos o proponen cambios, como un crédito vendido en otra ciudad; la administración los acepta o los rechaza.
- Comisiones por tramos. Reglas con fecha y por persona pagan una tarifa por millón de pesos que sube cuando el volumen mensual del asesor supera ciertos hitos; los coordinadores cobran sobre el volumen de su equipo. Cada recálculo crea una nueva versión de los pagos.
- PDF firmados. Los asesores añaden sus datos bancarios y su firma y eligen pago total, parcial o dividido. La plataforma genera cada cuenta de cobro en PDF con el importe en letras y la certificación del Estatuto Tributario.
- El archivo de pagos del banco. Exporta el archivo de pagos masivos de GNB: una línea de ancho fijo de 238 caracteres por beneficiario, y la exportación se detiene si una sola línea no cuadra.
Mi papel
Único desarrollador: 118 de 118 commits, del modelo de datos al despliegue con Docker. Empecé con FastAPI y Python y a mitad de proyecto lo reescribí en TypeScript sobre Hono. Lo planifiqué con el método BMAD (PRD, arquitectura, historias) y dirigí agentes de IA durante el desarrollo.
Stack
TypeScript sobre Node 22, Hono con plantillas renderizadas en servidor, PostgreSQL 16 con Drizzle, SheetJS para Excel, Puppeteer para los PDF, almacenamiento compatible con S3 y Docker Compose. Unas 68 pruebas unitarias y unas 220 pruebas de extremo a extremo con Playwright, incluidas las de accesibilidad y móvil.
Resultado
En pruebas manuales, el ciclo mensual pasó de 20 horas a 4 horas, un 80 % menos de tiempo. La plataforma genera ella misma las cuentas de cobro firmadas y el archivo del banco, así que nadie tiene que dividir hojas de cálculo ni volver a teclear pagos.
