Cobrança - Kiraa

O módulo Cobrança é onde a Kiraa gerencia a dívida — desde o momento em que a operadora sobe uma carteira de crédito até o instante em que o pagamento cai na conta. Ele complementa a parte de IA que conversa com o devedor: agora a plataforma sabe quanto ele deve, de qual contrato, qual parcela, com saldo atualizado, e fecha acordo com assinatura digital sem sair do produto. Acesse em Cobrança no menu lateral. As cinco páginas do módulo são:

Insights

Painel da operadora: recuperação, aging, funil, performance

Carteiras

Configura juros, multa, modo nativo/espelho e integrações por carteira

Contratos

Drill-down de contratos e parcelas com saldo atualizado on-read

Acordos

Renegociação com simulador, aceite OTP ou ClickSign

Pagamentos

PIX, Boleto e Link de pagamento via gateway integrado

Como o dado se organiza

+--------------+
|  CARTEIRA    |  ← entidade nova: define juros, multa, modo
+------+-------+    nativo/espelho, integração ERP/gateway
       |
       v
+--------------+
|  CONTRATO    |  ← cliente pode ter N contratos na mesma carteira
+------+-------+
       |
       v
+--------------+
|  PARCELA     |  ← o "recebível atômico"
+------+-------+    saldo calculado on-read
       |
       v
+--------------+
|  PAGAMENTO   |  ← ledger append-only (estorno = nova linha negativa)
+--------------+

Por que essa hierarquia importa:

Um devedor pode ter vários contratos na mesma carteira — não precisa concatenar string como antigamente.
O acordo cobre parcelas específicas — dá pra renegociar só as duas parcelas atrasadas, mantendo as futuras intactas.
O pagamento parcial aparece como linha no histórico do contrato; o saldo do dia seguinte já reflete.
O ledger é append-only: estornos viram uma linha nova com valor negativo apontando pra original. Auditoria sempre reconstrói a verdade histórica.

A entidade central do CRM continua sendo o Cliente. O módulo Cobrança se conecta ao cliente existente — não substitui.

Modo nativo vs. modo espelho

Toda carteira é configurada num dos dois modos. A escolha é imutável após a primeira parcela ser criada — mudar exige um endpoint dedicado de transição.

Modo Nativo

A Kiraa é o sistema-mestre. Calcula juros, multa, correção e saldo do dia por conta própria.Quando usar: operadora começando do zero, sem ERP de cobrança, ou que prefere centralizar tudo aqui.

Modo Espelho

A Kiraa sincroniza com o ERP do cliente (Nowlex, Asaas, HTTP customizado). O saldo vem de fora; a Kiraa espelha.Quando usar: operadora que já tem ERP de cobrança e quer continuar usando, mas precisa da camada de IA + Portal do Devedor por cima.

Mode é imutável após primeira parcela. O banco rejeita o UPDATE por trigger. Defina certo na criação — corrigir depois exige procedimento de transição com snapshot + reconciliação.

Carteiras

A página Cobrança → Carteiras lista todas as carteiras da operadora em cards, com filtros por modo, tipo de juros e nome do credor.

Criar uma carteira

Clique em Nova carteira. O formulário pede:

Campo	O que é
Nome	Identificador interno (ex: `BCSUL Crédito Pessoal 2026`)
Credor	Nome e CNPJ do credor original (CNPJ é obrigatório quando a carteira é de instituição financeira)
Instituição financeira?	Toggle que destrava regras especiais (juros compostos, regime de Súmula 30 STJ)
Modo	Nativo ou Espelho
Tipo de juros	Simples / Composto / Nenhum
Taxa de juros mensal	Até 2% ao mês (limite CDC)
Multa por atraso	Até 2% (CDC art. 52 §1º)
Índice de correção	Nenhum / IGP-M / IPCA / INPC
Carência (dias)	Dias sem juros após o vencimento
Integração ERP	(Modo espelho) Qual integração sincroniza os saldos
Gateway de pagamento	Qual integração emite PIX/Boleto
Provedor de assinatura	ClickSign / DocuSign (para acordos)

Travas legais aplicadas no banco: juros > 2% a.m. falha no INSERT. Para instituição financeira, juros remuneratórios e correção monetária são mutuamente exclusivos (Súmula 30 STJ). A UI mostra erro amigável antes, o banco recusa por garantia.

Sincronizar (modo espelho)

Na lista, carteiras em modo espelho mostram um botão Sincronizar agora. Ele dispara a integração ERP configurada e retorna created/updated/skipped. Há também sync periódico automático rodando a cada 30 minutos para todas as carteiras em modo espelho.

Detalhe da carteira

Clicar numa carteira abre /cobranca/carteiras/[id] com três abas:

Contratos — lista de contratos daquela carteira
Acordos — acordos abertos vinculados a contratos dessa carteira
Pagamentos — payment intents emitidos a partir dessa carteira

E cards de estatísticas: total de contratos, valor em aberto, parcelas vencidas, taxa de recuperação.

Contratos e parcelas

A página Cobrança → Contratos lista contratos de todas as carteiras com filtros por carteira, status e busca por número/cliente. Status do contrato:

Status	Significado
Em dia (`ativo`)	Todas as parcelas em dia
Atrasado (`atrasado`)	Pelo menos uma parcela venceu
Inadimplente (`inadimplente`)	Atraso prolongado (regra por carteira)
Em acordo (`em_acordo`)	Existe acordo ativo cobrindo as parcelas
Quitado (`quitado`)	Todas as parcelas pagas
Prescrito (`prescrito`)	Passou da `data_prescricao`
Judicial (`judicial`)	Foi pra esteira jurídica
Baixado (`baixado`)	Soft-delete (não aparece na operação)

Saldo do dia (a fonte oficial)

Clicar num contrato abre o detalhe com a lista de parcelas. Cada parcela tem o botão Saldo atualizado que retorna:

Principal:              R$ 1.000,00
+ Juros (36 dias):      R$    12,00
+ Multa (2%):           R$    20,00
+ Correção monetária:   R$     0,00
- Pagamentos:           R$     0,00
= Saldo de hoje:        R$ 1.032,00

O saldo não fica persistido em coluna. Cada chamada recalcula a partir do original_amount + payments + parâmetros da carteira. Isso evita o clássico bug de auditoria: coluna current_amount desatualizada por bug de migration. A função de cálculo é versionada (compute_current_amount_v1) — qualquer mudança de interpretação legal vira _v2, sem reescrever histórico.

No modo espelho, o saldo vem do payload do ERP (external_payload->>'valor_atualizado') — a Kiraa não recalcula, só espelha.

Pagamentos

A página Cobrança → Pagamentos lista todos os payment intents emitidos pela organização. Cada intent é uma cobrança específica (PIX, Boleto, Cartão ou Link) atrelada a uma parcela ou a um contrato.

Visualizações

Lista

Tabela com filtros por status, método, carteira e busca por cliente

Kanban

Colunas por status — útil pra ver quantas cobranças estão “Aguardando pagamento” agora

Status

Status	Significado
Aguardando geração (`pending_generation`)	Intent criado mas ainda não materializado no gateway
Aguardando pagamento (`pending`)	PIX/Boleto/Link emitido, esperando devedor pagar
Atrasado (virtual: `pending` + `due_date < hoje`)	Mesmo status que o board mostra, calculado on-read
Pago (`paid`)	Confirmação do gateway processada
Expirado (`expired`)	Passou da validade sem pagamento
Cancelado (`cancelled`)	Cancelado manualmente ou por acordo
Falhou (`failed`)	Erro de geração/processamento
Substituído (`superseded`)	Foi superado por um acordo

Emitir uma nova cobrança

Em Pagamentos → Nova cobrança:

Escolha o cliente e a parcela

Busca por nome/CPF; lista as parcelas em aberto do cliente.

Escolha o método

PIX (QR + Copia-e-cola), Boleto (linha digitável), Link (página do gateway com múltiplos métodos) ou Cartão.

Confirme valor e validade

Valor vem do saldo do dia. Validade tem default por carteira (configurável).

Gere e envie

O gateway materializa, o intent vira pending. O botão Enviar abre um diálogo pra mandar o link/QR por WhatsApp, SMS ou e-mail.

Quando uma cobrança PIX existe e está pending, gerar nova cobrança reusa o mesmo link (reuse_active=true por padrão). Isso evita duplicar QRs vivos no celular do devedor.

Confirmação automática

Quando o devedor paga, o gateway envia webhook → a Kiraa:

Marca o intent como paid, adiciona linha no ledger de payments
Atualiza saldo da parcela
Cancela runs de automação ativas naquela cobrança (régua para de tocar)
Dispara automações que escutam payment.confirmed (ex: mandar agradecimento)

Webhooks são validados por HMAC (Asaas) ou assinatura específica do provedor (Mercado Pago). Não aceitamos payment.confirmed de origem não-verificada.

Acordos

A página Cobrança → Acordos é o coração da renegociação. Um acordo cobre parcelas específicas de um contrato e gera novas parcelas com desconto, prazo e método de pagamento configuráveis.

Status do acordo

Status	Significado
Aguardando aceite (`pending_signature`)	Acordo criado, aguardando devedor assinar
Ativo (`active`)	Assinado, parcelas em andamento
Quitado (`completed`)	Todas as parcelas do acordo foram pagas
Quebrado (`broken`)	Devedor não pagou — passou do threshold de dias (configurável por carteira, default 7)
Cancelado (`cancelled`)	Cancelado manualmente
Expirado (`expired`)	Não foi assinado dentro do prazo

Criar um acordo

Selecione contrato e parcelas

Marque as parcelas que entram no acordo. As demais ficam intactas.

Defina termos

Desconto total (% ou valor), número de parcelas do acordo, intervalo entre parcelas, primeira data de vencimento.

Escolha o método de aceite

Veja a próxima seção — a sugestão default vem do threshold da carteira.

Envie pra assinatura

Sistema envia link de assinatura por WhatsApp/e-mail. Devedor abre, autentica pelo método escolhido, assina.

Após o aceite

Parcelas originais marcadas como em_acordo
Payment intents pendentes daquelas parcelas viram superseded
Novas parcelas do acordo criadas com vencimentos calculados
Régua de cobrança cancela runs antigas e (opcionalmente) inicia régua nova focada no acordo

Threshold por carteira e método de aceite

Cada carteira define três faixas de valor com auth methods sugeridos:

Faixa	Default sugerido	Justificativa
Simples (até R$ X)	OTP por SMS	Compromisso baixo, peso probatório suficiente
Médio (X até Y)	ClickSign — email + SMS	Acordo formal, pacote auditável
Avançado (acima de Y)	ClickSign — biometria facial / SERPRO+CPF	Renúncia de direito, exige peso jurídico máximo

Os thresholds e os métodos são configuráveis em Carteiras → Editar → Acordos.

Plataforma suporta ambos OTP cru e ClickSign. OTP é suficiente pra acordos simples; ClickSign produz pacote com peso jurídico forte (auditoria completa, certificado ICP-Brasil para faixas avançadas). A escolha do mecanismo por valor fica configurável por carteira.

Templates de PDF customizados

Você pode subir um template de PDF do acordo por carteira (agreement_template_id). Variáveis tipo {{cliente_nome}}, {{contrato_numero}}, {{acordo_valor_total}} são preenchidas no momento da geração. Sem template, o sistema usa o layout padrão da Kiraa.

Quebra automática

Se uma parcela do acordo passa N dias sem pagamento (configurável por carteira, default 7), o acordo vira broken automaticamente. As parcelas originais voltam pra atrasado — sem o desconto. O sistema dispara agreement.broken que pode iniciar régua mais agressiva.

Insights

A página Cobrança → Insights é um dashboard de widgets customizáveis com filtros por carteira e período.

Widgets disponíveis

Recuperação por carteira

% do valor recuperado por carteira no período

Aging

Buckets de parcelas em aberto: 0-30, 31-60, 61-90, 91-180, 180+

Funil de contato

Contatados → Falaram → Prometeram → Cumpriram → Quitaram

Performance por agente

Acordos fechados e valor recuperado por agente (humano e IA)

Pagamentos por método

Distribuição entre PIX, Boleto, Link, Cartão

Acordos por status

Pending / Ativo / Quitado / Quebrado

Export

Botão Exportar disponibiliza o dashboard em Excel (linhas brutas) ou PDF (snapshot visual). Útil pra reuniões com credor.

Compliance: o gate de contato

Toda comunicação que o módulo gera (mensagem de cobrança, ligação, envio de PIX por Zap) passa pelo gate can_contact antes de sair:

+----------------------------------+
|  Disparo (régua, agente, manual) |
+----------------+-----------------+
                 |
                 v
+----------------------------------+
|  GATE can_contact(client, channel)
|                                   |
|  • Faixa CDC?                     |
|    seg-sex 8h-20h, sáb 8h-14h    |
|    dom/feriado: bloqueia          |
|                                   |
|  • DNI (Do Not Call)?             |
|    Hash CPF + telefone E.164      |
|                                   |
|  • LGPD: marketing pede consent   |
|    Cobrança não pede (legítimo    |
|    interesse), mas registra       |
+----------------+------------------+
                 |
       +---------+---------+
       |                   |
       v                   v
   permitido            bloqueado
       |                   |
       v                   v
   envio segue       audit em
                    compliance_blocks

Fail-closed: se o gate der erro (banco fora, etc.), o sistema bloqueia o envio em vez de soltar. Postura segura — melhor não mandar do que mandar fora do horário CDC por bug.

Configure a DNI da operadora em Configurações → Compliance → Lista de não-perturbe (em construção). Por enquanto, gerencie via API ou suporte.

Como o módulo conecta com o resto da plataforma

+--------------------+
|   COBRANÇA         |
|   (carteira →      |
|    contrato →      |
|    parcela)        |
+----+-----------+---+
     |           |
     v           v
+----------+  +-----------------+
| RÉGUA    |  | AGENTE IA       |
| de       |  | (voz / WhatsApp)|
| cobrança |  |                 |
| (auto-   |  | tools:          |
|  mação   |  | • emitir_pix    |
|  com     |  | • simular_acordo|
|  cadence_|  | • firmar_acordo |
|  check)  |  | • consultar_    |
|          |  |   saldo         |
+----+-----+  +--------+--------+
     |                 |
     +--------+--------+
              |
              v
       +-------------+
       | COMPLIANCE  |
       | can_contact |
       +------+------+
              |
              v
        WhatsApp / SMS / Email / Voz
              |
              v
          DEVEDOR
              |
       +------+------+
       |             |
       v             v
   paga via      assina acordo
   PIX QR        (OTP / ClickSign)
       |             |
       v             v
   webhook        webhook
   gateway        provedor
       |             |
       v             v
   ledger        novas parcelas
   append-only   do acordo

A Régua de cobrança é um workflow especial que roda 1 run por cobrança, todo dia, decidindo o que fazer hoje (mandar Zap, ligar, gerar PIX, encerrar).
O Agente IA ganha tools de cobrança quando associado a uma carteira: consulta saldo, simula acordo, emite link de pagamento, registra promessa.
O Portal do Devedor (em construção) será um subdomínio whitelabel onde o devedor entra com CPF + OTP e resolve sozinho — simulador, aceite digital e PIX QR.

Variáveis disponíveis em templates

Quando uma mensagem é disparada no contexto de uma cobrança (régua, agente, manual em /pagamentos), estas variáveis ficam disponíveis nos templates:

Da cobrança

{{pagamento_status}} — status display (inclui virtual overdue)
{{pagamento_metodo}} — pix / boleto / card / payment_link
{{pagamento_valor}} — valor da cobrança
{{link_pagamento}} — boleto_url ou qr_code_text (atalho)
{{qr_code_pix}} / {{boleto_url}}
{{valor_atualizado}} — saldo do dia (recalculado on-read)
{{pagamento_dias_atraso}} — derivado de due_date
{{pagamento_expira_em}} — ISO timestamp

Da parcela / contrato

{{parcela_numero}} / {{parcela_vencimento}} / {{parcela_valor_original}}
{{contrato_numero}} / {{contrato_id}}

Contadores globais (sobrevivem entre runs)

{{pagamento_lembretes_enviados}} — total já enviado pra essa cobrança
{{pagamento_lembretes_whatsapp}} / {{pagamento_lembretes_email}} / {{pagamento_lembretes_sms}} / {{pagamento_lembretes_call}}
{{pagamento_ultimo_envio}} — timestamp ISO

Do cliente (igual aos outros workflows)

{{cliente_nome}}, {{cliente_telefone}}, {{cliente_email}}
Custom fields: {{cpf}}, {{custom.cpf}}

Limitações conhecidas

Importação CSV de carteiras inteiras ainda não está self-service via UI — hoje é por sync ERP (modo espelho) ou suporte. Importação self-service é da próxima sprint.
Editor visual da régua já está em produção (ver Automações → tipo “Cobrança”); templates pré-prontos por janela ainda vão chegar.
Portal do Devedor (subdomínio whitelabel) está em construção.
Score IA de propensão a pagar está no roadmap, ainda não disponível.
Migração de modo nativo → espelho (ou vice-versa) depois da primeira parcela exige procedimento manual — endpoint POST /portfolios/{id}/migrate-mode retorna 501 hoje.

Próximos passos

Régua de cobrança

Workflow de cadência por cobrança — gera PIX, escala canal, encerra sozinho

Templates WhatsApp

Templates com variáveis de cobrança ({{link_pagamento}} etc.)

Agentes IA

Tools de cobrança — emitir link, simular acordo, firmar acordo durante a ligação

Plugins

Conecte Asaas, Mercado Pago, ClickSign, ERP customizado

Insights

Carteiras

Contratos

Acordos

Pagamentos

​Como o dado se organiza

​Modo nativo vs. modo espelho

Modo Nativo

Modo Espelho

​Carteiras

​Criar uma carteira

​Sincronizar (modo espelho)

​Detalhe da carteira

​Contratos e parcelas

​Saldo do dia (a fonte oficial)

​Pagamentos

​Visualizações

Lista

Kanban

​Status

​Emitir uma nova cobrança

​Confirmação automática

​Acordos

​Status do acordo

​Criar um acordo

​Threshold por carteira e método de aceite

​Templates de PDF customizados

​Quebra automática

​Insights

​Widgets disponíveis

Recuperação por carteira

Aging

Funil de contato

Performance por agente

Pagamentos por método

Acordos por status

​Export

​Compliance: o gate de contato

​Como o módulo conecta com o resto da plataforma

​Variáveis disponíveis em templates

​Da cobrança

​Da parcela / contrato

​Contadores globais (sobrevivem entre runs)

​Do cliente (igual aos outros workflows)

​Limitações conhecidas

​Próximos passos

Régua de cobrança

Templates WhatsApp

Agentes IA

Plugins

Como o dado se organiza

Modo nativo vs. modo espelho

Carteiras

Criar uma carteira

Sincronizar (modo espelho)

Detalhe da carteira

Contratos e parcelas

Saldo do dia (a fonte oficial)

Pagamentos

Visualizações

Status

Emitir uma nova cobrança

Confirmação automática

Acordos

Status do acordo

Criar um acordo

Threshold por carteira e método de aceite

Templates de PDF customizados

Quebra automática

Insights

Widgets disponíveis

Export

Compliance: o gate de contato

Como o módulo conecta com o resto da plataforma

Variáveis disponíveis em templates

Da cobrança

Da parcela / contrato

Contadores globais (sobrevivem entre runs)

Do cliente (igual aos outros workflows)

Limitações conhecidas

Próximos passos