Arquitectura de un core de crédito moderno: servicios, APIs y datos

Introducción

Un core de crédito es el sistema central que gestiona todo el ciclo de vida de las operaciones crediticias de una entidad financiera: desde la solicitud y originación hasta la gestión de cartera, la causación contable y la recuperación. Diseñar la arquitectura de este sistema requiere equilibrar múltiples exigencias: rendimiento, seguridad, cumplimiento regulatorio, escalabilidad y mantenibilidad. En este artículo exploramos los principios de diseño, las capas de servicio y el modelo de datos de un core de crédito moderno.

Principios de diseño

Event-driven (orientado a eventos)

Un core de crédito moderno se diseña alrededor de eventos que representan cambios significativos en el estado del sistema:

CreditoCreado: cuando se registra una nueva solicitud
CreditoPreaprobado: cuando pasa la evaluación automática
CreditoDesembolsado: cuando se transfieren los fondos
PagoRegistrado: cuando el deudor realiza un pago
CreditoEnMora: cuando un crédito supera los días de gracia

Cada evento desencadena acciones posteriores (notificaciones, actualizaciones contables, recálculos de provisión) de forma desacoplada, lo que permite que los módulos operen de forma independiente.

Idempotencia

Toda operación crítica debe ser idempotente: ejecutarla múltiples veces produce el mismo resultado que ejecutarla una vez. Esto es fundamental para:

Causación diaria: si el proceso se ejecuta dos veces, no duplica asientos
Procesamiento de pagos: si un pago se registra dos veces (por retry de red), solo se aplica una vez
Generación de reportes: recalcular un reporte produce los mismos números

Audit trail (trazabilidad)

Cada acción en el sistema debe quedar registrada con:

Quién la ejecutó (usuario o proceso automático)
Cuándo se ejecutó (timestamp con zona horaria)
Qué se modificó (estado anterior y estado nuevo)
Por qué (justificación o regla de negocio aplicada)

Esta trazabilidad es un requisito regulatorio de la Superfinanciera y una necesidad operativa para la resolución de disputas y la auditoría.

Seguridad por diseño

Row Level Security (RLS): cada tabla define políticas que restringen qué filas puede ver o modificar cada usuario según su rol
Cifrado en tránsito y en reposo: toda la comunicación se realiza sobre HTTPS y los datos sensibles se almacenan cifrados
Principio de mínimo privilegio: cada servicio y usuario tiene solo los permisos estrictamente necesarios

Capas de la arquitectura

Capa de presentación (Frontend)

La interfaz de usuario se divide en dos portales:

Portal del cliente: solicitud de crédito, seguimiento de estado, consulta de amortización, carga de documentos, pagos
Portal backoffice: gestión de solicitudes, análisis de crédito, administración de cartera, configuración de flujos, reportes

La tecnología típica incluye Next.js con React para interfaces rápidas y componentes reutilizables.

Capa de API (Gateway)

La capa de API expone los servicios del core mediante endpoints RESTful organizados por dominio:

/api/applications: gestión de solicitudes de crédito
/api/credits: operaciones sobre créditos vigentes
/api/payments: registro y consulta de pagos
/api/products: configuración de productos de crédito
/api/customers: gestión de clientes
/api/config/flow: configuración de flujos de crédito

Cada endpoint implementa autenticación, autorización, validación de entrada y manejo de errores estandarizado.

Capa de servicios (Business Logic)

Los servicios encapsulan la lógica de negocio y se organizan por dominio:

ApplicationService: evaluación de solicitudes, pre-aprobación, validaciones
CreditService: gestión del ciclo de vida del crédito
PaymentService: procesamiento de pagos, distribución entre capital e intereses
AmortizationService: generación de tablas de amortización (Francés, Alemán, Americano)
CausacionService: causación diaria de intereses y generación de asientos
ProvisionService: cálculo de provisiones según modelos de la Superfinanciera
NotificationService: envío de notificaciones por email, SMS y push
FlowConfigService: gestión de la configuración de flujos de crédito

Capa de datos

La base de datos es el corazón del sistema. Un diseño moderno utiliza Supabase (PostgreSQL) con:

Tablas principales: credits, payments, amortization_schedules, customers, products, guarantees, insurances
Tablas de configuración: flow_configs, flow_phases, flow_transitions, flow_actions
Tablas de auditoría: timeline_events, audit_logs
Row Level Security: políticas que restringen acceso por rol de usuario
Funciones PostgreSQL: para cálculos complejos que se ejecutan directamente en la base de datos

Modelo de datos: entidades principales

Las entidades principales del modelo de datos de un core de crédito son:

Customer: datos del cliente (identificación, contacto, información financiera)
Product: configuración del producto de crédito (tasas, plazos, montos, tipo de amortización, seguros obligatorios)
Credit: la instancia del crédito (producto asociado, cliente, monto, tasa, plazo, estado, fase actual)
AmortizationSchedule: tabla de amortización con cada cuota planificada (fecha, capital, interés, seguro, saldo)
Payment: registro de cada pago realizado (fecha, monto, distribución entre componentes)
Guarantee: garantías asociadas al crédito (tipo, valor, vigencia, documentos)
Insurance: seguros vinculados (tipo, prima, aseguradora, vigencia)
TimelineEvent: registro de cada evento significativo en la vida del crédito

Flujo de datos: ejemplo de un pago

Cuando un deudor realiza un pago, el flujo de datos atraviesa las capas de la siguiente forma:

Frontend: el operador registra el pago en el portal backoffice (o el sistema lo recibe automáticamente desde el banco)
API: el endpoint /api/payments valida el monto, la fecha y el crédito asociado
PaymentService: distribuye el pago entre los componentes (intereses causados, capital, seguros, mora si aplica) según la prioridad definida
CreditService: actualiza el saldo del crédito y recalcula la tabla de amortización si es necesario
CausacionService: genera los asientos contables del pago (débito a caja, crédito a cartera e intereses por cobrar)
Base de datos: persiste todos los cambios de forma transaccional (todo o nada)
Evento PagoRegistrado: se emite el evento que desencadena notificación al cliente y actualización del dashboard

Conclusión

La arquitectura de un core de crédito moderno debe ser modular, segura, auditable y escalable. Los principios de diseño orientado a eventos, idempotencia y trazabilidad garantizan la integridad de las operaciones financieras. La separación en capas claras (presentación, API, servicios, datos) facilita el mantenimiento y la evolución del sistema. Para las entidades financieras que buscan construir o adoptar un core de crédito, entender esta arquitectura es el primer paso para tomar decisiones tecnológicas informadas y alineadas con los requisitos regulatorios y operativos del mercado colombiano.