## Visão geral

A **Recuperação de vendas** é a camada que garante que um evento de comércio **sempre vire uma ação
visível**. Antes, o card de recuperação podia morrer em silêncio: se o cliente não tinha conversa
aberta, ou se a mensagem caía fora da janela do WhatsApp, nada acontecia e ninguém ficava sabendo.

Agora, todo evento de ciclo de vida — vindo de Kiwify, Hotmart, Nuvemshop ou do gateway nativo
(Asaas / Mercado Pago) — passa por três garantias:

1. Um **resolvedor de conversa** decide para onde o card vai, com uma **política** que você escolhe.
2. Uma **guarda de janela de envio** verifica se o canal aceita a mensagem naquele momento.
3. Um **resultado de entrega** é registrado em **todos** os caminhos de saída: `enviado`, `ignorado`
   ou `falhou`, sempre com um **motivo** legível.

O resultado prático: você abre a página **Recuperação de vendas** e vê quantas oportunidades foram
alcançadas, quantas não foram e **exatamente por quê** — em vez de descobrir semanas depois que uma
cadência inteira nunca saiu.

### Quando cada estágio dispara

| Estágio | Dispara quando | Acionável? |
|---|---|---|
| **Carrinho abandonado** | o cliente montou o carrinho/checkout e não concluiu | Sim |
| **Pagamento pendente** | PIX ou boleto foi gerado e ainda não foi pago | Sim |
| **Pagamento recusado** | o cartão foi negado pelo emissor ou pelo antifraude | Sim |
| **Vencido** | a data de vencimento passou sem pagamento | Sim |
| **Pedido criado** | o pedido foi registrado na plataforma, ainda pendente | Não (não liquida) |
| **Pagamento confirmado** | o pagamento foi aprovado | Não (liquidação) |
| **Reembolsado** | o valor foi devolvido ao cliente | Não |
| **Chargeback** | o cliente contestou a cobrança no emissor | Não |
| **Assinatura atrasada** | a renovação da assinatura falhou ou está em atraso | Não |
| **Assinatura cancelada** | a assinatura foi encerrada | Não |

Os quatro estágios **acionáveis** são os que entram na conta da taxa de recuperação. Reembolso e
chargeback nunca contam como recuperação — são o oposto disso.

`due_soon` continua sendo um valor armazenado válido por compatibilidade, mas nenhum conector ou gateway
nativo atual o produz. Por isso ele não é oferecido na recuperação automática nem no seletor de Follow-up.

## Pré-requisitos

- A funcionalidade **Recuperação de vendas** (`commerce_recovery`) **habilitada na conta**. Ela vem
  **desligada por padrão**; peça a ativação a quem administra a instalação.
- Perfil de **administrador** ou de **agente** na conta. Ambos podem abrir a página de recuperação,
  alterar políticas e reenviar cards — não existe permissão separada por módulo aqui.
- Pelo menos uma **fonte de comércio** conectada (Kiwify, Hotmart, Nuvemshop) ou um **gateway nativo**
  configurado (Asaas / Mercado Pago), para que os eventos cheguem.
- Para envio fora da janela do WhatsApp: um **template aprovado** na caixa de entrada correspondente.

Sem a funcionalidade ligada, a nova página, o painel lateral e as métricas ficam ocultos. A entrega em
si (política de conversa, resultado registrado) continua funcionando nos bastidores — é infraestrutura
de comportamento preservado.

## Passo a passo

1. Abra **Recuperação de vendas** no menu do módulo de comércio.
2. Confira o **funil acionável por estágio**: ele usa os mesmos quatro estágios das métricas de
   tentativas e recuperações; liquidações, reembolsos e cancelamentos não entram nesse funil.
3. Olhe o bloco de **entrega**: `enviado`, `ignorado`, `falhou` e `não tentado`.
4. Abra a lista de **motivos** — ela vem ordenada do mais frequente para o menos frequente. É a sua
   lista de correção, em ordem de impacto.
5. Clique em um evento para ver o card, a conversa de destino e o histórico de entrega.
6. Se o card não saiu por um motivo já corrigido (canal reconectado, template aprovado), use
   **Reenviar**. Se precisar passar por cima da guarda de duplicidade, marque **forçar**.
7. Ajuste a **política de conversa** na ação de automação/macro para que o próximo evento do mesmo tipo
   não caia no mesmo motivo.

## Configurações & opções

### A política de conversa (a escolha mais importante)

Quando o card precisa ser entregue, a plataforma precisa saber **em qual conversa** escrever. Você tem
três opções:

| Política | O que faz | Quando usar |
|---|---|---|
| **Usar uma conversa existente** *(padrão)* | Entrega na conversa mais recente do contato. **Nunca cria** uma conversa. Se não houver nenhuma, o card é ignorado com o motivo `no_conversation`. | Padrão seguro — é exatamente o comportamento de hoje. Nada muda para quem já usa. |
| **Criar uma se necessário** | Usa a conversa existente quando há uma; **cria uma nova** quando não há. | Quando você quer alcance máximo e aceita que uma conversa nova apareça para o cliente. |
| **Somente esta conversa** | Entrega estritamente na conversa em que a regra foi disparada. Nunca procura outra, nunca cria. | Quando o card só faz sentido no contexto daquele atendimento específico. |

> **Por que "criar uma se necessário" é opt-in:** criar uma conversa é uma ação **visível para o
> cliente** e para a fila do time. Ela aparece no inbox, conta nos relatórios e pode gerar notificação.
> Por isso Conversa Labs nunca faz isso por conta própria — você precisa escolher.

### A janela de 24 horas do WhatsApp (sem meias-verdades)

O WhatsApp só permite mensagem livre dentro de **24 horas** desde a última mensagem do cliente. Fora
dessa janela:

- **Sem template aprovado** → o card é **ignorado**, com o motivo `whatsapp_window_closed`. Ele **não é
  entregue**. Conversa Labs prefere registrar a razão a enfileirar uma mensagem que o WhatsApp vai
  rejeitar.
- **Com template aprovado** → a entrega **degrada para a mensagem única do template**. Você recebe o
  contato, mas **não** o card rico completo: apenas o que o template aprovado permite.

**WhatsApp Web não tem janela.** Caixas de entrada WhatsApp Web entregam normalmente a qualquer momento
— a restrição de 24h é da API oficial do WhatsApp Business, não da plataforma.

**Exceção: par híbrido.** Se você tem um par híbrido com Cloud como principal e roteamento de fora da
janela para o WhatsApp Web, o envio sai completo por sessão do Web — não vira template nem é pulado.
Nesse caso não espere ver `whatsapp_window_closed`.

### Outros canais

O card sempre inclui o **link de pagamento no corpo da mensagem**, nunca só em anexo. Isso é
deliberado: **LINE, TikTok e X (Twitter)** descartam ou rejeitam anexos. Se o link viajasse apenas no
anexo, o cliente receberia uma mensagem sem a única coisa que importa.

### Entrega dos cards e a fila de "não tentado"

O painel mostra a **repartição da entrega** — enviados, ignorados, com falha e **não tentados**. O
balde "não tentado" é o que nunca teve card algum: nenhuma regra agiu sobre aquele evento. Ele deixou
de ser um número solto: agora dá para **filtrar por ele** na linha do tempo e **enfileirar os pendentes**
em lotes limitados, do mais antigo para o mais novo, até 50 por vez.

A ação responde **aceito/enfileirado**, não uma contagem de entregas. O processamento acontece em
segundo plano e os resultados reais (`enviado`, `ignorado` ou `falhou`) aparecem depois na linha do
tempo. Ela nunca abre uma conversa nova: um evento sem destino fica registrado como ignorado com o
motivo correspondente. Histórico importado ou adotado de gateway fica sempre fora dessa fila.

> **Por que "Recuperações tentadas" pode aparecer como 0 com a lista cheia.** A conta considera só os
> eventos acionáveis **cujo card foi registrado como enviado**. Se nenhum card foi enviado, o denominador é zero —
> não é a página quebrada, é a informação de que ninguém foi abordado ainda.

### Recuperação automática por estágio (desligada por padrão)

Em **Mensagens → Recuperação automática por estágio**, ligue apenas os estágios ao vivo que você quer
que o Conversa Labs enfileire automaticamente. Todos os controles começam **desligados**. O evento imediato
enfileira o card, e um backstop a cada cinco minutos repara uma passagem perdida para a fila. Os dois
caminhos conferem o controle novamente antes da entrega, reutilizam uma conversa existente, respeitam
a janela de 24h do WhatsApp e adiam quando o limite seguro de envio da conexão está cheio.

Cobranças importadas ou adotadas são histórico: continuam visíveis para auditoria e relatórios, com o
selo **Histórico — envio bloqueado**, mas são excluídas de qualquer envio ao cliente. Recuperação
automática, dreno manual, backstop, Follow-up, reenvio forçado, automações e Maestro não atravessam
essa proteção.

### Ordem das mensagens do card

O card é uma sequência: resumo → botão de pagar → PIX copia-e-cola → QR Code → boleto → linha
digitável. Essa ordem agora é **garantida na entrega** — antes cada mensagem saía por conta própria e
podiam chegar embaralhadas (o código PIX cru chegando antes da mensagem que manda copiá-lo).

Em **Mensagens → Entrega** você define o **intervalo entre as mensagens do card**. Deixe em branco
para usar o padrão do canal: no WhatsApp conectado por celular (WazMeow) é 1 segundo, para espaçar a
rajada e não parecer disparo automático; nos demais canais não há pausa.

### Abrir a conversa e reenviar

Cada linha ao vivo da lista tem **Abrir conversa** (vai direto para o atendimento daquele cliente) e
**Reenviar card**. O reenvio mira a conversa pelo identificador público — nunca corre o risco de cair
no cliente errado. Se o evento ainda não tem conversa, o diálogo avisa antes de confirmar que uma
conversa será aberta com o cliente. Linhas históricas não exibem reenvio e a API também recusa a ação,
mesmo com **forçar**.

## Casos de uso

- **PIX pendente que esfriou**: o cliente gerou o PIX ontem e sumiu. O card reenvia o código na conversa
  existente, sem criar ruído novo.
- **Recusa de cartão em massa**: uma emissora derrubou várias transações. Você filtra por
  `payment_declined`, vê que todas foram ignoradas por `channel_unavailable`, reconecta o canal e
  reenvia em lote.
- **Carrinho abandonado de quem nunca falou com você**: contato novo, sem conversa. Com a política
  "criar uma se necessário", o card abre a conversa e inicia o atendimento.
- **Auditoria de cadência**: a lista de motivos mostra que 60% dos envios morreram em
  `whatsapp_window_closed` — o sinal claro de que aquela cadência precisa de template aprovado.

## Dicas, limites e boas práticas

### Os resultados de entrega e o que fazer com cada um

Todo evento termina em um destes estados: **enviado**, **ignorado**, **falhou** — ou **não tentado**,
quando nenhuma regra agiu sobre ele.

| Motivo | O que significa | O que fazer |
|---|---|---|
| `no_contact` | O evento chegou sem um contato identificável (a plataforma de origem não enviou telefone/e-mail utilizável). | Verifique o mapeamento de identificação na fonte de comércio. Sem contato não há para quem enviar. |
| `no_conversation` | O contato existe, mas não há conversa para receber o card e a política é "usar uma conversa existente". | Se quer alcançar esses casos, mude a política para **criar uma se necessário**. |
| `no_channel_inbox` | Não existe caixa de entrada do canal pedido pela ação. | Conecte a caixa de entrada daquele canal, ou aponte a ação para uma caixa que exista. |
| `whatsapp_window_closed` | Fora da janela de 24h e sem template aprovado. | Anexe um **template aprovado** à ação. Ou desloque a cadência para dentro da janela. |
| `throttled` | O limite de envio do canal foi atingido naquele momento. | Espace a cadência. Rajadas grandes em WhatsApp também aumentam risco de bloqueio. |
| `channel_unavailable` | O canal está desconectado, expirado ou indisponível. | Reconecte a caixa de entrada e reenvie os eventos afetados. |
| `sequence_not_published` | A sequência de Follow-up ainda está em rascunho. | Publique a sequência. Rascunho nunca envia — é proposital. |
| `already_sent` | A guarda de duplicidade barrou: esse evento já teve card registrado como enviado. | Nada, na maioria dos casos. Se precisa mesmo reenviar, use **Reenviar** com **forçar**. |

### Integrando com sistemas externos

Cada resultado de entrega — enviado, pulado ou falhou — também sai como o evento de webhook de conta
`commerce_card_delivery`, com o motivo canônico junto. É por ele que um sistema externo (n8n, CRM)
reage sem ficar consultando: por exemplo, abrir uma tarefa quando o motivo for `no_conversation`, ou
tentar outro canal quando for `whatsapp_window_closed`. Ative-o em **Configurações → Integrações →
Webhooks**.

### A guarda de duplicidade e o reenvio explícito

Um mesmo evento cria e despacha localmente o card **uma vez**. Se uma automação e uma macro tentarem
enviar o mesmo card, a segunda é ignorada com `already_sent` — essa é a guarda local de duplicidade.
A entrega final do provedor ainda precisa ser conferida no estado da mensagem/conversa do canal.

O **reenvio** é sempre explícito e humano: você abre o evento e clica em **Reenviar**. Ele preserva o
registro do primeiro envio (data e mensagem originais) e apenas incrementa o contador de reenvios — o
histórico nunca é apagado. Para atravessar a guarda de propósito, marque **forçar**.

### Como ler a taxa de recuperação (com honestidade)

A taxa de recuperação é a **proporção de tentativas acionáveis registradas como enviadas que receberam
uma liquidação posterior atribuível ao mesmo contato e ao mesmo pedido**.

Com precisão:

- **Denominador**: eventos acionáveis (carrinho abandonado, pendente, recusado, vencido)
  **cujo card foi registrado como enviado**.
- **Numerador**: liquidações posteriores com o **mesmo contato, a mesma origem e o mesmo identificador
  externo do pedido/cobrança**. Pagar outro pedido não recupera o primeiro.
- Uma liquidação conta **uma única vez**. Se o mesmo pedido recebeu vários cards acionáveis, ela é
  atribuída deterministicamente à tentativa registrada como enviada mais recente anterior à
  liquidação. **Pedido criado nunca liquida receita**: somente `payment_confirmed` entra no numerador.
- Eventos cujo card nunca foi registrado como enviado ficam fora **dos dois lados**. O estado
  `enviado` confirma a criação e o despacho local do card; ele ainda não é um recibo final do provedor.
- Quando **nada** foi tentado no período, a taxa aparece como **—**, não como 0%. Zero por cento
  significaria "tentamos e falhamos"; travessão significa "não houve tentativa".

> **Isto é correlação, não causalidade.** A métrica diz "o cliente pagou depois de a gente falar com
> ele", e não "o cliente pagou **porque** a gente falou com ele". Parte dessas pessoas pagaria de
> qualquer forma. Use o número para comparar cadências entre si e acompanhar tendência — não o
> apresente como receita atribuída a uma campanha.

A **receita recuperada usa o valor e a moeda da liquidação**, não o valor que aparecia no card. Os
totais são exibidos separadamente por moeda — por exemplo, BRL e USD nunca são somados nem rotulados
como se tudo fosse BRL. Valores monetários permanecem na **unidade principal** da moeda e não há
conversão escondida. Quando a origem não informa a moeda, a interface deixa essa ausência explícita.

## Solução de problemas

- **"Não tentado" em muitos eventos**: nenhuma regra está agindo sobre aquele estágio. Crie uma
  automação ou uma sequência de Follow-up para o estágio em questão.
- **Tudo ignorado com `no_conversation`**: sua base é de contatos sem conversa aberta e a política é a
  padrão. Mude para **criar uma se necessário** — lembrando que a conversa nova é visível ao cliente.
- **Tudo ignorado com `whatsapp_window_closed`**: a cadência está rodando fora da janela de 24h.
  Aprove um template e anexe-o à ação, ou antecipe o disparo.
- **Card entregue, mas “pobre”**: você está fora da janela **com** template. É o comportamento correto —
  o WhatsApp só aceita o template aprovado nessa situação.
- **`channel_unavailable` intermitente**: a caixa de entrada está caindo. Verifique a conexão do canal
  antes de reenviar em lote, senão os reenvios falham pelo mesmo motivo.
- **O cliente recebeu duas vezes**: verifique se há uma automação **e** uma sequência de Follow-up
  cobrindo o mesmo estágio, ou se alguém usou **forçar** no reenvio.
- **A taxa aparece como “—”**: nenhum card de recuperação foi registrado como enviado no período
  filtrado. Amplie o período ou verifique a lista de motivos.
- **A página não aparece**: a funcionalidade `commerce_recovery` está desligada na conta, ou seu
  usuário não é administrador nem agente nela.

## Veja também

- [Ciclo de vida de e-commerce: webhooks Kiwify/Hotmart/Nuvemshop/Shopify](/hc/ajuda/articles/catalog-commerce-commerce-lifecycle-pt-br)
- [Visão geral de Catálogo & Comércio](/hc/ajuda/articles/catalog-commerce-overview-pt-br)
- [Enviar produto e receber pedidos na conversa](/hc/ajuda/articles/catalog-commerce-enviar-produto-pedido-na-conversa-pt-br)