> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kiraa.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Cobrança

> Módulo de recebíveis: carteiras, contratos, parcelas, pagamentos integrados (PIX/Boleto/Link), acordos com assinatura digital e insights de recuperação

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:

<CardGroup cols={2}>
  <Card title="Insights" icon="chart-line" href="/cobranca#insights">
    Painel da operadora: recuperação, aging, funil, performance
  </Card>

  <Card title="Carteiras" icon="wallet" href="/cobranca#carteiras">
    Configura juros, multa, modo nativo/espelho e integrações por carteira
  </Card>

  <Card title="Contratos" icon="file-pen" href="/cobranca#contratos-e-parcelas">
    Drill-down de contratos e parcelas com saldo atualizado on-read
  </Card>

  <Card title="Acordos" icon="signature" href="/cobranca#acordos">
    Renegociação com simulador, aceite OTP ou ClickSign
  </Card>

  <Card title="Pagamentos" icon="dollar-sign" href="/cobranca#pagamentos">
    PIX, Boleto e Link de pagamento via gateway integrado
  </Card>
</CardGroup>

***

## 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.

<Info>
  A entidade central do CRM continua sendo o [Cliente](/clients). O módulo Cobrança **se conecta** ao cliente existente — não substitui.
</Info>

***

## 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.

<CardGroup cols={2}>
  <Card title="Modo Nativo" icon="calculator">
    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.
  </Card>

  <Card title="Modo Espelho" icon="rotate">
    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.
  </Card>
</CardGroup>

<Warning>
  **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.
</Warning>

***

## 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)                                                                   |

<Warning>
  **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.
</Warning>

### 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
```

<Info>
  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.
</Info>

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

<CardGroup cols={2}>
  <Card title="Lista" icon="list">
    Tabela com filtros por status, método, carteira e busca por cliente
  </Card>

  <Card title="Kanban" icon="layout-kanban">
    Colunas por status — útil pra ver quantas cobranças estão "Aguardando pagamento" agora
  </Card>
</CardGroup>

### 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**:

<Steps>
  <Step title="Escolha o cliente e a parcela">
    Busca por nome/CPF; lista as parcelas em aberto do cliente.
  </Step>

  <Step title="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**.
  </Step>

  <Step title="Confirme valor e validade">
    Valor vem do saldo do dia. Validade tem default por carteira (configurável).
  </Step>

  <Step title="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.
  </Step>
</Steps>

<Tip>
  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.
</Tip>

### Confirmação automática

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

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

<Warning>
  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.
</Warning>

***

## 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

<Steps>
  <Step title="Selecione contrato e parcelas">
    Marque as parcelas que entram no acordo. As demais ficam intactas.
  </Step>

  <Step title="Defina termos">
    Desconto total (% ou valor), número de parcelas do acordo, intervalo entre parcelas, primeira data de vencimento.
  </Step>

  <Step title="Escolha o método de aceite">
    Veja a próxima seção — a sugestão default vem do **threshold da carteira**.
  </Step>

  <Step title="Envie pra assinatura">
    Sistema envia link de assinatura por WhatsApp/e-mail. Devedor abre, autentica pelo método escolhido, assina.
  </Step>

  <Step title="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
  </Step>
</Steps>

### 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**.

<Info>
  **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.
</Info>

### 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

<CardGroup cols={2}>
  <Card title="Recuperação por carteira" icon="percent">
    % do valor recuperado por carteira no período
  </Card>

  <Card title="Aging" icon="hourglass">
    Buckets de parcelas em aberto: 0-30, 31-60, 61-90, 91-180, 180+
  </Card>

  <Card title="Funil de contato" icon="filter">
    Contatados → Falaram → Prometeram → Cumpriram → Quitaram
  </Card>

  <Card title="Performance por agente" icon="user">
    Acordos fechados e valor recuperado por agente (humano e IA)
  </Card>

  <Card title="Pagamentos por método" icon="dollar-sign">
    Distribuição entre PIX, Boleto, Link, Cartão
  </Card>

  <Card title="Acordos por status" icon="chart-pie">
    Pending / Ativo / Quitado / Quebrado
  </Card>
</CardGroup>

### 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
```

<Warning>
  **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.
</Warning>

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](/automations#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](/agents) 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](/templates-whatsapp):

### 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](/automations) → 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

<CardGroup cols={2}>
  <Card title="Régua de cobrança" icon="route" href="/automations#régua-de-cobrança">
    Workflow de cadência por cobrança — gera PIX, escala canal, encerra sozinho
  </Card>

  <Card title="Templates WhatsApp" icon="message" href="/templates-whatsapp">
    Templates com variáveis de cobrança (`{{link_pagamento}}` etc.)
  </Card>

  <Card title="Agentes IA" icon="robot" href="/agents">
    Tools de cobrança — emitir link, simular acordo, firmar acordo durante a ligação
  </Card>

  <Card title="Plugins" icon="plug" href="/plugins">
    Conecte Asaas, Mercado Pago, ClickSign, ERP customizado
  </Card>
</CardGroup>