Injetar um lead
A porta de entrada para formulário de site, landing page e ferramenta de captação — cria contato e negócio numa chamada só, sem duplicar.
Corpo de exemplo
{
"external_ref": "site-form-8412",
"source": "landing-page-plano-pro",
"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"
},
"utm": {
"utm_source": "google",
"utm_medium": "cpc",
"utm_campaign": "plano-pro-agosto"
}
}Campos
| 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. Precisa casar com uma origem já cadastrada na conta (as origens são geridas dentro do CRM, no próprio negócio); se não casar, 400 |
tags |
não | até 20 ids de tag. Cada uma precisa existir na conta e servir pra contato ou negócio — senão 400, e nada é gravado |
owner_id |
não | pessoa ativa da equipe. Responsável do negócio criado; no contato, só vale se ele for novo ou ainda não tiver dono. Sem ele, o negócio fica com o dono do contato, senão com o da empresa |
contact.name |
sim | 1–120 |
contact.email / contact.phone |
um dos dois | e-mail válido (até 200) · telefone até 40. Mandar só o name devolve 400: sem e-mail nem telefone, o mesmo lead vira dois contatos diferentes na próxima submissão |
deal |
não | se presente, cria um negócio junto |
deal.funnel_id / deal.column_id |
não | funil e etapa de destino. Se os dois vierem, a coluna precisa pertencer àquele funil |
utm |
não | rastreio de campanha: utm_source, utm_medium, utm_campaign, utm_term, utm_content, gclid, fbclid (texto até 200 cada; gclid/fbclid vão dentro de utm). Exige deal — sem negócio, não há onde pendurar o rastreio |
Resposta
{
"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
O código HTTP conta se esta chamada foi processada agora; o created conta se o lead nasceu
aqui. Um external_ref novo cujo e-mail ou telefone já pertence a um contato do CRM volta 201
com "created": false — o contato existente foi reaproveitado. (Reenviar o mesmo external_ref
volta 200.) Quem decide se abre uma tarefa para o vendedor é o created, nunca o código HTTP.
O mesmo lead chegando duas vezes vira um negócio só
Se o contato já tem um negócio aberto no funil de destino, criado nos últimos 30 minutos,
o lead entra nesse negócio: o deal_id devolvido é o dele, nada dele é sobrescrito (rastreio,
campos personalizados, empresa e external_id só preenchem o vazio) e o webhook deal.created
não sai. Negócio aberto mais antigo, ganho ou perdido não recebe o lead — nasce um negócio novo.