Como funcionam as integrações de apps

A rota Integrações no painel concentra todas as conexões da sua conta: gateways de cobrança (PIX, cartão, boleto) e apps de terceiros — ferramentas de recuperação, comunicação, rastreio, área de membros e emissão de nota fiscal. Cada app aparece como um card com status Conectado, Configurado ou Não configurado.

Dois tipos de integração

API nativa — a CopyFunnel conversa diretamente com a API da ferramenta usando a credencial que você configura. É o caso de Utmify (postback de vendas), ActiveCampaign (contatos e tags) e Notazz (NFS-e).

Webhook de saída — a CopyFunnel envia um POST JSON para a URL que você informar, sempre que um evento acontece. É o modelo das ferramentas de recuperação e plataformas: Reportana, Wite Recuperation, HotBillet, Hotzapp, Único Drop, Sak, IntegraX, SmsFunnel, Notificações Inteligentes, Smart Funnel, Astron Members e Cademí. Você só precisa da URL do webhook (e, opcionalmente, de um segredo HMAC).

Eventos disparados

A CopyFunnel dispara até 5 eventos para os apps:

1. order.pending — pedido criado, aguardando pagamento (PIX/boleto).
2. order.completed — pedido pago (confirmado pelo gateway).
3. order.refunded — pedido reembolsado.
4. recovery.carrinho — carrinho abandonado: o comprador digitou o e-mail no checkout, mas não criou pedido.
5. recovery.boleto — pedido PIX/boleto pendente que entrou na esteira de recuperação.

Quem recebe o quê:

• Utmify — apenas order.pending, order.completed e order.refunded (recuperação não é venda).
• ActiveCampaign — order.completed e order.refunded.
• Notazz — apenas order.completed.
• Apps webhook (Reportana, Wite, HotBillet, Hotzapp, Único Drop, Sak, IntegraX, SmsFunnel, Notificações Inteligentes, Smart Funnel, Astron Members, Cademí) — todos os 5 eventos.

Os eventos recovery.* saem quando a recuperação nativa da CopyFunnel envia uma etapa (10 min, 5 h e 24 h) — a ferramenta externa recebe um push por pedido/sessão e roda a própria cadência, pausando quando recebe order.completed ou order.refunded.

Um envio por pedido (dedupe)

Cada evento é enviado no máximo uma vez por pedido para cada app, mesmo que o processo rode em mais de um lugar (webhook do gateway, polling, cron de recuperação). O controle é em banco: se outro processo já despachou aquele evento para aquele app, o envio é pulado automaticamente.

Formato do webhook

Apps webhook recebem um POST JSON com payload {event, data, sentAt}:

{
  "event": "order.completed",
  "data": { "orderId": "...", "status": "PAID", "amountCents": 29700, "buyerEmail": "...", "utm": { "utm_source": "instagram" } },
  "sentAt": "2026-01-01T12:00:00.000Z"
}

Headers: x-copyfunnel-event (nome do evento) e, se você configurar o segredo, x-copyfunnel-signature — HMAC-SHA256 (hex) do corpo cru, para o lado da ferramenta conferir que o POST veio da CopyFunnel.

Testar conexão

Todo app integrado tem o botão Testar conexão no drawer de credenciais. Ele faz uma validação real na ferramenta:

• Apps webhook — envia um POST sintético com event: "copyfunnel.test" na URL configurada; resposta 2xx valida.
• Utmify — envia um postback de teste (isTest: true, que não salva transação).
• ActiveCampaign — consulta o usuário autenticado (/api/3/users/me).
• Notazz — consulta notas existentes (consult_all_nfse).
• WhatsApp Cloud API — consulta o Phone Number ID no Graph API.

2xx marca a credencial como validada (status Conectado). Erro de rede não desvalida a credencial — você pode salvar e testar depois.

Segurança das credenciais

Segredos (tokens, API keys, segredo HMAC) são cifrados em repouso (AES-256-GCM) e nunca voltam para a tela — o drawer mostra apenas os últimos 4 dígitos. Deixar o campo secreto vazio ao salvar preserva o valor anterior. Campos de texto (URLs, tags, IDs) voltam normalmente para edição.

Falha de envio nunca derruba a venda

Todo envio para apps é fire-and-forget: se a ferramenta externa estiver fora do ar, demorar mais de 10 segundos ou recusar a chamada, nada acontece com o pedido — a venda é aprovada, o acesso é liberado e o reembolso processa normalmente. A falha fica só no log interno.