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:
- o
owner_idque você mandou; - o dono do contato (quando o lead caiu num contato que já existia e já tinha dono);
- o dono da empresa do negócio (ou, sem ela, da empresa do contato);
- 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_idna resposta é o do negócio que já existia;- nada do negócio existente é sobrescrito — rastreio (
utm),custom_fields, empresa eexternal_idsó preenchem o que estiver vazio; - o webhook
deal.creatednã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"
}
}
201não quer dizer"created": true, e esta tabela dizia que sim.createdresponde "um contato NOVO nasceu nesta chamada?" — e não "esteexternal_refera novo?". Umexternal_refinédito cujo e-mail/telefone já pertence a alguém no CRM reaproveita o contato existente: sai201com"created": false. Se o seu fluxo usa ocreatedpra decidir "mandar e-mail de boas-vindas", leia o campo, nunca o código HTTP.
Pode reenviar à vontade. É o mesmo
external_refque garante que um timeout ou um retry do seu formulário não vira dois leads.
Tag inválida recusa o lead inteiro. Se
tagstrouxer 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 semdeal), a resposta é400e nada é gravado — nem o contato. Confira os ids comGET/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).