ScalaCRM

Cadastrar leads via API (landing page, Lead Ads, n8n)

Envie leads de fora para o CRM por uma requisição HTTP — com nome, telefone, UTMs, identificadores de clique do anúncio e campos personalizados.

Quando um lead nasce fora do WhatsApp — um formulário de landing page, um Lead Ads passando pelo Make/n8n, ou um sistema seu — você pode cadastrá-lo no CRM com uma requisição HTTP simples. O lead entra na base, ganha (se quiser) um card na entrada do funil, e pode carregar a origem completa do anúncio: UTMs, o identificador do formulário do Lead Ads e os identificadores de clique que fazem a Meta e o Google reconhecerem a conversão.

O que você precisa antes

1. O secret da integração. Em Configurações → Integrações, no card Integração com n8n, copie o secret. Ele é o token de autenticação (Authorization: Bearer <secret>). O recurso está disponível em todos os planos pagos.

2. Os campos personalizados criados no CRM (só se você for usar custom_fields). A API só preenche campos que já existem. Em Configurações → Preferências → Campos personalizados, crie o campo (entidade Contato) e anote o key que aparece embaixo do nome.

  • Exemplos: um campo chamado CNPJ vira o key cnpj; Nome da Empresa vira nome_da_empresa.
  • Chave que não existe é ignorada (a API não cria campo sozinha — é de propósito, para não poluir a base com campos ad-hoc).
  • Para dados que vêm só de integração e que o atendente não deve editar, marque o campo como "apenas API" ao criar. Ele fica somente-leitura e só aparece no contato que recebeu o dado.

A requisição

POST https://www.scalacrm.com/api/integrations/contacts
Authorization: Bearer SEU_SECRET
Content-Type: application/json

{
  "name": "João Silva",
  "phone": "5566999998888",
  "email": "joao@exemplo.com",
  "utm": { "source": "google", "medium": "cpc", "campaign": "black-friday" },
  "click_ids": {
    "gclid": "Cj0KCQiA...",
    "fbclid": "IwAR2xY..."
  },
  "create_funnel_card": true,
  "note": "Veio da landing de setembro",
  "custom_fields": {
    "cnpj": "12.345.678/0001-90"
  }
}

Campo a campo:

  • name (obrigatório) — nome do lead.
  • phone (obrigatório) — DDI + DDD + número (ex.: 5566999998888). O CRM aplica a regra do 9º dígito e não duplica: se o telefone já existir, o lead é atualizado em vez de recriado.
  • email (opcional).
  • utm (opcional) — source, medium, campaign, term, content.
  • click_ids (opcional) — fbclid, gclid, gbraid, wbraid. Ver a seção abaixo: é o que separa atribuição exata de atribuição por estimativa.
  • lead_ads (opcional) — para leads do formulário nativo da Meta. Ver a seção própria.
  • create_funnel_card (opcional, padrão true) — já cria o card na etapa de entrada do funil. É o gancho para a abordagem ativa do agente: lead novo na entrada + agente com prospecção ligada = o agente manda a 1ª mensagem sozinho.
  • note (opcional) — nota interna no contato (só na criação; reenvio não duplica).
  • custom_fields (opcional) — objeto { "key": valor }, com o key do campo já criado no CRM.

Identificadores de clique (click_ids) — o que muda de verdade

Sem eles, a Meta e o Google tentam adivinhar de qual anúncio o lead veio comparando o telefone com a base deles. Funciona às vezes. Com eles, a plataforma sabe exatamente qual clique gerou aquele lead — e a otimização da campanha melhora porque o retorno para o algoritmo passa a ser confiável.

Os quatro que o CRM reconhece são os que aparecem na URL da sua landing page quando o visitante chega de um anúncio:

ParâmetroDe onde vem
gclidGoogle Ads (o caso normal)
gbraidGoogle Ads em iPhone/iPad, tráfego de aplicativo
wbraidGoogle Ads em iPhone/iPad, tráfego web
fbclidMeta (Facebook e Instagram)

Mande o valor exatamente como veio na URL, sem alterar nada. O CRM faz a conversão para o formato de cada plataforma na hora do envio — no caso da Meta, o formato exigido inclui o horário de chegada do lead, e por isso a montagem precisa acontecer do lado de cá.

Como pegar no seu formulário: leia a query string da página no momento em que o formulário é enviado. Em JavaScript, new URLSearchParams(location.search).get("gclid"). Se você usa n8n/Make no meio, é só repassar os campos.

Se o lead chegar com um click ID, o CRM marca a origem dele como Anúncio automaticamente — você não precisa de nenhuma automação extra para isso. O mesmo vale para UTMs. É o que faz o lead aparecer no filtro "De anúncio" da lista de contatos e nos relatórios por origem.

Chave que o CRM não reconhece (ttclid, msclkid, dclid…) volta listada em ignored_fields em vez de sumir calada. Se aparecer ali, é porque ainda não é suportada.

Leads do formulário da Meta (lead_ads)

Se o lead veio do formulário nativo do Facebook/Instagram (Lead Ads), mande o leadgen_id — é o identificador mais forte que existe para esse caso, mais forte até que o telefone:

{
  "name": "Maria Souza",
  "phone": "5566988887777",
  "lead_ads": {
    "leadgen_id": "9911223344556677",
    "form_id": "1234567890",
    "ad_name": "Campanha Setembro — Criativo A",
    "campaign_name": "Setembro | Leads"
  }
}

Com ele, a Meta reconhece o evento como Conversion Leads e o atribui de volta ao envio daquele formulário específico. Só o leadgen_id é obrigatório dentro do bloco; o resto ajuda a leitura no CRM.

Se o lead já mandou mensagem antes

Acontece o tempo todo em landing page: a pessoa preenche o formulário, é redirecionada ao WhatsApp e manda mensagem em segundos — a mensagem chega antes do seu webhook.

Você não precisa de um verificador no seu fluxo. O endpoint faz upsert pelo telefone: se o contato já existe, ele é atualizado, e a origem é promovida para Anúncio automaticamente quando chega UTM, click ID ou lead_ads num contato que estava marcado como WhatsApp ou Instagram. A ordem de chegada é acidente de tempo, não informação de negócio.

O que ele não faz: sobrescrever uma origem que alguém registrou de propósito. Contato marcado como Importado ou Manual fica como está.

A resposta

{
  "ok": true,
  "contact_id": "3f2a…",
  "created": true,
  "ignored_fields": ["campo_que_nao_existe", "click_ids.ttclid"]
}
  • created — true se o contato é novo; false se já existia (foi atualizado).
  • ignored_fields — chaves que você mandou e o CRM não usou: campo personalizado que não existe, ou uma chave desconhecida dentro de utm/click_ids/lead_ads. Vale conferir sempre: um dado descartado em silêncio só apareceria semanas depois, num Gerenciador de Eventos vazio.

O contato cadastrado por aqui ganha o selo "API" no detalhe, para a equipe saber que veio de uma integração. Os identificadores de clique aparecem no painel Origem do lead, no inbox e no detalhe do contato.

Para a conversão realmente sair

Capturar o identificador é metade do caminho — a outra metade é a conta estar conectada:

  • Meta: configure as conversões offline em Configurações → Integrações (Dataset ID + token). Sem isso, nada é enviado.
  • Google: configure o Google Ads em Configurações → Integrações (Customer ID + as ações de conversão).

Sem essas configurações o lead entra normal no CRM, com a origem certa — só não vira evento na plataforma de anúncio.

Erros comuns

  • 401 / "Segredo inválido" — o Authorization: Bearer está errado ou o secret foi regenerado. Copie de novo em Configurações → Integrações.
  • 403 / "não está inclusa no plano" — a API de integrações exige um plano com a integração liberada. Está inclusa em todos os planos pagos e no teste gratuito de 14 dias; o 403 aparece quando a conta está suspensa ou com o recurso bloqueado por configuração.
  • 422 / "Telefone inválido" — mande no formato DDI+DDD+número, só dígitos.
  • 429 — muitas requisições no mesmo minuto. Espere o tempo indicado em Retry-After e reenvie.
  • Campo não aparece no contato — o key não bate com nenhum campo criado (veja ignored_fields), ou o campo é "apenas API" e o contato ainda não recebeu valor.
  • O lead entrou mas não virou conversão — confira se a conta tem a conversão configurada (seção acima) e se o click ID chegou (aparece no painel Origem do lead).

Veja também