Integration Hub — canais de entrada de leads

Objetivo

Toda organização conecta os próprios canais de entrada em minutos e responde, numa tela, "de onde seus leads chegam?". Cada canal que entra vira um lead na Radhr AI com identidade única (a mesma pessoa pelo WhatsApp e pelo formulário é um lead só), dono decidido pelas regras de roteamento, origem rastreada (canal, campanha, UTMs, página) e o rastro operacional (eventos de integração sem segredos). Fazem parte do hub três produtos do próprio Radar — Radhr Forms, Radhr Chat Widget e o Developer Hub (chaves de API e webhooks de saída) — e o marketplace de provedores por categoria e fase. O desenho completo está em docs/radar/integration-hub.md.

Fluxo

Conectar (/radar/integracoes → cartão do provedor): o admin informa nome, credenciais (cifradas com AES-GCM; a tela mostra só os quatro últimos caracteres) e configuração; a integração nasce conectada com um token de webhook (a URL de entrada) e, nos provedores da Meta, o token de verificação (hub.verify_token). "Testar" faz um ping no provedor; "Desconectar" apaga as credenciais e mantém o histórico.
Receber: o provedor chama POST /api/webhooks/<provedor>/<token> (Meta: WhatsApp, Lead Ads, Instagram, Messenger; Typeform; Tally; Google Ads; 360Dialog; Evolution) ou POST /api/entrada/<token> (JSON de qualquer origem: Zapier, Make, n8n, Google Forms via Apps Script, LinkedIn, TikTok, e-mail de entrada). O token diz a organização; a assinatura é conferida quando o provedor assina. Com a fila da Cloudflare ligada, o payload é guardado na fila (webhook_entrada, 3 entregas) antes do 200 ao provedor; sem fila — ou se a fila recusar o envio — o processamento roda antes da resposta e uma falha vira 500 para o provedor retentar (no Lead Ads, erro 5xx/429 do Graph também relança; 4xx pula o item) — nos dois casos nada se perde depois de um 200. Processamento: parser do provedor → mapeamento de campos da conexão → pipeline.
Pipeline (receberLead): chaves de identidade (e-mail, documento, telefone, WhatsApp, redes, id externo) → acha o lead (ou cria) → mescla só os campos vazios → toque em lead_fontes (o primeiro define canal e campanha do lead) → roteamento (regras; sem regra, a Vertical) → log em integracao_eventos → webhooks de saída → próxima ação da IA. Mensagens (WhatsApp, DM) viram evento na linha do tempo; no modo ia/hibrido do WhatsApp a primeira mensagem de um lead novo recebe a saudação da organização pelo provedor.
Radhr Forms: o admin monta o formulário (campos, mapeamento para o lead, entrega: link, embed, popup ou landing page); o visitante envia em /f/<código> com consentimento; o lead entra pelo pipeline com canal formulario (ou landing_page) e campanha das UTMs; respostas que não mapeiam campo viram formulario_respondido.
Chat Widget: <script src="…/widget/<token>.js"> no site da organização abre o chat na marca dela; o modo ia usa o Agente SDR (/api/chat?chave=), o humano o formulário curto (/api/contato?chave=), o hibrido os dois.
Developer Hub: chaves rk_live_… (só o hash fica no banco; escopos leads:ler, leads:escrever, webhooks:ler; limite por minuto; validade; revogação; logs) para POST/GET /api/v1/leads; webhooks de saída (lead_criado, lead_atualizado, cliente_criado, contrato_criado, escopo_criado) sempre assinados com HMAC (segredo que não decifra = falha, nada sai sem assinatura), com retentativas de prazos 1 min, 5, 30, 2 h e 12 h processadas pelo cron horário (cada tentativa sai na primeira rodada depois do prazo; a 6ª falha desiste) e pausa após 10 falhas seguidas.
Operação: cron diário confere tokens a vencer (7 dias → atenção; vencido → erro); erros seguidos mudam o status (1–2 atenção, 3+ erro); o alerta 9 avisa a Witbiz de integração em erro há mais de 1 h e de webhook pausado.

Regras de negócio

Nunca dois leads para a mesma pessoa: a identidade decide (e-mail > documento > telefone > WhatsApp > redes > id externo, este único por provedor: typeform:abc e tally:abc são pessoas diferentes); a mesclagem só preenche campos vazios e nunca sobrescreve; lead perdido que volta reabre em triagem. Uma chave que já é de outro lead nunca muda de dono (fica como identidade_conflito no log). Duas entregas simultâneas da mesma pessoa ou da mesma referência: a que perde desfaz o lead que acabou de criar e segue no vencedor.
A mesma referência do provedor (id da mensagem/lead/resposta) entra uma vez só por organização e provedor.
A organização de uma rota pública vem do token/código do link, nunca do domínio.
Credenciais cifradas e nunca devolvidas às telas; erros gravados sem segredos; logs sem payload bruto. Credenciais gravadas que não decifram (chave de cifra trocada) fecham a porta: o webhook responde 503 e a integração vai para atenção — nunca "sem assinatura"; para salvar de novo é preciso informar todas as credenciais obrigatórias do provedor. A chave de API e o segredo do webhook aparecem uma vez, na resposta do próprio POST, nunca numa URL.
Lead com dono não muda de dono pelo roteamento; a primeira regra ativa que casa decide; destino inválido cai na próxima; sem regra, a Vertical (ambíguo → Tech).
O canal legado continua: chat do site, formulário curto, WhatsApp dos segredos da Witbiz, cadastro manual e indicação de parceiro criam leads como antes e registram só o toque.
Sem a migração 0043 nada quebra: as telas explicam e os canais antigos seguem; os passos novos falham em silêncio.
Provedores P3 (HubSpot, RD Station, Pipedrive, Salesforce) aparecem como "em breve", sem conexão.
Webhooks de saída só para https público; segredo mostrado uma vez.
Uploads dos Radhr Forms vão ao R2 sob formularios/<organização>/… só depois de o envio passar (robô ou envio inválido não deixa objeto órfão); a chave fica no evento e o download (/radar/integracoes/arquivo?chave=) só aceita chaves da própria organização; sem R2 o lead entra e o evento diz que o arquivo não foi guardado.

Casos de uso

Agência liga o WhatsApp oficial: conecta a Meta Cloud API, cola a URL e o token de verificação no app da Meta, manda um "oi" do celular e vê o lead nascer com a mensagem na linha do tempo e o dono pelo round robin.
Campanha de Lead Ads no Instagram: conecta Meta Lead Ads com o token da página; cada lead chega com campanha, conjunto e anúncio — e aparece no Lead Source Intelligence com a receita atribuída.
Formulário no site antigo: cria um Radar Form, cola o script de embed; o lead entra com a UTM da campanha.
Zap de uma planilha: conecta "Webhook de entrada", cola um exemplo de linha, "Sugerir pelo exemplo", salva.
Sistema próprio: gera uma chave no Developer Hub e chama POST /api/v1/leads com id_externo (idempotente).
Avisar o ERP quando fechar contrato: cadastra um webhook de saída para contrato_criado.

Telas

/radar/integracoes: "De onde seus leads chegam?", dashboard (leads hoje, por canal, conversão, origem dos clientes, canal mais performático, tempo de resposta), atalhos, cartões por grupo com status.
/radar/integracoes/marketplace?categoria=: catálogo por categoria e fase.
/radar/integracoes/<provedor>[/<id>]: status, o que faz, conexão, URL de entrada e token de verificação, mapeamento visual (campo da Radhr AI → caminho no payload, sugestão pelo exemplo).
/radar/integracoes/formularios[/<id>], /radar/integracoes/widget, /radar/integracoes/roteamento, /radar/integracoes/desenvolvedor, /radar/integracoes/logs?integracao=, /radar/integracoes/arquivo?chave= (download de upload de formulário).
Públicas: /f/<código> (+ .js), /widget/<token> (+ .js), /api/webhooks/<provedor>/<token>, /api/entrada/<token>, /api/v1/*, /api/v1/openapi.json, /integration-hub (atalho).
Trilho: item "Integrações" no grupo Organização.

Permissões

integracoes.ler (todo papel); integracoes.conectar (owner, admin); integracoes.formularios (owner, admin); integracoes.roteamento (owner, admin, manager); integracoes.desenvolvedor (owner, admin). Nos papéis legados, leitura e financeiro só consultam.
Flags: integration_hub (todos os planos pagos, interno e teste); developer_hub (Profissional em diante).
Públicas: assinatura do provedor + token; formulários limitados por IP (LIMITES_PUBLICOS.formulario_envio); API limitada por chave e minuto.

Perguntas frequentes

Onde vejo por que um lead não entrou? Em Logs (/radar/integracoes/logs): descartado (sem e-mail, telefone, documento ou id), duplicado (referência repetida), erro (assinatura ou provedor).
O token da Meta vence? O da Meta Cloud API com usuário de sistema é permanente; preencha "Token vence em" quando usar token temporário — o cron avisa 7 dias antes.
A IA responde no WhatsApp? No modo ia/hibrido ela manda a saudação e deixa a próxima ação com o rascunho; a conversa completa do SDR por WhatsApp chega na sprint 2.
Posso ter dois números? Sim: cada conexão tem o próprio token e mapeamento (/radar/integracoes/<provedor>?nova=1).
Como rotacionar a chave de cifra? Troque INTEGRACOES_CHAVE e peça às organizações que salvem as credenciais de novo (a versão da chave fica na linha); sem o segredo, a cifra deriva do SESSION_SECRET.