1. Resumen Del Proyecto
El cliente es un negocio comercial y de construcción que gestionaba clientes, operaciones, pagos y ventas diarias en KeepinCRM. La CRM funcionaba como interfaz operativa, pero la lógica financiera vivía alrededor: revisiones manuales, decisiones de managers, caja, deuda, anticipos y aprobaciones de dirección
La CRM no podía asignar automáticamente un pago a las deudas abiertas más antiguas, calcular retrasos, separar clientes sanos de clientes de riesgo, bloquear un paso peligroso hacia despacho o dar a dirección una vista clara de cuentas por cobrar
Mi rol fue construir un financial control layer alrededor de CRM: middleware que lee KeepinCRM por API, aplica reglas de negocio, mantiene su propio audit journal, escribe resultados de vuelta, controla deuda, genera reporting y conecta caja con hardware fiscal físico
No fue “conectar una API”. Fue convertir un proceso vivo de dinero, deuda, caja, managers y decisiones de dirección en un sistema controlado
2. Situación Inicial
•Los pagos no se asignaban automáticamente: el cliente podía pagar a nivel de cuenta, pero el negocio necesitaba cerrar primero las operaciones abiertas más antiguas
•La deuda y el anticipo no eran sistémicos: deuda actual, sobrepago, saldos y días vencidos debían ser visibles en CRM, pero CRM no tenía esa lógica nativa
•El control de crédito era manual: un manager podía seguir moviendo una operación aunque el cliente superara el límite o tuviera deuda vencida
•Dirección necesitaba reporting operativo: saldo inicial, despachos, pagos, deuda final, anticipo, días vencidos y estado
•La caja era física y legacy: el puesto del cajero usaba Windows 7 y el dispositivo fiscal era local
•1C/RDP y la caja tenían que convivir: el agente no podía capturar el dispositivo todo el tiempo, solo durante la impresión
•Los duplicados eran peligrosos: procesar un pago dos veces o imprimir dos recibos podía crear errores financieros reales
3. Alcance
•Diseñar middleware entre KeepinCRM y las reglas financieras del negocio
•Implementar FIFO allocation: las deudas más antiguas se pagan primero
•Manejar pagos parciales, sobrepagos, anticipos y clientes sin operaciones abiertas
•Recalcular deuda, anticipo, retraso, estado del cliente y utilización del límite
•Implementar estados OK / RISK / BLOCK
•Bloquear acciones críticas cuando se exceden límites o vencimientos
•Dar a dirección un manual unblock con audit log
•Construir reporting de cuentas por cobrar con filtros y exportación Excel
•Crear receipt queue y agente local para caja fiscal
•Añadir background radar para pagos nuevos y cambios de operaciones
4. Solución
Financial Middleware Architecture
•KeepinCRM siguió siendo la interfaz del equipo, mientras la lógica financiera se movió a un servicio FastAPI
•El middleware lee datos por API, los mapea a un modelo financiero y escribe resultados controlados de vuelta a CRM
•El servicio se separó en módulos: CRM client, allocation engine, debt calculator, blocker, receivables reporter, receipt queue, local-agent endpoints y SQLite journal
•SQLite funciona como audit journal para allocations, recalculations, block events, receipts, processed payments, agent status y agent logs
FIFO Payment Allocation
•El sistema toma operaciones abiertas del cliente, selecciona las que tienen deuda, las ordena por fecha y cierra primero la deuda más antigua
•Los pagos parciales dejan saldo claro, los sobrepagos se convierten en anticipo y los clientes sin operaciones abiertas no pierden dinero en comentarios
•La misma payment ID no se procesa dos veces gracias a idempotency y allocation journal
Debt Control & Blocking
•El sistema calcula deuda, anticipo, días vencidos, utilization y estado del cliente
•Los estados OK / RISK / BLOCK convierten números en acción operativa
•BLOCK detiene el movimiento riesgoso de la operación
•Dirección puede desbloquear, pero solo con razón y registro en block_log
Reporting & Cash Register
•El reporting calcula opening balance, charges, payments, closing balance, advance, overdue days y debt status
•Excel export da a dirección una herramienta práctica de control
•Receipt queue conecta CRM con la caja física mediante estados pending, completed y failed
•El agente local Windows toma el recibo, imprime en el dispositivo fiscal y devuelve el resultado
•El agente toma el dispositivo solo durante la impresión y lo libera para el software legacy
Radar & Background Processing
•Background radar detecta pagos nuevos y cambios de operaciones
•Un pago nuevo lanza allocation y control de bloqueo
•Un cambio de operación lanza recálculo de riesgo
•Daily recalculation detecta vencimientos incluso sin acción del manager
5. Resultado
•CRM se convirtió en interfaz para un proceso financiero controlado
•Los pagos empezaron a asignarse por una regla FIFO clara
•Deuda, anticipo, retraso y estado del cliente se volvieron calculables
•Los clientes riesgosos recibieron stop-points automáticos
•Dirección obtuvo override con audit log
•Reporting de cuentas por cobrar quedó disponible por API/UI y Excel
•La caja se conectó a CRM mediante cola, estados y agente local
•Windows 7 y hardware fiscal físico fueron integrados sin reemplazar el puesto del cajero
6. Resultado Técnico
El resultado fue un financial control layer para KeepinCRM:
•KeepinCRM API integration
•Receivables reporter con Excel export
7. Por Qué Fue Difícil
El proyecto fue difícil porque conectaba CRM, reglas financieras y un dispositivo fiscal físico en una estación Windows antigua
Había que mantener la interfaz CRM, dar control a dirección, evitar pagos y recibos duplicados, mostrar deuda real y no romper el puesto del cajero. No fue una integración genérica, sino una capa operativa de control financiero alrededor de CRM
