API Lead

O que é a API Lead

A API Lead é o canal público de entrada de leads no Simplifica.

Ela foi pensada para:

• landing pages;
• formulários externos;
• integrações simples com campanhas;
• automações que precisam registrar um lead para processamento interno.

Endpoint publicado

POST {{base_url}}/api_lead/lead

Autenticação

Essa integração usa token público por chave no header:

x-api-key: {{public_api_key}}

Ela não usa bearer token.

Hoje, este é o principal caso documentado de uso de token público no Simplifica.

No próprio Simplifica existe uma área de Integrações onde a empresa visualiza essa chave.

Formato do body

Envie JSON.

Os nomes dos campos são case-sensitive. Para evitar erro de processamento, envie sempre os nomes exatamente em minúsculas, como nesta documentação.

Exemplo mínimo recomendado:

{
  "nome": "Maria da Silva",
  "origem": "Landing Page",
  "celular": "85999990000"
}

Exemplo com campos adicionais:

{
  "nome": "Matheus Botelho",
  "origem": "Instagram",
  "consultor": "joao.silva@gmail.com",
  "celular": "11991234567",
  "telefone_fixo": "1143211234",
  "email": "matheus.botelho@gmail.com",
  "utm_creative_format": "video",
  "utm_product": "simplifica_lead_capture",
  "utm_term": "lead_form",
  "utm_medium": "paid_social",
  "utm_source_platform": "facebook_ads",
  "utm_audience": "lookalike_2pct_br",
  "utm_id": "fb_oct_2025_lp1",
  "utm_content": "creative_v1",
  "utm_source": "facebook",
  "utm_campaign": "lead_gen_oct_2025",
  "utm_marketing_tactic": "prospecting",
  "custom": {
    "Qual o nome da sua empresa?": "Espaço das Cadeiras",
    "Qual o seu Cargo?": "CEO / Dono do Negócio",
    "Qual é o Faturamento Médio Mensal?": "Entre R$100 mil a R$300 mil",
    "Segmento": "Comércio de produtos de mesas"
  }
}

Campos obrigatórios

• nome
• origem
• celular

Campos opcionais mais usados

• email
• consultor
• telefone_fixo
• cpf
• cnpj
• custom
• chaves com prefixo utm_

Regras confirmadas do payload

• envie os nomes dos campos exatamente em minúsculas, como publicados nesta documentação;
• consultor, quando enviado, deve ser o e-mail do consultor cadastrado no Simplifica;
• celular e telefone_fixo aceitam envio com ou sem máscara;
• cpf e cnpj não devem ser enviados juntos;
• custom aceita um objeto JSON livre;
• chaves com prefixo utm_ podem ser enviadas livremente.

Exemplos válidos de formato:

• celular: 11991234567 ou (11) 99123-4567
• telefone_fixo: 1143211234 ou (11) 4321-1234
• consultor: joao.silva@gmail.com

Contrato HTTP síncrono atual

O retorno HTTP atual é enxuto. Ele informa apenas se o endpoint aceitou ou não aquele payload naquele momento.

Respostas publicadas:

• 200: lead recebido;
• 400: body ausente ou JSON inválido;
• 401: credencial inválida;
• 500: erro técnico inesperado.

Regra do campo consultor

• quando enviado, o valor esperado é o e-mail do consultor cadastrado no Simplifica;
• se o e-mail for encontrado, o lead já entra vinculado a esse consultor;
• se consultor não for enviado, o Simplifica tenta definir automaticamente um responsável.

Ordem usada quando consultor não vem no payload:

1. lista da vez da empresa;
2. usuário marcado como SDR;
3. usuário marcado como closer;
4. primeiro usuário encontrado.

Regra do campo origem

• se a origem enviada já existir, ela é usada no cadastro do lead;
• se a origem ainda não existir, o Simplifica cria essa origem automaticamente e continua o cadastro.
• continue enviando origem preenchida; a documentação trata esse campo como obrigatório no payload.

Processamento interno após o recebimento

Depois que o endpoint aceita o payload, o lead segue para tratamento interno do Simplifica.

Nesta etapa podem ocorrer:

• validações complementares de negócio;
• exigência de pelo menos um contato válido, como celular ou email;
• deduplicação ou consolidação por documento, celular ou e-mail;
• bloqueios por conflito de identificação.

Importante:

• essas regras internas não mudam o contrato HTTP síncrono publicado;
• a documentação pública não promete, por enquanto, payload síncrono detalhado de erro de validação;
• a documentação pública também não promete idempotência formal do endpoint.

Respostas esperadas

• 200: lead recebido;
• 400: JSON inválido;
• 401: credencial inválida;
• 500: erro técnico inesperado.

Exemplos comuns:

{
  "status": "sucesso",
  "mensagem": "Lead recebido"
}

{
  "status": "erro",
  "mensagem": "Json inválido"
}

Quando usar a API reference

Use a referência técnica para ver:

• contrato exato do endpoint;
• schema do payload;
• formato das respostas;
• exemplos técnicos prontos para integração.