API de entrada de leads

Visão geral

Cada vez que um lead novo aparece no seu sistema, ele faz uma chamada para este endereço. A partir daí, o painel cuida do resto: junta pelo telefone com quem já existe, registra a origem e a base legal, manda a primeira mensagem pelo WhatsApp e coloca o cartão no Funil.

1. Seu sistema
3. Envia o lead
5. Junta pelo telefone
7. Primeiro contato
9. IA assume

Autenticação

Toda chamada leva a chave da integração no cabeçalho X-Api-Key. A chave começa com atld_ e é de uma integração só: cada sistema que manda leads tem a sua, e você pode pausar ou gerar outra sem mexer nas demais.

X-Api-Key: atld_SUA_CHAVE
Content-Type: application/json

• Por segurança, a chave completa aparece uma única vez, quando é criada. Depois o painel mostra só o começo e o fim.
• A chave de pedidos continua servindo só para pedidos. Para leads, use a chave da integração.
• Usa o painel de um parceiro? O endereço certo aparece em Integrações, no seu painel, já com o domínio dele.

Enviar leads

O corpo pode ser um lead solto, no formato que a maioria dos distribuidores já manda, ou uma lista em "leads" com até 100 leads. Os nomes dos campos são em inglês. Os valores da base legal podem ir em português (solicitaram, clientes, consentimento) ou em inglês (requested, customers, consent). As mensagens de volta vêm em português.

curl -X POST https://api.attendto.com.br/api/integrations/leads \
  -H "X-Api-Key: $CHAVE_DA_INTEGRACAO" \
  -H "Content-Type: application/json" \
  --data '{
    "external_id": "DL-88213",
    "name": "Camila Ribeiro",
    "phone": "(21) 98714-2290",
    "legal_basis": "solicitaram",
    "source": { "platform": "meta", "campaign_name": "Reserva Alcântara — Set/26" }
  }'

Campos do lead

Só o telefone e a base legal são indispensáveis. Todo o resto deixa o lead mais completo para a IA e para o seu time.

{
  "leads": [
    {
      "external_id": "DL-88213",
      "name": "Camila Ribeiro",
      "phone": "(21) 98714-2290",
      "email": "camila.ribeiro@exemplo.com",
      "legal_basis": "solicitaram",
      "consent": {
        "text": "Aceito receber contato da Imobiliária Horizonte sobre este imóvel.",
        "collected_at": "2026-09-24T20:56:41-03:00",
        "page_url": "https://www.horizonteimoveis.com.br/reserva-alcantara"
      },
      "source": {
        "platform": "meta",
        "campaign_id": "120214875530910001",
        "campaign_name": "Reserva Alcântara — Set/26",
        "adset_id": "120214875530910022",
        "adset_name": "Alcântara 28-45",
        "ad_id": "120214875530910347",
        "ad_name": "Vídeo tour 2 quartos",
        "form_id": "987650000000001",
        "form_name": "Reserva Alcântara — interesse",
        "meta_lead_id": "1234567890123456",
        "utm_source": "facebook",
        "utm_medium": "cpc",
        "utm_campaign": "reserva-alcantara-set",
        "utm_content": "video-tour-2q",
        "utm_term": null,
        "clicked_at": "2026-09-24T20:56:30-03:00"
      },
      "fields": {
        "tipo_de_imovel": "Apartamento 2 quartos",
        "faixa_de_valor": "Até R$ 300 mil",
        "usar_fgts": true
      },
      "tags": ["reserva alcântara"],
      "first_contact": true
    }
  ]
}

Origem do anúncio

Tudo dentro de source é opcional, mas é isso que dá nome de campanha de anúncio, conjunto e anúncio a cada lead no painel. Mande os IDs sempre como texto, entre aspas: número grande perde os últimos dígitos em muitos sistemas.

Base legal (LGPD)

Você é quem responde pelos dados dos seus leads; o painel trata esses dados em seu nome. Por isso, cada lead precisa dizer por que você pode falar com ele. A base que chega pela API fica registrada como declaração sua, com o nome de quem responde pela integração, a data e a hora.

• Sem base legal no lead e sem base padrão na integração, o lead é recusado, com o motivo na resposta.
• Quem pediu para não receber mensagens nunca volta a receber mensagem automática, mesmo que se cadastre de novo: a entrada volta como blocked, sem mensagem.
• Não mande CPF, RG, dados de saúde nem documentos em fields. Mande só o que ajuda a atender.

Primeiro contato automático

Com o primeiro contato ligado na integração, o lead recebe em segundos uma mensagem com um modelo aprovado do WhatsApp, assinada pela assistente da sua empresa. Quando ele responde, a IA assume a conversa e qualifica. O modelo, o horário e o custo por envio ficam no painel, na integração.

A mensagem não sai quando:

• alguém do seu time já está na conversa com essa pessoa;
• o lead já está conversando com a IA (não faz sentido gastar um modelo);
• a mesma pessoa já recebeu uma primeira mensagem nos últimos 30 dias, por qualquer integração;
• o número não é um celular do Brasil;
• a base legal do lead é clientes: mensagem automática de marketing pede o consentimento da pessoa;
• o seu time marcou o contato para não receber campanha;
• você mandou "first_contact": false.

Lead que chega fora do horário de envio da integração (padrão: das 8h às 21h, horário de Brasília) recebe a mensagem na próxima abertura. O motivo de cada decisão volta na resposta, em first_contact_reason, e aparece no registro de entradas do painel.

Resposta

Quando a chamada entra, a resposta é 200 com o resultado de cada lead, na mesma ordem em que foram enviados. Um lead com problema não derruba os outros.

{
  "received": 2,
  "created": 1,
  "updated": 1,
  "duplicates": 0,
  "rejected": 0,
  "items": [
    { "index": 0, "external_id": "DL-88213", "status": "created",
      "lead_id": "7f0c2a91-4d1e-4b0a-9c55-2e8f1d3a6b70",
      "first_contact": "scheduled" },
    { "index": 1, "external_id": "DL-88214", "status": "updated",
      "lead_id": "a91e5b30-77c2-4f18-8d0e-5c4b2a1f9e33",
      "first_contact": "skipped",
      "first_contact_reason": "O lead já está conversando com a IA." }
  ],
  "errors": []
}

Erros

Quando a chamada inteira não pode entrar, a resposta vem com o código HTTP e uma frase em detail, pronta para mostrar no log do seu sistema.

Motivos de recusa

Quando só um lead do lote tem problema, ele volta como rejected e o motivo aparece em errors, com o índice dele. Os outros entram normalmente.

Atualizar a etapa

Com a permissão Atualizar etapas ligada na integração (vem desligada), a mesma chave move o cartão do lead no quadro de destino da integração, ou no quadro padrão quando ela não tem destino. A etapa é o Nome na API da coluna, que não muda quando alguém renomeia a coluna. Liste as etapas de um quadro em GET /api/integrations/boards/{board_id}/stages.

{
  "external_id": "CRM-48213",
  "stage": "pasta",
  "fields": {
    "valor_imovel": 450000,
    "tipo_financiamento": "Financiamento bancário"
  }
}

A resposta traz status: moved quando o cartão mudou de etapa, ou unchanged quando ele já estava nela. Mandar a mesma etapa de novo não move o cartão nem repete os avisos dos webhooks; campos diferentes em fields são gravados, com o histórico de cada um.

[
  { "key": "novo", "name": "Novo", "role": "entrada" },
  { "key": "qualificado", "name": "Qualificado", "role": "qualificado" },
  { "key": "visita", "name": "Visita", "role": "intermediaria" },
  { "key": "pasta", "name": "Pasta", "role": "intermediaria" },
  { "key": "venda", "name": "Venda", "role": "ganho" },
  { "key": "perdido", "name": "Perdido", "role": "perdido" }
]

Repetidos e reenvio

Na dúvida, reenvie. O painel reconhece o que já recebeu e não cria lead, nem manda mensagem, nem cobra de novo.

• Com external_id: o mesmo ID na mesma integração volta como duplicate, com o mesmo lead_id, a qualquer momento.
• Sem external_id: o mesmo telefone na mesma integração em até 10 minutos também volta como duplicate. Cobre o reenvio automático por tempo esgotado.
• Quando reenviar: em 429, espere o tempo de Retry-After. Em erro do servidor ou queda de rede, tente de novo com espera crescente, por exemplo 2 s, 10 s e 1 min.
• Não reenvie os itens que voltaram como rejected sem corrigir: eles voltam recusados de novo.

Limites

O limite de 1 MB vale antes de tudo: um lote de 100 leads com muitos campos pode passar dele, e aí é melhor dividir em requisições menores. Cada requisição tem até 25 s; o lead que não couber volta com “Tempo da requisição esgotado” e pode ser reenviado sem duplicar.

Receber leads pela API não tem custo. O que tem custo é a primeira mensagem por modelo, quando ligada, e o valor aparece no painel antes de você ligar.

Formato do seu sistema

O seu distribuidor manda um JSON próprio e não dá para mudar? No painel, em Receber no formato do seu sistema, cole um exemplo real e ligue cada campo ao nosso. A integração passa a aceitar esse formato, um lead por chamada.

Campo que não vier fica vazio. Se faltar o telefone, o lead é recusado com o motivo “Telefone não encontrado em contato.celular”.

Depois que o lead entra