Encargos
Quando um título vence sem pagamento, o valor devido cresce por conta dos encargos: multa, juros de mora e, opcionalmente, correção monetária. No sentido inverso, o credor pode oferecer desconto por pontualidade ou antecipação. É esse conjunto que transforma o Valor Original no Valor Atual que o devedor vê nas mensagens da régua e no portal.
O motor de encargos foi desenhado para mexer com dinheiro cobrado do devedor sem margem para erro: o cálculo é idempotente (recalcular do zero nunca corrompe nem duplica valores), feito em centavos inteiros com arredondamento half-up, e sempre avaliado no fuso da organização.
Os quatro encargos
- Multa (
fineAmount) — penalidade pelo não pagamento no prazo. Incide uma única vez após o vencimento. Pode ser um percentual sobre o valor original (percent) ou um valor fixo (fixed). - Juros de mora (
interestAmount) — encargo pelo tempo de atraso. Acumula pró-rata die: cada dia vencido soma uma fração. Configurável ao mês (percent_month), ao dia (percent_day) ou como valor fixo por dia (fixed_day). - Desconto (
discountAmount) — abatimento concedido por pagamento antecipado ou pontual. Definido em faixas por data-limite (quanto mais cedo, maior o desconto). - Correção monetária (
correctionAmount) — atualização por índice (IPCA ou IGP-M). O campo e a configuração já existem, com padrão sem correção (none); a aplicação por índice fica reservada para uma fase seguinte e hoje não entra no cálculo do valor atual.
Multa, juros e desconto podem ser desativados individualmente (disabled).
Configuração em três níveis
A política de encargos pode ser definida em três lugares, do mais geral ao mais específico:
- Conta (
Organization) — o padrão da organização, aplicado a tudo que não sobrescreve. - Régua de cobrança / campanha (
CollectionRule) — sobrepõe o padrão da conta para os títulos daquela régua. - Cobrança (
Charge) — sobrepõe tudo, para um título específico.
Precedência: mais específico vence, com herança campo a campo
O resolvedor parte dos defaults legais do sistema e aplica as camadas em ordem (conta, depois régua, depois cobrança). A camada mais específica vence, mas o merge é campo a campo: um nível pode definir só a multa e herdar os juros do nível acima. Assim, configurar o desconto na régua não apaga a multa herdada da conta.
Acima de todas as camadas está uma exceção: quando o título tem um boleto registrado com encargos, esse boleto é a fonte da verdade e o motor espelha os valores em vez de recalcular (veja Espelhar boleto).
Defaults legais e avisos de teto
Quando nenhuma camada define um encargo, valem os defaults legais do sistema:
| Encargo | Padrão | Base |
|---|---|---|
| Multa | 2% (percentual sobre o original) | Teto do CDC para relação de consumo |
| Juros de mora | 1% ao mês (≈ 0,033% ao dia) | Prática de mercado |
| Desconto | Desativado | — |
| Correção | Sem correção (none) | — |
A configuração aceita valores acima desses patamares, mas exibe avisos quando você ultrapassa os limites de referência: multa acima de 2% sinaliza que está acima do teto do CDC para consumo (Código de Defesa do Consumidor, art. 52, §1º), e juros acima de 1% ao mês sinalizam risco em relação à prática usual e à limitação legal de juros (Lei 14.905/2024, que alterou o art. 406 do Código Civil). Os avisos não travam o cadastro: apenas apontam o risco jurídico para você decidir com consciência.
Como o valor atualizado é calculado
Sobre a base imutável (originalAmount + dueDate), o motor deriva os encargos e chega ao valor atual:
Valor Atual = Valor Original + Multa + Juros + Correção − Desconto
Regras do cálculo:
- Dias em atraso são contados em dias corridos entre o vencimento e a data de hoje, no fuso da organização. Título em dia tem zero dia de atraso.
- Multa: aplicada uma vez, a partir do primeiro dia após o vencimento (respeitando uma carência opcional em dias,
graceDays). Percentual incide sobre o valor original. - Juros de mora: acumulam por dia a partir do vencimento (também com carência opcional). Uma taxa mensal é convertida para diária dividindo por 30, e o total é
taxa diária × dias cobráveis × valor original. - Desconto: só se aplica enquanto o título ainda não venceu. Entre as faixas cuja data-limite ainda não passou, vale a de prazo mais próximo (melhor desconto por antecipação).
- Arredondamento: toda a matemática é feita em centavos inteiros, com arredondamento half-up, para não acumular erro de ponto flutuante. O valor atual nunca fica negativo.
- Após um pagamento parcial: o saldo vira uma cobrança-filha com nova base imutável (o próprio saldo) e vencimento na data do pagamento. A partir daí os juros de mora incidem sobre o saldo — não sobre o principal cheio — e sem reaplicar os encargos já embutidos nele. Veja Pagamento e baixa.
Cada cálculo guarda uma memória auditável: a fonte (calculado ou espelhado do boleto), os dias em atraso e a fórmula de cada componente (por exemplo, "1%/mês × 12 dia(s) sobre R$ 500,00"). Isso permite reconstruir e explicar exatamente como o valor atual foi formado, tanto no detalhe da cobrança quanto no portal do devedor.
Espelhar boleto
Um boleto registrado no banco (via CNAB/CIP) já carrega multa, juros por dia e desconto com suas datas, e é o banco que liquida o título com esses encargos. Quando a cobrança tem um boleto registrado com encargos, o motor entra em modo espelho: em vez de recalcular, ele copia os valores do registro (encargoSource = 'boleto') para que a plataforma mostre exatamente o que será cobrado na compensação. Nesse modo, a política de encargos da conta/régua/cobrança não é aplicada.
Encargos na API
O recurso de cobranças (/api/v1/charges) expõe o detalhamento dos encargos: originalAmount, fineAmount, interestAmount, correctionAmount, discountAmount e currentAmount, além de daysOverdue. Assim, sua integração pode exibir ou conferir a composição do valor devido sem reimplementar o cálculo. Veja a referência em /api/v1/charges.
:::tip Editar valores pontualmente Para um ajuste manual em um único título (refletindo uma negociação feita por fora, por exemplo), o formulário de edição da cobrança permite alterar juros, multa e desconto diretamente. Para uma política que se repete, configure os encargos na conta ou na régua. E se quem contesta o valor é o devedor, o caminho é registrar uma disputa, não editar o título. :::