***

title: API Lead
subtitle: Envie leads externos ao Simplifica por webhook com x-api-key
slug: 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

```http
POST {{base_url}}/api_lead/lead
```

## Autenticação

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

```http
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:

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

Exemplo com campos adicionais:

```json
{
  "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:

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

```json
{
  "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.