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.

POST https://app.salos.com.br/api/leads leads:write

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.