Plantillas de Cascada (Waterfall)

Requisitos previos de acceso

• Permiso (módulo): creditConfigManage (para crear/editar). Lectura habilitada por viewCredits.
• Licencia/Feature: CREDIT_INVESTMENTS habilitada en la licencia del tenant (Vault).
• Contenedor del menú: TOKENIZACIÓN → grupo Crédito Tokenizado

Qué es / cuándo usar

La Plantilla de Cascada (Waterfall) define el orden de distribución de los fondos cuando una cuenta por cobrar es liquidada. Especifica, paso a paso, quién recibe primero y bajo qué regla: primero el principal del inversor, luego el rendimiento del inversor, la tarifa de la plataforma, el eventual excedente del originador y la reserva. Es el mecanismo que garantiza que la cascada de pagos siga siempre la misma prioridad contratada.

Use esta pantalla para estandarizar cómo se reparten los fondos liquidados entre las partes en la liquidación (settlement), en lugar de definir el orden caso por caso.

Requisitos previos

• Permiso: creditConfigManage (permiso doble — enum CPM + módulo dinámico en DB).
• Licencia/Feature: CREDIT_INVESTMENTS habilitada.
• Dependencias: ninguna para crear la plantilla; es consumida en la liquidación (settlement) de una operación.

Paso a paso

1. Acceda a Crédito Tokenizado → Plantillas de Cascada.
2. Filtre por Activo si es necesario.
3. Haga clic en Crear.
4. Complete Nombre, % de Reserva y la Regla de Redondeo.
5. En el bloque Pasos, haga clic en Agregar paso y configure cada fila: Tipo de Ítem, Tipo de Regla y, si aplica, el Valor. El orden se numera automáticamente (primer paso = máxima prioridad).
6. Reordene eliminando/reincorporando pasos (la renumeración es automática).
7. Haga clic en Guardar.

Campos

Campo	Qué es	¿Obligatorio?	Efecto en el sistema/backend
Nombre	Identificación de la plantilla	Sí	Almacenado en name.
% de Reserva	Porcentaje retenido como reserva antes/durante la cascada	No (default 0)	Almacenado en reservePercentage.
Regla de Redondeo	Cómo redondear valores fraccionados: FLOOR (hacia abajo, 10.9→10), CEIL (hacia arriba, 10.1→11), ROUND (al más cercano)	No	Almacenado en roundingRule (o null si está vacío). Garantiza consistencia de centavos en la división entre partes.
Paso → Orden	Posición en la cola de distribución	Sí (automático)	Almacenado en order. En la ejecución, los ítems se ordenan por prioridad (el menor primero) y los desembolsos ocurren en esa secuencia.
Paso → Tipo de Ítem	A quién/para qué paga el paso: INVESTOR_PRINCIPAL, INVESTOR_YIELD, PLATFORM_FEE, ORIGINATOR_EXCESS, RESERVE	Sí	Almacenado en itemType. Dirige el desembolso a la cuenta correcta y clasifica el asiento en el libro mayor (INVESTOR, PLATFORM u ORIGINATOR).
Paso → Tipo de Regla	Cómo se calcula el monto del paso: PERCENT, FIXED o REMAINDER	Sí	Almacenado en rule.type. PERCENT/FIXED usan el Valor; REMAINDER distribuye lo que quedó (sin usar Valor).
Paso → Valor	Porcentaje (PERCENT) o monto (FIXED)	Condicional	Almacenado en rule.value. Omitido cuando el tipo es REMAINDER.
Activo	Activa/desactiva la plantilla	Sí (default Sí)	Almacenado en active.
Versión	Número de versión	No (default 1)	Almacenado en version.

El formulario construye automáticamente el stepsJson (estructura { steps: [{ order, itemType, rule: { type, value } }] }). No se edita el JSON manualmente.

Cómo se ejecuta la cascada (visión del ejecutor)

En la liquidación de un settlement, el ejecutor de waterfall:

1. Localiza la cuenta del Escrow Pool (pool de garantía de la plataforma).
2. Ordena los ítems por prioridad (el número menor primero).
3. Para cada ítem, libera los fondos del Escrow Pool hacia la cuenta destino y registra el asiento en el libro mayor (ledger) con una idempotencyKey por settlement+itemType.
4. Si un ítem falla, el ejecutor continúa con los siguientes (no aborta toda la cascada).

Acciones y modales

• Crear / Actualizar: guarda la plantilla vía createWaterfallTemplate / updateWaterfallTemplate. Botón visible solo con creditConfigManage.
• Agregar / Eliminar paso: manipulan la lista y renumeran el orden automáticamente.
• Editar: carga la plantilla y reconstruye los pasos a partir del stepsJson guardado.

Por definir la división del dinero, guardar puede requerir step-up (contraseña + MFA) según el entorno.

Reglas de negocio / precauciones

Atención

• El orden es la prioridad. Quien está primero recibe primero. Coloque siempre INVESTOR_PRINCIPAL antes de INVESTOR_YIELD, y ambos antes de PLATFORM_FEE/ORIGINATOR_EXCESS, salvo contrato específico.
• Use REMAINDER en el último paso. El paso REMAINDER distribuye el saldo restante; dejarlo en el medio puede dejar en cero los pasos siguientes. Normalmente ORIGINATOR_EXCESS es REMAINDER.
• REMAINDER ignora el Valor. Aunque ingrese un valor, no se almacena para pasos REMAINDER.
• El fallo parcial no revierte los desembolsos ya realizados. El ejecutor continúa con el siguiente ítem; un ítem que falló queda pendiente sin deshacer los anteriores — requiere conciliación manual.

Distribución financiera

• La ejecución de la cascada mueve dinero real del Escrow Pool hacia inversores/plataforma/originador. Una vez liberado el desembolso, no hay rollback automático — una plantilla incorrecta distribuye incorrectamente. Valide el orden y los valores antes de activar.

• Valores financieros: porcentajes y montos se tratan como BigNumber; la Regla de Redondeo define explícitamente el tratamiento de fracciones de centavo para evitar divergencias de conciliación.
• Idempotencia: los desembolsos se registran con idempotencyKey por settlement+itemType — reprocesar una liquidación es seguro y no duplica asientos. En flujos financieros del ecosistema, el error E00021 ("already processed") significa éxito (ya procesado), no fallo.

Ejemplos

Escenario 1 — Cascada estándar inversor-primero

1. Nombre: "Estándar Senior". % Reserva: 0. Redondeo: FLOOR.
2. Pasos:
   • 1 · INVESTOR_PRINCIPAL · REMAINDER — devuelve el principal invertido.
   • 2 · INVESTOR_YIELD · PERCENT · valor conforme al rendimiento contratado.
   • 3 · PLATFORM_FEE · PERCENT · tarifa de la plataforma.
   • 4 · ORIGINATOR_EXCESS · REMAINDER — lo que sobre vuelve al originador.
3. Guardar.

Nota: si hay dos REMAINDER, el primero consume el saldo; ajuste para usar FIXED/PERCENT en el principal y reserve REMAINDER solo para el excedente del originador.

Escenario 2 — Cascada con reserva y tarifa fija

1. Nombre: "Con Reserva 5%". % Reserva: 5. Redondeo: ROUND.
2. Pasos:
   • 1 · RESERVE · PERCENT · 5.
   • 2 · INVESTOR_PRINCIPAL · FIXED · monto del principal.
   • 3 · INVESTOR_YIELD · PERCENT · rendimiento.
   • 4 · PLATFORM_FEE · FIXED · tarifa fija.
   • 5 · ORIGINATOR_EXCESS · REMAINDER.
3. Guardar.

Resultado: en la liquidación, el 5% va a reserva, el principal y el rendimiento del inversor se pagan a continuación, la plataforma recibe la tarifa fija, y el saldo restante vuelve al originador.

Escenario 3 — Cascada "originador subordinado"

1. Nombre: "Originador Subordinado". Redondeo: FLOOR.
2. Pasos: INVESTOR_PRINCIPAL → INVESTOR_YIELD → PLATFORM_FEE → ORIGINATOR_EXCESS (REMAINDER).
3. Guardar.

Resultado: el originador solo recibe excedente después de todos los inversores y la plataforma — estructura típica de operación donde el originador absorbe la primera pérdida.

Pantallas relacionadas

• Políticas de Crédito
• Plantillas de Precios
• Guía de Crédito
• Crédito Tokenizado (índice del grupo)