Recuperação

As métricas de recuperação respondem à pergunta que justifica o produto: o que a régua fez por você? A resposta é construída com atribuição honesta — o sistema só chama de "recuperado" o que estava de fato em recuperação, e diz qual etapa e canal tocaram o devedor por último antes do dinheiro entrar.

O que conta como recuperação

Um registro de recuperação é criado no momento em que um pagamento é confirmado, se a cobrança estava em uma destas situações:

• Em régua (rule) — havia uma régua ativa ou pausada trabalhando a cobrança.
• Negociada (agreement) — a cobrança estava em acordo.
• Vencida sem régua (overdue_no_rule) — estava em atraso, ainda que fora de régua.

Pagamento em dia, sem régua, não conta. Esse dinheiro entraria de qualquer forma; somá-lo inflaria o número. É essa separação por método (rule / agreement / overdue_no_rule) que deixa claro quanto veio do trabalho da régua e quanto veio de acordo ou de atraso resolvido por outros meios.

Um pagamento parcial também gera recuperação, atribuída ao valor efetivamente pago na baixa parcial do título original (o saldo segue como uma cobrança-filha e, se recuperado depois, gera seu próprio registro).

Como funciona a atribuição

Cada registro de recuperação guarda a telemetria da régua até o pagamento:

• Última etapa e canal — a atribuição vai para a última etapa efetivamente enviada (enviada, entregue, respondida ou convertida) antes do pagamento, com o canal usado. É um modelo last-touch deliberadamente simples e verificável: nada de dividir o crédito entre toques por heurística.
• Etapas executadas — quantos passos a régua rodou até converter (mede o esforço por recuperação).
• Dias de atraso no pagamento — calculados direto das datas (pagamento − vencimento), sem depender de contadores atualizados uma vez por dia.
• Valor recuperado — o valor pago (ou o valor atual da cobrança no momento da baixa).
• Origem do pagamento — kobana, PSP, CNAB ou manual.

Cada pagamento gera no máximo um registro por cobrança (idempotente): reentregas de webhook não dobram o número.

As métricas disponíveis

A partir desses registros, o sistema calcula para o período (por padrão, os últimos 6 meses; configurável de 1 a 24):

• Total recuperado — valor e quantidade de cobranças.
• Taxa de recuperação — recuperado ÷ (recuperado + carteira em atraso hoje). Uma leitura conservadora: o denominador inclui tudo o que ainda está vencido agora.
• Atraso médio na recuperação — quantos dias de atraso, em média, as cobranças tinham ao serem pagas.
• Etapas médias até recuperar — o esforço médio da régua por conversão.
• Série mensal — valor e quantidade recuperados mês a mês.
• Por método — quanto veio de régua, de acordo e de vencidas sem régua.
• Por canal — quanto cada canal (e-mail, SMS, WhatsApp) converteu como último toque.

Essas métricas estão disponíveis pela API (GET /api/v1/metrics/recovery) para alimentar seus próprios relatórios.

O card no dashboard

No dashboard, o card Recuperado pela régua mostra o valor recuperado no mês corrente e a contagem de cobranças vencidas pagas no mês. Ele fica ao lado do Recebido no mês de propósito: o primeiro é o resultado do trabalho de cobrança; o segundo é todo o caixa que entrou. A diferença entre os dois é o que teria entrado sozinho.

A série mensal e a taxa de recuperação também aparecem como um gráfico de tendência no dashboard (valor recuperado por mês), alimentado por GET /api/v1/metrics/recovery — útil para enxergar a evolução da recuperação ao longo do tempo, não só o mês corrente.