Recargos y ajustes
Cuando un título vence sin pago, el monto adeudado crece por los recargos: multa, intereses de mora y, opcionalmente, corrección monetaria. En el sentido inverso, el acreedor puede ofrecer un descuento por puntualidad o anticipación. Es este conjunto lo que transforma el Monto Original en el Monto Actual que el deudor ve en los mensajes de la regla y en el portal.
El motor de recargos fue diseñado para manejar dinero cobrado al deudor sin margen de error: el cálculo es idempotente (recalcular desde cero nunca corrompe ni duplica montos), hecho en centavos enteros con redondeo half-up, y siempre evaluado en la zona horaria de la organización.
Los cuatro recargos
- Multa (
fineAmount) — penalidad por no pagar a tiempo. Incide una única vez después del vencimiento. Puede ser un porcentaje sobre el monto original (percent) o un valor fijo (fixed). - Intereses de mora (
interestAmount) — cargo por el tiempo de atraso. Se acumula pro rata die: cada día vencido suma una fracción. Configurable al mes (percent_month), al día (percent_day) o como valor fijo por día (fixed_day). - Descuento (
discountAmount) — rebaja concedida por pago anticipado o puntual. Definido en franjas por fecha límite (cuanto más temprano, mayor el descuento). - Corrección monetaria (
correctionAmount) — actualización por índice (IPCA o IGP-M). El campo y su configuración ya existen, con valor por defecto sin corrección (none); la aplicación por índice queda reservada para una fase posterior y hoy no entra en el cálculo del monto actual.
Multa, intereses y descuento pueden desactivarse individualmente (disabled).
Configuración en tres niveles
La política de recargos puede definirse en tres lugares, del más general al más específico:
- Cuenta (
Organization) — el valor por defecto de la organización, aplicado a todo lo que no lo sobrescriba. - Regla de cobranza / campaña (
CollectionRule) — sobrepone el valor por defecto de la cuenta para los títulos de esa regla. - Cobro (
Charge) — sobrepone todo, para un título específico.
Precedencia: el más específico gana, con herencia campo a campo
El resolvedor parte de los valores legales por defecto del sistema y aplica las capas en orden (cuenta, luego regla, luego cobro). La capa más específica gana, pero el merge es campo a campo: un nivel puede definir solo la multa y heredar los intereses del nivel superior. Así, configurar un descuento en la regla no borra la multa heredada de la cuenta.
Por encima de todas las capas hay una excepción: cuando el título tiene un boleto registrado con recargos, ese boleto es la fuente de la verdad y el motor espeja los valores en vez de recalcularlos (ver Espejar el boleto).
Valores por defecto legales y avisos de tope
Cuando ninguna capa define un recargo, valen los valores legales por defecto del sistema:
| Recargo | Por defecto | Base |
|---|---|---|
| Multa | 2% (porcentaje sobre el original) | Tope del CDC para relación de consumo |
| Intereses de mora | 1% al mes (≈ 0,033% al día) | Práctica de mercado |
| Descuento | Desactivado | — |
| Corrección | Sin corrección (none) | — |
La configuración acepta valores por encima de esos umbrales, pero muestra avisos cuando superas los límites de referencia: una multa por encima del 2% señala que está sobre el tope del CDC para consumo (Código de Defensa del Consumidor, art. 52, §1º), e intereses por encima del 1% al mes señalan riesgo frente a la práctica usual y a la limitación legal de intereses (Ley 14.905/2024, que modificó el art. 406 del Código Civil). Los avisos no bloquean el registro: solo apuntan el riesgo jurídico para que decidas con conocimiento.
Cómo se calcula el monto actualizado
Sobre la base inmutable (originalAmount + dueDate), el motor deriva los recargos y llega al monto actual:
Monto Actual = Monto Original + Multa + Intereses + Corrección − Descuento
Reglas del cálculo:
- Días en mora se cuentan como días corridos entre el vencimiento y hoy, en la zona horaria de la organización. Un título al día tiene cero días en mora.
- Multa: aplicada una vez, a partir del primer día después del vencimiento (respetando una carencia opcional en días,
graceDays). El porcentaje incide sobre el monto original. - Intereses de mora: se acumulan por día desde el vencimiento (también con carencia opcional). Una tasa mensual se convierte a diaria dividiendo por 30, y el total es
tasa diaria × días cobrables × monto original. - Descuento: solo se aplica mientras el título aún no venció. Entre las franjas cuya fecha límite no pasó, gana la de plazo más cercano (el mejor descuento por anticipación).
- Redondeo: toda la matemática se hace en centavos enteros con redondeo half-up, para no acumular error de punto flotante. El monto actual nunca queda negativo.
- Tras un pago parcial: el saldo se convierte en un cobro hijo con nueva base inmutable (el propio saldo) y vencimiento en la fecha del pago. A partir de ahí los intereses de mora inciden sobre el saldo — no sobre el principal completo — y sin reaplicar los recargos ya incorporados en él. Consulta Pago y baja.
Cada cálculo guarda una memoria auditable: la fuente (calculado o espejado del boleto), los días en mora y la fórmula de cada componente (por ejemplo, "1%/mes × 12 día(s) sobre R$ 500,00"). Esto permite reconstruir y explicar exactamente cómo se formó el monto actual, tanto en el detalle del cobro como en el portal del deudor.
Espejar el boleto
Un boleto registrado en el banco (vía CNAB/CIP) ya lleva multa, intereses por día y descuento con sus fechas, y es el banco el que liquida el título con esos recargos. Cuando el cobro tiene un boleto registrado con recargos, el motor entra en modo espejo: en vez de recalcular, copia los valores del registro (encargoSource = 'boleto') para que la plataforma muestre exactamente lo que se cobrará en la compensación. En este modo, la política de recargos de la cuenta/regla/cobro no se aplica.
Recargos en la API
El recurso de cobros (/api/v1/charges) expone el desglose de los recargos: originalAmount, fineAmount, interestAmount, correctionAmount, discountAmount y currentAmount, además de daysOverdue. Tu integración puede mostrar o verificar la composición del monto adeudado sin reimplementar el cálculo. Consulta la referencia en /api/v1/charges.
:::tip Editar montos caso por caso Para un ajuste manual en un único título (reflejando una negociación hecha por fuera, por ejemplo), el formulario de edición del cobro permite cambiar intereses, multa y descuento directamente. Para una política que se repite, configura los recargos en la cuenta o en la regla. Y si quien impugna el monto es el deudor, el camino es registrar una disputa, no editar el título. :::