Receber leads de formulários de anúncio

Os formulários nativos de anúncio da Meta (Facebook e Instagram) e do Google Ads entregam os leads direto à owiew. Os leads ficam guardados cifrados na caixa de leads do projeto e podem seguir para um CRM conectado.

Você não implementa nada nos seus sistemas. Você conecta a plataforma pelo painel, e a plataforma chama as rotas de recepção da owiew. Esta página descreve o que cada conexão exige e o contrato do endpoint que o Google Ads chama.

O que você precisa

• Ser administrador do projeto na owiew.
• Acesso de administração à conta de anúncios (Google Ads) ou à Página (Meta).
• Para o CRM de destino, a chave de API do CRM (Asender, Kommo ou RD Station).

Plataformas disponíveis

Plataforma	Situação	Como conecta
Meta (Facebook e Instagram)	Disponível	Autorização na Meta pelo painel.
Google Ads	Disponível	Endereço de recepção e chave, que você cola no Google Ads.
LinkedIn	Em breve	Aparece no painel como “Em breve”.
TikTok	Em breve	Aparece no painel como “Em breve”.

Conectar a Meta

1. No painel, abra as configurações de Leads e clique em Conectar na Meta.
2. Você será levado à Meta para autorizar o acesso às Páginas.
3. De volta ao painel, escolha quais Páginas entregam leads.

A Meta avisa a owiew de cada lead novo com uma notificação assinada que traz só identificadores, sem dados pessoais. A owiew então busca o lead na Meta com a autorização da Página, normaliza, cifra e grava. A Meta reenvia a notificação por até 36 horas se necessário, e a owiew deduplica pelo identificador do lead.

O botão Buscar leads perdidos refaz a busca de leads que não chegaram. A autorização da Meta tem validade: o painel mostra a data e avisa antes de vencer. Reautorize antes disso para não perder leads.

Conectar o Google Ads

1. Em Leads, clique em Conectar no Google Ads e depois em Gerar chave do Google Ads.
2. O painel mostra o Endereço de recepção e a Chave. A chave aparece só desta vez e não pode ser consultada depois. Guarde-a.
3. No Google Ads, abra as configurações de entrega do formulário de lead e cole o endereço e a chave.

O Google Ads não permite buscar leads antigos: só os novos chegam.

Endpoint de recepção do Google

POST /v1/recepcao/google/{conexao_id}
Content-Type: application/json

O conexao_id identifica a conexão e já vem no endereço exibido pelo painel. Não há sessão nem chave de API: a prova de origem é a google_key no corpo, comparada em tempo constante com a chave da conexão. O cliente da owiew é determinado pela conexão, nunca por algo que você envie.

Corpo (formato do Google Ads):

Campo	Tipo	Obrigatório	Descrição
lead_id	string, até 256	sim	Id do lead. Base da deduplicação.
user_column_data	lista, até 100 itens	sim	Respostas do formulário: column_id, column_name, string_value.
google_key	string, até 256	sim	A chave da conexão.
api_version, form_id, campaign_id, adgroup_id, creative_id, gcl_id	vários	não	Metadados do anúncio.
is_test	booleano	não	Marca lead de teste.

Exemplo, com dados inventados:

curl -i -X POST "$OWIEW_LEAD_URL" \
  -H "Content-Type: application/json" \
  -d '{
    "lead_id": "lead-exemplo-0001",
    "form_id": 1,
    "campaign_id": 1,
    "is_test": true,
    "google_key": "'"$OWIEW_LEAD_CHAVE"'",
    "user_column_data": [
      { "column_id": "FULL_NAME", "column_name": "Nome", "string_value": "Pessoa Exemplo" },
      { "column_id": "EMAIL", "column_name": "E-mail", "string_value": "pessoa@exemplo.invalid" }
    ]
  }'

$OWIEW_LEAD_URL é o endereço de recepção exibido pelo painel e $OWIEW_LEAD_CHAVE é a chave.

Resposta

HTTP/1.1 200 OK
Content-Type: application/json

{}

O corpo {} é exigido pelo Google. O lead é cifrado antes de ser gravado e nunca existe em claro em disco, em log ou em fila.

Erros

Os erros trazem { "error": { "code", "message", "trace_id" } }.

Status	Código	Quando
400	CORPO_INVALIDO	JSON malformado ou campo desconhecido. O Google não reenvia respostas 4xx.
401, 403 ou 404	resposta uniforme	Chave inválida, conexão inexistente ou de outro cliente. A resposta é a mesma nos três casos, para não revelar o que existe.
413	CORPO_GRANDE_DEMAIS	Corpo acima de 256 KB.
429	RATE_LIMITED	Muitas falhas por IP ou por rota e IP. Há Retry-After.
503	INDISPONIVEL	Falha temporária de armazenamento. O Google reenvia respostas 5xx.

Anti-spam e proteção

• Cada rota conta as falhas por IP e por rota e IP antes de ler o corpo, e responde 429 ao exceder.
• Credencial inválida gasta o limite de falhas do IP e recebe resposta uniforme.
• O corpo e o cabeçalho de assinatura nunca são registrados em log.
• Entrada hostil não produz 500.
• Cada lead é deduplicado pelo seu identificador (lead_id no Google, identificador do lead na Meta).
• Quando o módulo de leads está desligado ou a página da Meta é desconhecida, a recepção aceita e descarta, sem revelar o motivo.

Depois que o lead chega

• A caixa de leads lista os leads. Os dados aparecem mascarados e só são revelados por ação explícita, que fica registrada em trilha de acesso.
• Em Para onde os leads vão, conecte um CRM (Asender, Kommo ou RD Station) com a chave de API dele. Se o envio falhar, o lead fica guardado e o envio é tentado de novo. Em estado Pausado, os leads ficam guardados sem envio.
• Em Retenção, defina por quantos dias guardar os leads. Reduzir o prazo apaga leads imediatamente e pede confirmação de identidade.

Teste ponta a ponta

1. Conecte o Google Ads e gere a chave.
2. Envie o curl acima, com is_test verdadeiro.
3. Espere a resposta 200 com {}.
4. Abra a caixa de leads e confirme que o lead de teste apareceu. Na conexão, Último lead deve mostrar o horário.
5. Envie o mesmo curl de novo: a caixa não deve ganhar um segundo lead.
6. Para a Meta, use a ferramenta de teste de leads da própria Meta e confira a caixa.

Se algo der errado

Sintoma	Causa provável
401, 403 ou 404 no teste	Chave errada, ou endereço de outra conexão. Se perdeu a chave, gere outra.
429	Várias tentativas com chave errada vindas do mesmo IP. Aguarde o Retry-After.
Conexão Meta sem leads	Autorização vencida ou Página não selecionada. Reautorize e escolha as Páginas.
“Nenhum lead recebido ainda”	Nenhum lead chegou desde a conexão. O Google não busca leads antigos.
Lead na caixa, mas não no CRM	Destino pausado, credencial inválida ou falha temporária do CRM. O envio é tentado de novo.

Próximos passos

• Visão geral das integrações
• Receber conversões por webhook
• Instalar o pixel