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

# Métricas de recuperação de receita

> Quanto falhou, quanto voltou, por qual caminho e por qual motivo.

Recuperação sem medição é palpite. O painel de recuperação — em **Assinaturas →
Recuperação** no painel da sua organização — responde, em reais, às quatro
perguntas que importam: quanto falhou, quanto disso voltou, por qual caminho
voltou e por que falhou. É com esses números que você calibra a
[política de retentativas](/payments/smart-retries) com dado
em vez de intuição.

<Info>
  **Cada fatura conta uma vez, ancorada na primeira falha.**

  Uma fatura que falhou três vezes e foi paga na quarta é **um** pagamento com
  falha, **um** motivo de recusa (o da primeira falha) e **uma** recuperação — no
  mês em que a primeira falha aconteceu. Nenhum número do painel conta a mesma
  fatura duas vezes, e todos usam o mesmo recorte, então as proporções sempre
  fecham.
</Info>

## Os quatro indicadores

| Indicador                  | Definição exata                                                                                            |
| -------------------------- | ---------------------------------------------------------------------------------------------------------- |
| **Pagamentos com falha**   | Volume (R\$) das faturas de renovação cuja cobrança automática falhou ao menos uma vez no período.         |
| **Taxa de falha**          | Pagamentos com falha ÷ volume de renovações cobradas no período.                                           |
| **Pagamentos recuperados** | Volume (R\$) das faturas com falha que acabaram pagas — por retentativa, e-mail ou qualquer outro caminho. |
| **Taxa de recuperação**    | Pagamentos recuperados ÷ pagamentos com falha.                                                             |

## Os três estados de uma falha

Toda fatura que falhou está, a qualquer momento, em um de três estados:

| Estado             | Significado                                                                                        |
| ------------------ | -------------------------------------------------------------------------------------------------- |
| **Em recuperação** | A fatura segue aberta e existe uma próxima tentativa agendada (`next_payment_attempt` preenchido). |
| **Recuperado**     | A fatura foi paga depois de ter falhado.                                                           |
| **Não recuperado** | A janela terminou (ou a fatura foi baixada) sem pagamento.                                         |

O gráfico principal empilha os três ao longo do tempo — a régua funcionando
aparece como a faixa "recuperado" crescendo às custas das outras duas.

## Origem da recuperação

Cada fatura recuperada é atribuída ao caminho que trouxe o pagamento, em R\$ e
em quantidade:

| Origem          | Como é atribuída                                                                                                                |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| **Retentativa** | A cobrança que aprovou foi um passo automático da agenda.                                                                       |
| **E-mail**      | O pagamento veio de um link enviado num e-mail de recuperação — pela página da fatura ou pela troca de cartão no portal.        |
| **Outros**      | Qualquer outro caminho: cobrança manual pelo painel ou API, link enviado pelo seu time, ação do próprio cliente fora do e-mail. |

É a leitura mais direta do valor da automação: quanto a régua devolve sozinha,
quanto o e-mail resolve e quanto ainda depende de gente.

## Motivos de recusa

Os cinco maiores motivos de falha por volume, no mesmo recorte dos
indicadores: **uma fatura, um motivo** — o da primeira falha automática. Os
códigos são os do
[catálogo de motivos de recusa](/api-reference/charges/failure-codes), então o
que você vê no painel é o mesmo `failure_code` que a sua integração recebe em
`charge.failed`.

Use esta quebra para decidir onde agir: um topo dominado por saldo insuficiente
pede janela mais longa; cartões vencidos pedem o aviso de expiração ligado;
recusas definitivas em volume pedem atenção ao fluxo de troca de cartão.

## Principais clientes em recuperação

A lista operacional de "dinheiro em risco agora": os clientes com faturas em
recuperação neste momento, ordenados pelo valor em aberto, com o tempo de casa
de cada um. É o ponto de partida para uma ação humana dirigida — um contato
direto com os maiores valores costuma valer mais que qualquer ajuste de
política.

## O recorte, com precisão

Para que os números signifiquem sempre a mesma coisa, o painel aplica um
recorte fixo:

* **Só renovações com cobrança automática.** Faturas avulsas e assinaturas
  cobradas por fatura manual ficam de fora — pertencem a outra régua.
* **A primeira fatura após um trial não entra.** A falha dela mede a conversão
  do trial, não a recuperação de um assinante estabelecido.
* **O período é o da primeira falha.** Uma fatura que falhou em março e foi
  paga em abril conta em março, como recuperada — o painel responde "das
  falhas de março, quanto voltou?", não "o que aconteceu em abril?".
* **Ambientes separados.** Os modos de teste e produção têm séries
  independentes, como em todo o painel.

<Info>
  Números de períodos passados podem ser recalculados quando a definição de um
  indicador é refinada — os dados de origem nunca mudam, a lente sim. A
  definição vigente é sempre a desta página.
</Info>