## Visão geral

O **ciclo de vida de e-commerce** conecta plataformas externas — **Kiwify, Hotmart, Nuvemshop e
Shopify** — para que os eventos de venda cheguem dentro do atendimento. Quando algo acontece na
plataforma externa (carrinho abandonado, PIX/boleto gerado, compra aprovada, recusada ou reembolsada),
a ConversaLabs recebe o **webhook**, normaliza o evento e mostra um **card na conversa** do cliente,
com os dados de pagamento quando disponíveis.

Com isso, você recupera vendas sem trocar de ferramenta: o time vê o estágio da compra na própria
conversa e pode acionar **Follow-ups** automáticos para reconquistar quem não finalizou.

## Pré-requisitos

- Módulo de **Catálogo & Comércio** habilitado e permissão para configurar fontes de comércio.
- Acesso à plataforma externa (Kiwify, Hotmart, Nuvemshop ou Shopify) para configurar o webhook.
- Para recuperação automática: o módulo de **Follow-ups** configurado com sequências por evento.

## Passo a passo

1. Na área de **Catálogo & Comércio**, crie uma **fonte de comércio** para a plataforma desejada.
2. Copie a **URL de webhook completa** gerada para essa fonte. Ela inclui a conta e a fonte; não
   remova nenhum trecho. Configure também o **segredo de verificação**. Na Kiwify, o registro
   automático pode gerar e salvar o token; na Hotmart, informe o Hottok da aplicação.
3. Cole a URL no painel da plataforma externa (ou use o **registro automático** quando disponível, por
   exemplo em Kiwify e Nuvemshop).
4. Faça uma venda de teste (ou um carrinho de teste) para confirmar que o evento chega.
5. Veja o **card do evento** aparecer na conversa do cliente, com itens, valores e link/dados de
   pagamento conforme o estágio.
6. Configure **Follow-ups** acionados por evento (por exemplo, "carrinho abandonado") para recuperar a
   venda automaticamente.

## Configurações & opções

### Pagamento e envio do card são estados diferentes

No painel **Comércio** da conversa, o título indica o evento comercial registrado e **Envio do
card** indica somente a tentativa de envio daquele card. **Pagamento confirmado** junto de
**Não tentado** não significa pagamento pendente: a confirmação financeira foi registrada, mas
esse card de Comércio ainda não teve envio registrado. Outras mensagens de pagamento podem já
estar na conversa.

Use **Ver card** para abrir a mensagem correlacionada, quando existir, ou **Abrir conversa** para
consultar o histórico. **Enviar confirmação** ou **Reenviar confirmação** abre um diálogo antes
do envio; você pode cancelar. Essa ação não cria uma cobrança nem altera a confirmação financeira.
Se o card já estiver registrado, o reenvio exige sua confirmação explícita. Sem conversa vinculada,
o servidor busca uma conversa existente do contato; esse painel não abre uma conversa nova.

Um card registrado na conversa não é prova de recebimento pelo cliente: confira também o status
da mensagem e do canal. Falha, envio recusado e resposta não confirmada não são apresentados como
sucesso. Mensagens e boletos enviados antes da quitação continuam no histórico; sua presença não
transforma um pagamento confirmado em pendente. Não use a imagem de um comprovante para substituir
o status financeiro registrado pelo gateway ou pelo operador autorizado.

- **Fonte de comércio**: uma por plataforma, com URL de webhook e segredo de verificação próprios.
- **Registro automático do webhook**: disponível em parte das plataformas (ex.: Kiwify e Nuvemshop);
  nas demais, a configuração é manual no painel da própria plataforma.
- **Card do evento**: mostra o estágio da compra e, quando a plataforma expõe, dados de PIX/boleto e o
  link de checkout.
- **Variáveis de comércio**: dados do último evento ficam disponíveis para uso em mensagens de
  Follow-up (link de pagamento, valor, código PIX/boleto, etc.).

### Escolher quais eventos receber

Ao editar a fonte em **Catálogo → Fontes de sincronização → editar a fonte**, a seção **Eventos** lista
os eventos que aquela plataforma envia e permite mapear **cada um** para um estágio do ciclo de vida — ou
marcá-lo como **Desligado (ignorar)** para descartá-lo por completo.

Todo evento habilitado percorre o resto da plataforma: **automações, flows, webhooks, Follow-up e o
CRM**. O mapeamento é o que decide **em qual estágio** ele entra.

Um botão em destaque de **Recuperação de carrinho abandonado** liga e desliga o evento de carrinho da
plataforma — é ele que alimenta a cadência de recuperação no Follow-up (gatilho `commerce.cart_abandoned`).

Disponível para:

| Fonte | Eventos que você mapeia |
|---|---|
| **Hotmart** | eventos de compra, carrinho, assinatura e área de membros |
| **Kiwify** | os 10 gatilhos reais: `compra_aprovada`, `pix_gerado`, `boleto_gerado`, `compra_recusada`, `compra_reembolsada`, `chargeback`, `carrinho_abandonado`, `subscription_renewed`, `subscription_late`, `subscription_canceled` |
| **Nuvemshop** | os valores de `payment_status` do pedido: `paid`, `authorized`, `pending`, `refunded`, `partially_refunded`, `abandoned` — o webhook da Nuvemshop traz apenas o ID, então o estágio vem do status de pagamento do pedido |
| **Fontes genéricas** | os nomes de evento documentados pelo seu sistema. Você define explicitamente o campo do evento, o ID, os caminhos de comprador/produto/itens e o estágio canônico; nada é inferido pelo nome de uma plataforma |

Fontes gerenciadas sem um contrato verificado de ciclo de venda, como **Mercado Livre e OLX**, não
exibem um seletor de eventos. Fontes atendidas pelo conector genérico — inclusive uma configuração
Shopify/API própria — exibem a configuração do webhook genérico assinado e recebem somente os eventos
que você mapear explicitamente.

Os padrões já são sensatos: só mexa no mapeamento se quiser um estágio diferente ou se quiser ignorar
um evento.

### Quem aparece como autor do card de recuperação

Quando um **assistente de IA ou robô ativo** envia o card de recuperação, a mensagem fica registrada
com a autoria do próprio robô. Ele deve estar ativo na **caixa de entrada da conversa**, na **mesma
conta**, e o evento usado na recuperação deve pertencer ao **mesmo contato da conversa**.

Quando um **atendente** envia o card, a mensagem fica registrada com a autoria do próprio atendente.

## Casos de uso

- **Carrinho abandonado**: dispara uma sequência de Follow-up lembrando o cliente de concluir.
- **PIX/boleto pendente**: reenvia o código de pagamento e acompanha até confirmar.
- **Compra aprovada**: confirma com o cliente e libera o próximo passo do atendimento.
- **Reembolso/recusa**: alerta o time para tratar o caso na própria conversa.

## Dicas, limites e boas práticas

- **O que cada plataforma expõe varia**: algumas enviam o **código PIX e a linha do boleto** no evento
  (recuperação completa dentro da conversa); outras só fornecem o **link de checkout** — nesses casos,
  o card mostra o link para o cliente concluir.
- **Valores e formatos diferem por plataforma**: a ConversaLabs normaliza cada evento; você não precisa
  se preocupar com a conversão — o card já exibe o valor correto.
- **Segredo de verificação**: mantenha-o configurado para que apenas eventos legítimos da plataforma
  sejam aceitos. Webhooks Hotmart, Kiwify, Nuvemshop e genéricos sem segredo configurado são recusados. Um emissor
  genérico também precisa enviar a assinatura com timestamp e um ID de entrega estável por evento.
- Combine com Follow-ups para automatizar a recuperação em vez de depender de ação manual.

Uma mensagem registrada ou um card visível na conversa não confirma a entrega pelo canal do cliente.
Antes de informar que o cliente recebeu, confira o **status de entrega da mensagem** e a **conexão do
canal**.

## Solução de problemas

- **O reenvio ficou sem resposta**: o card pode já ter sido aceito pelo servidor. O painel bloqueia
  outra tentativa e oferece **Conferir resultado registrado**, que apenas consulta os registros.
  Se ainda não houver um resultado verificável, confira a conversa; a consulta não reenvia o card.
  A proteção permanece ao fechar e reabrir a confirmação. Com o armazenamento de sessão disponível,
  ela também sobrevive a recarregar na mesma aba; se o navegador negar o armazenamento, dura enquanto
  o painel estiver montado. Isso não comprova entrega nem protege entre abas diferentes.
- **O estado da cobrança mudou**: um evento antigo de confirmação não é reenviado quando a cobrança
  nativa atual está estornada, cancelada ou em outro estado incompatível. Consulte **Pagamentos**.
- **PIX/boleto sumiram depois do pagamento**: instrumentos antigos continuam no histórico, mas não
  são oferecidos novamente para cobranças liquidadas, estornadas, canceladas ou arquivadas. Um estorno
  parcial não cria uma nova dívida. Parcelas realmente abertas de um plano continuam com suas ações.
- **A confirmação não pode ser enviada fora da janela do WhatsApp**: use um modelo aprovado de
  confirmação sem botão de pagamento configurado. Um modelo de cobrança não é reutilizado para uma
  cobrança quitada. Confira também se o conteúdo e os botões estáticos aprovados são de confirmação.

- **O evento não aparece**: confira se a URL completa de webhook foi colada corretamente na plataforma
  e se o segredo de verificação está configurado e confere.
- **Não vejo PIX/boleto no card**: nem toda plataforma expõe esses dados; quando não há, o card traz o
  link de checkout.
- **Eventos duplicados**: entregas genéricas com o mesmo ID são processadas uma única vez. Se notar algo
  estranho, confirme que o emissor reutiliza esse ID nas tentativas e que há apenas um webhook
  configurado para a mesma fonte.
- **O robô não envia o card de recuperação**: confira se está ativo na caixa de entrada da conversa,
  na mesma conta, e se o evento pertence ao mesmo contato da conversa.
- **O card aparece, mas o cliente não recebeu**: confira o status de entrega da mensagem e a conexão
  do canal antes de confirmar o recebimento ao cliente.

## Veja também

- [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)
- [Catálogo nativo: produtos, categorias, imagens e preços](/hc/ajuda/articles/catalog-commerce-catalogo-nativo-pt-br)