Conversões externas

O que isso resolve

O ciclo comercial do Brodalink é Campanha → Link/QR → acesso → lead → conversão/resultado. Quando o fechamento acontece fora do Form nativo, a API de conversões externas registra o resultado no mesmo eixo — sem inventar integração nativa com CRMs específicos.

• Credencial dedicada da conta
• Idempotência
• Atribuição opcional
• Lista em Conversões

1. Quando usar

Use quando a ação desejada (venda, contrato, status comercial) acontece em outro sistema, mas você quer ver o resultado no Brodalink ligado à origem da divulgação quando o contexto existir.

• Lead entrou pela campanha; fechamento no CRM ou processo externo
• Sistema próprio precisa notificar o Brodalink
• Não substituir a conversão nativa de Form quando o Form já resolve

2. Como gerar a credencial

No app: Conversões → Conversões externas → Criar credencial. O valor completo aparece só na criação/regeneração. Depois só o prefixo fica visível. Revogue ou regenere quando precisar.

• Credencial account-scoped (não use JWT de login)
• Segredo gerado no servidor e armazenado como hash
• Revogação invalida o valor anterior imediatamente

3. Autenticação e endpoint

Envie o segredo no header X-Brodalink-Webhook-Secret. Endpoint de máquina: POST /webhooks/inbound/conversions. Assinatura HMAC (X-Brodalink-Signature + X-Brodalink-Timestamp) é opcional, mas recomendada em produção.

• Não reutilize sessão/JWT de usuário como API key persistente
• Rate limit por IP no caminho inbound
• Contas Free recebem bloqueio (plano Pro+)

4. Payload

Campos principais do body JSON:

• idempotencyKey (obrigatório) — mesma chave → mesma conversão (sem duplicar)
• type — use "custom"
• occurredAt — opcional (ISO-8601)
• externalReference — opcional (id no seu sistema)
• valueCents / currency — opcional
• metadata — objeto JSON opcional
• clickEventId — opcional; se presente, atribuição vem do clique (mesma conta)
• campaignId / linkId — opcionais só sem clickEventId; validados na conta

5. Atribuição

Com clickEventId válido da mesma conta, campanha/link/UTMs são copiados do clique. Sem clickEventId, você pode informar campaignId/linkId da conta. Sem contexto, a conversão é registrada sem origem inventada.

• Não inventamos atribuição a partir só de UTMs ou externalReference
• Conversão sem contexto ainda aparece em Conversões (tipo customizado)

6. Respostas e erros

201 na primeira gravação; 200 em replay idempotente. Erros comuns: 401 segredo inválido/revogado; 403 plano/flag; 400 payload inválido; 429 rate limit.

• Segredo nunca retorna de novo no GET de status
• Segredo nunca deve aparecer em logs seus ou nossos

7. Segurança

Trate a credencial como senha de sistema. Rotacione após vazamento. Revogue credenciais antigas. Prefira HTTPS e assinatura HMAC.

• Isolamento por conta
• Hash no armazenamento
• Kill switch V2_FLAG_EXTERNAL_CONVERSION=false

8. Plano necessário

Pro, Business e Premium. Free não inclui. Não há cota artificial extra nesta etapa além do entitlement de conversões do plano.

• Mesmo eixo comercial de Forms / Conversões