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 Conversa Labs 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
- Na área de Catálogo & Comércio, crie uma fonte de comércio para a plataforma desejada.
- 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.
- Cole a URL no painel da plataforma externa (ou use o registro automático quando disponível, por exemplo em Kiwify e Nuvemshop).
- Faça uma venda de teste (ou um carrinho de teste) para confirmar que o evento chega.
- Veja o card do evento aparecer na conversa do cliente, com itens, valores e link/dados de pagamento conforme o estágio.
- Configure Follow-ups acionados por evento (por exemplo, "carrinho abandonado") para recuperar a venda automaticamente.
Configurações & opções
- 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.
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 Conversa Labs 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.
Solução de problemas
- 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.