📚 Guia de Integração - Wite Recuperation

Documentação completa para integração da sua plataforma com o sistema Wite Recuperation

---

📖 Índice

1. Visão Geral
2. Webhooks de Gateways
   • Kirvano
   • WitePay
   • Yampi
   • Vega Checkout
   • Luna
3. Serviços de Disparo
   • Disparo em Massa WhatsApp
   • Disparo SMS
   • Disparo com IA
4. Exemplos Práticos
5. Troubleshooting

---

🎯 Visão Geral

O Wite Recuperation é uma plataforma completa para recuperação de carrinhos abandonados e automação de campanhas via WhatsApp e SMS. Este guia mostrará como integrar sua plataforma de vendas com nossos serviços.

O que você pode fazer:

✅ Recuperar Carrinhos Abandonados - Envie mensagens automáticas quando clientes abandonam o carrinho
✅ Notificar Compras - Receba notificações quando uma venda é aprovada
✅ Disparos em Massa - Envie campanhas para milhares de contatos via WhatsApp
✅ Campanhas SMS - Dispare SMS em massa para sua base de clientes
✅ IA Conversacional - Agentes com IA que conversam naturalmente com clientes

---

🔗 Webhooks de Gateways

Como Funciona

Quando um evento importante acontece na sua plataforma (carrinho abandonado, PIX expirado, compra aprovada), você precisa enviar um webhook para o nosso sistema. Nós processamos automaticamente e acionamos o agente de recuperação configurado.

URL do Webhook

Cada agente criado na plataforma recebe uma URL única de webhook:

https://api.witerecuperation.com/api/webhooks/{webhook_url}

Onde encontrar sua URL:

1. Acesse o painel do cliente
2. Vá em "Agentes"
3. Clique no agente desejado
4. Copie a "URL de Webhook"

---

Kirvano

Eventos Suportados

Evento	Descrição	Ação
CART_ABANDONED	Carrinho abandonado	Inicia recuperação automática
CHECKOUT_ABANDONED	Checkout abandonado	Inicia recuperação automática
PIX_EXPIRED	PIX expirou sem pagamento	Inicia recuperação de PIX
PAYMENT_PENDING	Pagamento pendente	Monitora para recuperação
SALE_APPROVED	Venda aprovada	Marca carrinho como recuperado

Configuração na Kirvano

1. Acesse o painel da Kirvano
2. Vá em Configurações → Webhooks
3. Adicione novo webhook:
   • URL: https://api.witerecuperation.com/api/webhooks/{sua_webhook_url}
   • Eventos: Selecione todos os eventos acima
   • Método: POST
   • Content-Type: application/json

Características Específicas

• ✅ Preços vêm formatados como string: "R$ 119,90"
• ✅ Campo phone_number ao invés de phone
• ✅ Campo is_order_bump para identificar upsells
• ✅ Suporta recovery_url para link de recuperação

---

WitePay

Eventos Suportados

Evento	Descrição	Ação
CART_ABANDONED	Carrinho abandonado	Inicia recuperação automática
CHECKOUT_ABANDONED	Checkout abandonado	Inicia recuperação automática
PIX_EXPIRED	PIX expirou	Inicia recuperação de PIX
PAYMENT_APPROVED	Pagamento aprovado	Marca carrinho como recuperado
ORDER_PAID	Pedido pago	Marca carrinho como recuperado

Configuração na WitePay

1. Acesse o painel da WitePay
2. Vá em Integrações → Webhooks
3. Adicione webhook:
   • URL: https://api.witerecuperation.com/api/webhooks/{sua_webhook_url}
   • Eventos: Selecione os eventos desejados
   • Formato: JSON

Características Específicas

• ✅ Campo intent_id como identificador principal
• ✅ Campo phone (ao invés de phone_number)
• ✅ Preços em formato numérico: 97.00
• ✅ Estrutura items ao invés de products
• ✅ Timestamps em formato ISO 8601

---

Yampi

Eventos Suportados

Evento	Descrição	Ação
cart.reminder	Carrinho abandonado	Inicia recuperação automática
order.created	Pedido criado	Monitora pagamento
order.paid	Pedido pago	Marca carrinho como recuperado
order.status.updated	Status atualizado	Atualiza status interno

Configuração na Yampi

1. Acesse o painel da Yampi
2. Vá em Configurações → Webhooks
3. Adicione webhook:
   • URL: https://api.witerecuperation.com/api/webhooks/{sua_webhook_url}
   • Eventos: Selecione os eventos acima

Características Específicas

• ✅ Estrutura profundamente aninhada: resource.customer.data.*
• ✅ Campo token como identificador do carrinho
• ✅ Telefone em phone.full_number
• ✅ Objeto totalizers com todos os valores

---

Vega Checkout

Eventos Suportados

Evento	Descrição	Ação
CART_ABANDONED	Carrinho abandonado	Inicia recuperação automática
Status approved	Transação aprovada	Marca carrinho como recuperado

Características Específicas

• ✅ Preços em centavos como string: "23600" = R$ 236,00
• ✅ Campo abandoned_cart_code como ID
• ✅ URL com typo: abandoned_checkout_url_url (sim, duplicado)
• ✅ Campos adicionais de endereço (district, zip_code)

---

Luna

Eventos Suportados

Evento	Descrição	Ação
sale_cart_abandoned	Carrinho abandonado	Inicia recuperação automática
event_sale_pending	Venda pendente	Monitora pagamento
event_sale_paid	Venda paga	Marca carrinho como recuperado

Características Específicas

• ✅ Usa client ao invés de customer
• ✅ Campo doc ao invés de document
• ✅ Campo items ao invés de products
• ✅ Preços como strings: "99.99"

---

🚀 Serviços de Disparo

Disparo em Massa WhatsApp

Envie mensagens personalizadas para milhares de contatos via WhatsApp com nosso sistema de disparo em massa.

Como Usar no Painel

1. Acesse "Disparo em Massa" no menu lateral
2. Clique em "Nova Campanha"
3. Dê um nome para sua campanha (ex: "Black Friday 2024")
4. Faça upload do CSV com seus contatos

Formato do CSV:

nome,email,telefone,cpf
João Silva,joao@email.com,11987654321,12345678900
Maria Santos,maria@email.com,21987654321,98765432100

5. Configure as mensagens:

   • Digite o texto da mensagem
   • Use variáveis: {{nome}}, {{email}}, {{telefone}}
   • Adicione links, emojis

6. Selecione o agente

7. Clique em "Criar Campanha"

8. Revise e inicie o disparo

Monitorar Resultados

Após iniciar, você pode acompanhar em tempo real:

• Total de contatos na campanha
• Mensagens enviadas
• Mensagens entregues
• Taxa de leitura
• Taxa de resposta
• Erros (números inválidos, etc)

Acesse: Disparo em Massa → Campanhas → [Sua Campanha] → Estatísticas

---

Disparo SMS

Envie SMS em massa para sua base de clientes usando nosso sistema integrado com Mobizon.

Como Usar no Painel

1. Assine um Plano SMS:

   • Acesse: Planos SMS no menu
   • Escolha o plano ideal (ex: 1000 SMS/mês)
   • Selecione forma de pagamento (PIX, Cartão)
   • Confirme a assinatura

2. Criar Campanha:

   • Acesse: SMS → Nova Campanha
   • Dê um nome (ex: "Promoção Black Friday")
   • Digite a mensagem (máx 160 caracteres)
   • Defina o remetente (sua marca)
   • Faça upload do CSV com destinatários ou selecione lista existente

Formato CSV para SMS:

telefone,nome,cpf
5511987654321,João Silva,12345678900
5521987654321,Maria Santos,98765432100

3. Agende ou Envie Imediatamente:
   • Enviar agora ou agendar para data/hora específica
   • Revise a prévia
   • Clique em "Enviar SMS"

Monitorar Resultados

Acompanhe em tempo real:

• SMS enviados
• SMS entregues
• Falhas (números inválidos)
• Taxa de entrega

Acesse: SMS → Campanhas → [Sua Campanha] → Estatísticas

---

Disparo com IA

Configure agentes com inteligência artificial para conversas naturais e personalizadas.

Como Funciona

1. Você cria um Agente no painel com informações do produto
2. Sistema recebe webhook de carrinho abandonado ou PIX expirado
3. IA inicia conversa automática com o cliente
4. Cliente responde e IA mantém conversa natural
5. IA identifica intenção de compra e envia link de checkout

Como Configurar no Painel

1. Acesse "Agentes" no menu

2. Clique em "Novo Agente"

3. Preencha as informações:

   • Nome do agente (ex: "Agente de Vendas")
   • Nome do produto
   • Preço do produto
   • Descrição e benefícios
   • Cupom de desconto (opcional)
   • URL do checkout

4. Configure o prompt da IA:

   • Como o agente deve se comportar
   • Que gatilhos usar (urgência, escassez, prova social)
   • Como responder objeções comuns

5. Ative voz (opcional):

   • Escolha gênero (masculino/feminino)
   • Selecione voz humanizada

6. Vincule ao gateway:

   • Selecione de qual plataforma virão os webhooks
   • Copie a URL de webhook
   • Configure no seu gateway (Kirvano, WitePay, etc)

7. Salve e ative o agente

Monitorar Conversas

Acompanhe em tempo real todas as conversas do agente:

• Acesse: Agentes → [Seu Agente] → Conversas
• Veja todas as mensagens trocadas
• Status: enviada, entregue, lida, respondida
• Taxa de conversão
• Vendas recuperadas

Para mais detalhes sobre treinamento do agente, veja: Treinamento de Agentes

---

💡 Casos de Uso

Caso 1: Recuperação Automática de Carrinhos (Kirvano)

Cenário: Loja de cursos online quer recuperar carrinhos abandonados automaticamente

Passos:

1. Criar agente no Wite Recuperation com informações do curso
2. Copiar URL de webhook do agente
3. Configurar webhook na Kirvano apontando para essa URL
4. Selecionar evento: "CART_ABANDONED"
5. Salvar configuração

Resultado:

• Cliente abandona carrinho na Kirvano
• Kirvano envia webhook automaticamente
• IA inicia conversa no WhatsApp do cliente
• Cliente tira dúvidas com a IA
• IA oferece desconto e envia link
• Cliente finaliza compra
• Kirvano notifica venda aprovada
• Sistema marca como "recuperado" ✅

---

Caso 2: Campanha SMS Black Friday

Cenário: E-commerce quer avisar toda base sobre promoção

Passos:

1. Assinar plano SMS no painel
2. Exportar lista de clientes (CSV)
3. Criar nova campanha SMS
4. Upload do CSV
5. Escrever mensagem: "BLACK FRIDAY! 50% OFF até meia-noite. Corra: suaurl.com"
6. Agendar para 00:00 do dia da Black Friday
7. Confirmar envio

Resultado:

• 10.000 SMS enviados automaticamente
• Taxa de entrega: 98%
• 2.500 acessos ao site
• R$ 85.000 em vendas geradas

---

Caso 3: Reengajamento de Clientes Inativos

Cenário: Recuperar clientes que não compram há 30+ dias

Passos:

1. Filtrar clientes inativos (CSV)
2. Criar campanha WhatsApp no painel
3. Configurar mensagens em sequência:
   • Msg 1: "Oi {{nome}}! Sentimos sua falta 😊"
   • Msg 2 (+5seg): "Desconto de 20% exclusivo: VOLTE20"
   • Msg 3 (+3seg): "Acesse: {{link_loja}}"
4. Fazer upload do CSV
5. Iniciar campanha

Resultado:

• 5.000 clientes contatados
• 850 reabriram conversa
• 320 usaram cupom
• Taxa de reengajamento: 17%

---

🐛 Troubleshooting

Webhook não está sendo recebido

Problema: Configurei o webhook mas não recebo notificações

Soluções:

1. ✅ Verifique se a URL está correta (sem espaços ou caracteres especiais)
2. ✅ Certifique-se de que o agente está ativo no painel
3. ✅ Verifique os logs do gateway (Kirvano, WitePay, etc)
4. ✅ Teste com ferramentas como Postman ou cURL
5. ✅ Verifique se o firewall não está bloqueando requisições

Como testar:

1. Crie um carrinho de teste no seu gateway
2. Abandone o carrinho
3. Aguarde 2-3 minutos
4. Verifique se recebeu mensagem no WhatsApp de teste
5. Confira os logs no painel: Agentes → [Seu Agente] → Logs

Mensagens não estão sendo enviadas

Problema: Webhook foi recebido mas cliente não recebe mensagem

Soluções:

1. ✅ Verifique se a instância do WhatsApp está conectada
2. ✅ Vá em Agentes → Instâncias e veja o status
3. ✅ Verifique se o número do chip está ativo
4. ✅ Confirme que tem saldo/créditos suficientes
5. ✅ Verifique se o telefone do cliente está no formato correto

Formato correto de telefone:

• ✅ Com DDI e DDD: 5511987654321
• ✅ Apenas números, sem espaços ou caracteres
• ❌ Errado: (11) 98765-4321
• ❌ Errado: 11 98765-4321

Taxa de entrega baixa no SMS

Problema: Muitos SMS não estão sendo entregues

Soluções:

1. ✅ Verifique se os números estão no formato internacional: 5511987654321
2. ✅ Remova números inválidos ou inexistentes
3. ✅ Evite caracteres especiais na mensagem (pode quebrar em múltiplos SMS)
4. ✅ Use remetente aprovado (max 11 caracteres)
5. ✅ Não envie links muito longos (encurte com bit.ly)

IA não está respondendo corretamente

Problema: Agente IA dá respostas genéricas ou inadequadas

Soluções:

1. ✅ Revise e melhore o prompt do agente
2. ✅ Adicione mais detalhes sobre o produto nos campos
3. ✅ Configure os gatilhos de recuperação adequadamente
4. ✅ Teste o prompt com diferentes cenários
5. ✅ Use exemplos de conversas bem-sucedidas no prompt

Exemplo de prompt melhorado:

Você é Ana, consultora de vendas da [SUA MARCA].

CONTEXTO:
- Produto: {{nome_produto}}
- Preço: R$ {{preco_produto}}
- Cliente: {{nome_cliente}} abandonou o carrinho

OBJETIVO:
Recuperar a venda sendo empática e consultiva

ABORDAGEM:
1. Cumprimente de forma amigável
2. Pergunte o motivo do abandono
3. Responda dúvidas com base nas informações do produto
4. Destaque os benefícios principais
5. Ofereça o cupom apenas se necessário: {{cupom}}
6. Envie o checkout: {{url_checkout}}

TOM:
- Seja natural e conversacional
- Evite linguagem robótica
- Use emojis moderadamente 😊
- Seja breve e direto

PROIBIDO:
- Ser insistente ou agressivo
- Enviar múltiplas mensagens seguidas
- Fazer promessas não cumprí veis

---

📞 Suporte

Precisa de ajuda? Entre em contato:

• 📧 Email: suporte@witerecuperation.com
• 💬 WhatsApp: (11) 98765-4321
• 🌐 Portal: https://painel.witerecuperation.com
• 📚 Documentação: https://docs.witerecuperation.com

---

Última atualização: Janeiro 2026
Versão: 1.0.0