Leads — a porta de entrada

Endpoint pensado para formulário de site, landing page e ferramenta de captação: cria contato (e negócio, se você quiser) numa chamada só, com proteção contr…

Endpoint pensado para formulário de site, landing page e ferramenta de captação: cria contato (e negócio, se você quiser) numa chamada só, com proteção contra duplicidade embutida.

Escopo: leads:write · Método: POST/api/leads

{
  "external_ref": "site-form-8412",
  "source": "landing-page-plano-pro",
  "tags": ["7c1e4b7a-2d5c-4f8e-8b3a-6c9d2e5f1a73"],
  "owner_id": "1b7c9d2e-5f3a-4e8b-9c1d-2a6f4b8e3d57",
  "contact": {
    "name": "Maria Souza",
    "email": "maria@exemplo.com.br",
    "phone": "+55 11 97777-0002"
  },
  "deal": {
    "name": "Plano Pro — Maria Souza",
    "value": 5900,
    "company_name": "Souza Consultoria",
    "funnel_id": "c3d5e7f9-1a2b-4c6d-8e0f-3a5b7c9d1e2f",
    "column_id": "e1f3a5b7-9c2d-4e6f-8a0b-1c3d5e7f9a2b",
    "expected_close_date": "2026-09-30",
    "notes": "Veio do formulário de captação",
    "external_id": "crm-legado-lead-482",
    "extra_contact_ids": ["9f1e4b7a-2d5c-4f8e-8b3a-6c9d2e5f1a73"]
  },
  "utm": {
    "utm_source": "google",
    "utm_medium": "cpc",
    "utm_campaign": "plano-pro-agosto",
    "gclid": "Cj0KCQjw..."
  }
}
Campo Obrigatório Regras
external_ref sim 1–200. O identificador da submissão no seu sistema. É o que impede duplicidade
source não até 100. Aparece no CRM como origem do lead — precisa casar (sem acento/caixa) com uma origem já cadastrada em Configurações → Negócios → Origens; se não casar, 400
tags não até 20 ids de tag. Cada uma precisa existir na conta e se aplicar a contato ou a negócio — senão 400 e nada é gravado. A tag é aplicada no contato se servir pra contato, e no negócio se servir pra negócio
owner_id não pessoa ativa da equipe. É o responsável do negócio criado. No contato, só vale se ele for novo ou ainda não tiver dono — um contato que já tem dono nunca troca de dono por causa de um lead
contact.name sim 1–120
contact.email / contact.phone um dos dois e-mail válido (até 200) · telefone até 40. ⛔ Só name, sem e-mail nem telefone, é 400 — sem um identificador a mesma pessoa vira um contato novo a cada submissão
contact.title / contact.department / contact.city / contact.state não até 120 cada. Cargo, setor, cidade e estado da ficha do contato — gravados na criação do lead, sem precisar de um PATCH depois
deal não se presente, cria um negócio junto
deal.name sim, se houver deal 1–200
deal.value não ≥ 0
deal.stage não padrão new. Se você mandar deal.column_id (ou deal.funnel_id), o stage é derivado da coluna e o que você pediu aqui é ignorado — mesma regra do PATCH de negócio (seção 9). Mandar column_id de uma coluna de Ganho com stage: "new" grava Ganho, não new
deal.company_id não empresa existente
deal.company_name não até 200 — cria ou reaproveita empresa com esse nome
deal.company_cnpj / company_segment / company_phone / company_email não só valem quando a empresa é criada nesta chamada — nunca sobrescrevem uma empresa já existente
deal.funnel_id / deal.column_id não funil e etapa de destino. Se os dois vierem, a coluna precisa pertencer àquele funil
deal.expected_close_date não AAAA-MM-DD
deal.lost_reason / deal.loss_reason_id não texto livre ou FK do catálogo (§9.3) — XOR, os dois juntos é 400
deal.notes não até 5000
deal.external_id não até 255 — ver §27
deal.extra_contact_ids não ≤ 200 ids de contato adicionais a vincular no negócio, além do contato principal do lead (que já vincula sempre). Um id de outra conta recusa a chamada INTEIRA — nem o contato principal chega a ser gravado
custom_fields não ⛔ na raiz do corpo, NÃO dentro de deal — {"<key ou uuid>": valor}, ver §28. Os valores vão para o negócio, então exige deal: sem negócio no corpo, é 400
utm não rastreio de campanha, gravado no negócio. Exige deal — sem negócio, não há onde pendurar o rastreio. Aceita só estas chaves, todas texto até 200: utm_source, utm_medium, utm_campaign, utm_term, utm_content, gclid, fbclid — ⛔ gclid e fbclid vão dentro de utm, nunca na raiz. Qualquer outra chave é 400 unknown_field

Como a empresa do negócio é resolvida (no Salos, negócio sempre pertence a uma empresa): usa deal.company_id se veio; senão cria ou reaproveita uma empresa com deal.company_name (ignorando maiúsculas); senão cria uma com o nome do contato.

Quem fica responsável pelo negócio novo, nesta ordem — o primeiro que existir e for pessoa ativa da equipe vence:

  1. o owner_id que você mandou;
  2. o dono do contato (quando o lead caiu num contato que já existia e já tinha dono);
  3. o dono da empresa do negócio (ou, sem ela, da empresa do contato);
  4. ninguém — o negócio nasce sem responsável.

É a carteira de clientes: um cliente que já é de um vendedor volta para o mesmo vendedor, sem você precisar saber quem é.

Mesmo lead chegando duas vezes: o negócio aberto recente recebe

Se o contato do lead já tem um negócio aberto no funil de destino (o deal.funnel_id informado, ou o funil padrão da conta) criado nos últimos 30 minutos, o lead entra nesse negócio em vez de abrir outro — é o caso do formulário e do WhatsApp do mesmo anúncio chegando quase juntos. Nesse caso:

  • deal_id na resposta é o do negócio que já existia;
  • nada do negócio existente é sobrescrito — rastreio (utm), custom_fields, empresa e external_id só preenchem o que estiver vazio;
  • o webhook deal.created não sai (o negócio não é novo).

Negócio aberto mais antigo que isso não recebe o lead: nasce um negócio novo, pra um pedido novo nunca sumir dentro de um card velho. Negócio ganho ou perdido nunca é reaberto, e um lead que já chega com deal.stage won ou lost sempre cria o seu.

Respostas

Código Significado
201 Lead novo processado. created pode vir false aqui — veja abaixo
200 Esse external_ref já foi processado antes. Devolve o mesmo resultado com "created": false. Nada é duplicado
409 O mesmo external_ref está sendo processado neste instante por outra chamada. Aguarde e reenvie
{
  "data": {
    "external_ref": "site-form-8412",
    "created": true,
    "contact_id": "9f1e4b7a-2d5c-4f8e-8b3a-6c9d2e5f1a73",
    "deal_id": "6d2c9f4e-1b7a-4e3d-8c5f-2a9b4d7e6f95"
  }
}

201 não quer dizer "created": true, e esta tabela dizia que sim. created responde "um contato NOVO nasceu nesta chamada?" — e não "este external_ref era novo?". Um external_ref inédito cujo e-mail/telefone já pertence a alguém no CRM reaproveita o contato existente: sai 201 com "created": false. Se o seu fluxo usa o created pra decidir "mandar e-mail de boas-vindas", leia o campo, nunca o código HTTP.

Pode reenviar à vontade. É o mesmo external_ref que garante que um timeout ou um retry do seu formulário não vira dois leads.

Tag inválida recusa o lead inteiro. Se tags trouxer um id que não existe nesta conta, ou uma tag que não serve nem pra contato nem pra negócio (uma tag só de empresa, ou uma tag só de negócio num lead sem deal), a resposta é 400 e nada é gravado — nem o contato. Confira os ids com GET/api/tags (seção 13) antes de ligar o formulário.

Erros comuns (400):

Situação Mensagem
owner_id de quem não é membro ativo "O responsável (owner_id) precisa ser uma pessoa ATIVA da sua equipe."
deal.funnel_id inexistente "Funil não encontrado."
deal.column_id inexistente "Coluna do funil não encontrada."
Coluna de outro funil "A coluna informada não pertence ao funil informado."
utm sem deal "Os campos de rastreio (utm) exigem um negócio (deal) para vincular."
custom_fields sem deal "Os campos personalizados (custom_fields) exigem um negócio (deal) para vincular."
contact só com name "contact.phone ou contact.email é obrigatório — sem um dos dois o mesmo lead vira dois contatos diferentes."
Tag que não existe na conta "tags: a etiqueta "…" não existe nesta conta."
Tag que não serve pra contato nem pra negócio "Escolha etiquetas aplicáveis ao contato ou negócio deste lead."
deal.extra_contact_ids com contato de outra conta "extra_contact_ids: o contato "…" não existe nesta conta."
custom_fields dentro de deal unknown_field — "O campo deal.custom_fields não existe nesta chamada". ⛒ Ele vai na raiz do corpo

11.1 Consultar um lead já enviado

Escopo: leads:read (distinto de leads:write — uma chave só de criação não pode auditar o histórico de envios). Método: GET/api/leads?external_ref=.

Quem migra uma base manda os leads pelo POST acima (idempotente por external_ref) e usa este GET pra provar, depois, o que aconteceu com um envio específico — sem precisar guardar a resposta do POST original.

curl "https://app.salos.com.br/api/leads?external_ref=site-form-8412" \
  -H "Authorization: Bearer $SALOS_API_KEY"
{
  "data": {
    "external_ref": "site-form-8412",
    "status": "done",
    "contact_id": "9f1e4b7a-2d5c-4f8e-8b3a-6c9d2e5f1a73",
    "deal_id": "6d2c9f4e-1b7a-4e3d-8c5f-2a9b4d7e6f95",
    "created_at": "2026-08-01T10:00:00.000Z"
  }
}

external_ref que não existe (nesta conta) devolve 404. ?external_ref= é obrigatório — sem ele, 400 (a rota nunca lista o histórico inteiro da conta de uma vez).