POST /sistema/crm/leads · API

Endpoints · Sistema

Inclui um contato no CRM

POST /api/v1/sistema/crm/leads

Requer chave system read_write. Cria contato privado com origem api e responsável titular; não envia mensagens. Limite de contatos ativos aplicado. id_externo protege contra duplicação entre chaves da mesma conta. Não aceita campos de conta ou responsável.

Parâmetros

Nome	Em	Obrigatório	Descrição
`Idempotency-Key`	header	sim	Reutilize ao repetir o mesmo pedido. Outro corpo com a mesma chave: 409.

Body da requisição

Campo	Tipo	Descrição
`id_externo` obrigatório	`string`	Estável por conta e contato; inclua prefixo da integração.
`nome` obrigatório	`string`
`email`	`string`
`telefone`	`string`
`whatsapp`	`string`
`cargo`	`string`
`setor`	`string`
`cnpj_empresa`	`string`	CNPJ numérico válido ou vazio para contato autônomo.
`nome_empresa`	`string`
`status`	`string`	Valores: `novo`, `em_prospeccao`, `qualificado`, `em_negociacao`, `convertido`, `sem_resposta`, `descartado`, `arquivado`.
`temperatura`	`string`	Valores: `quente`, `morno`, `frio`.

Exemplo:

{
    "id_externo": "erp:contato:ana-001",
    "nome": "Ana Souza",
    "email": "ana@example.com",
    "cnpj_empresa": "11222333000181",
    "nome_empresa": "Empresa Exemplo Ltda",
    "status": "novo",
    "temperatura": "morno"
}

Respostas

Status	Descrição
200	Mesmo id_externo e cadastro já incluído; devolve o ID existente.
201	Cadastro criado.
401	Chave inválida.
403	Escopo, permissão ou limite do CRM não permite a operação.
404	Recurso inexistente ou fora da visão.
409	Cadastro duplicado ou conflito de idempotência/identificador externo.
422	Campos inválidos, desconhecidos ou supressão de dados.
429	Limite de chamadas.
503	Migração ou verificação indisponível.

Exemplo curl

curl -X POST https://leadcnpj.com.br/api/v1/sistema/crm/leads \
  -H "Authorization: Bearer leadcnpj_system_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"id_externo":"erp:contato:ana-001","nome":"Ana Souza","email":"ana@example.com","cnpj_empresa":"11222333000181","nome_empresa":"Empresa Exemplo Ltda","status":"novo","temperatura":"morno"}'

Exemplo de resultado (201)

Dados fictícios. Campos sem informação podem ser null.

{
    "data": {
        "id": 123,
        "id_externo": "erp:contato:ana-001",
        "reutilizado": true
    },
    "meta": {
        "creditos_consumidos": 0,
        "consultado_em": "2026-10-16T09:00:00-03:00",
        "timezone": "America/Sao_Paulo"
    }
}

Como consultar o CRM

Crie uma chave com finalidade Sistema em Configurações → API. Use Authorization: Bearer leadcnpj_system_.... A chave de prospecção leadcnpj_live_ não funciona nestas consultas. Os exemplos abaixo usam dados fictícios e não consomem créditos.

Um lead é uma pessoa/contato, identificado por id. Uma empresa pode ter vários leads com o mesmo cnpj_empresa; cada contato mantém seu próprio status, temperatura e oportunidades.

Listar leads e seus IDs

Cada item em data contém id. O padrão exclui arquivados. Continue nas próximas páginas enquanto meta.has_more for true.

curl --get "https://leadcnpj.com.br/api/v1/sistema/crm/leads" \
  -H "Authorization: Bearer leadcnpj_system_..." \
  --data-urlencode "page=1" \
  --data-urlencode "per_page=100"

Buscar pelo nome da pessoa

Busca um trecho apenas no nome do contato. Pode retornar mais de uma pessoa; use o id para distinguir.

curl --get "https://leadcnpj.com.br/api/v1/sistema/crm/leads" \
  -H "Authorization: Bearer leadcnpj_system_..." \
  --data-urlencode "nome=Ana Souza"

Buscar em nome, empresa ou e-mail

q pesquisa os três campos. Para pesquisar somente o nome da pessoa, use nome.

curl --get "https://leadcnpj.com.br/api/v1/sistema/crm/leads" \
  -H "Authorization: Bearer leadcnpj_system_..." \
  --data-urlencode "q=ana@example.com"

Filtrar por tag

Use o nome completo da tag personalizada. Não distingue maiúsculas. tags_personalizadas mostra essas tags; tags é o campo legado e pode estar vazio.

curl --get "https://leadcnpj.com.br/api/v1/sistema/crm/leads" \
  -H "Authorization: Bearer leadcnpj_system_..." \
  --data-urlencode "tag=Cliente potencial"

Filtrar por status do lead

Valores: novo, em_prospeccao, qualificado, em_negociacao, convertido, sem_resposta, descartado, arquivado. Envie exatamente um desses códigos.

curl --get "https://leadcnpj.com.br/api/v1/sistema/crm/leads" \
  -H "Authorization: Bearer leadcnpj_system_..." \
  --data-urlencode "status=qualificado"

Filtrar por temperatura

Valores: quente, morno, frio. É a classificação efetiva do CRM, não necessariamente a sugestão do score.

curl --get "https://leadcnpj.com.br/api/v1/sistema/crm/leads" \
  -H "Authorization: Bearer leadcnpj_system_..." \
  --data-urlencode "temperatura=quente"

Buscar contatos pelo nome da empresa

Retorna os contatos visíveis cujo nome de empresa contém esse trecho. Empresas com nomes semelhantes também podem aparecer.

curl --get "https://leadcnpj.com.br/api/v1/sistema/crm/leads" \
  -H "Authorization: Bearer leadcnpj_system_..." \
  --data-urlencode "empresa=Empresa Exemplo"

Listar contatos de uma empresa específica

CNPJ exato, com ou sem pontuação. Paginar se houver mais contatos. A resposta é uma lista de pessoas, não um único cadastro de empresa.

curl --get "https://leadcnpj.com.br/api/v1/sistema/crm/leads" \
  -H "Authorization: Bearer leadcnpj_system_..." \
  --data-urlencode "cnpj=12345678000190" \
  --data-urlencode "per_page=100"

Combinar filtros

Os filtros se acumulam com AND: o lead precisa atender a todos. Uma lista vazia não indica erro.

curl --get "https://leadcnpj.com.br/api/v1/sistema/crm/leads" \
  -H "Authorization: Bearer leadcnpj_system_..." \
  --data-urlencode "tag=Cliente potencial" \
  --data-urlencode "status=qualificado" \
  --data-urlencode "temperatura=quente" \
  --data-urlencode "cnpj=12345678000190"

Consultar um lead pelo ID

data é um objeto com os campos publicados do lead, incluindo contatos, empresa, status, temperatura e tags. Não inclui CPF, notas internas nem histórico de conversa. Ausente ou fora da visão da chave retorna 404.

curl --get "https://leadcnpj.com.br/api/v1/sistema/crm/leads/123" \
  -H "Authorization: Bearer leadcnpj_system_..."

Consultar oportunidades de um lead

Lista negócios em que 123 é o lead principal. Aplica também a visibilidade do responsável do negócio. Um lead existente sem oportunidades visíveis retorna data: [].

curl --get "https://leadcnpj.com.br/api/v1/sistema/crm/leads/123/oportunidades" \
  -H "Authorization: Bearer leadcnpj_system_..." \
  --data-urlencode "page=1" \
  --data-urlencode "per_page=100"

Filtrar oportunidades abertas

Status do negócio: aberto, ganho, perdido, arquivado. Esse filtro não é o status do lead. Sem filtro, todos os status visíveis são incluídos.

curl --get "https://leadcnpj.com.br/api/v1/sistema/crm/leads/123/oportunidades" \
  -H "Authorization: Bearer leadcnpj_system_..." \
  --data-urlencode "status=aberto"

Consultar atualizações

Data RFC3339 com fuso. Não é um histórico de exclusões. Atualizações automáticas que não mudam data_atualizacao não aparecem neste recorte.

curl --get "https://leadcnpj.com.br/api/v1/sistema/crm/leads" \
  -H "Authorization: Bearer leadcnpj_system_..." \
  --data-urlencode "updated_since=2026-10-16T00:00:00-03:00"

Incluir arquivados na integração

Para obter todos os status, percorra primeiro a lista padrão inteira e depois esta lista de arquivados. Não existe status=all.

curl --get "https://leadcnpj.com.br/api/v1/sistema/crm/leads" \
  -H "Authorization: Bearer leadcnpj_system_..." \
  --data-urlencode "status=arquivado" \
  --data-urlencode "page=1" \
  --data-urlencode "per_page=100"

Como listar todos os leads com ID

page começa em 1; per_page aceita de 1 a 100 (padrão 25). A ordem é crescente por ID. Repita a requisição mantendo os filtros e incrementando page até meta.has_more=false. total é o total visível para aqueles filtros, não o total global da conta. A paginação não congela a base: para uma sincronização, deduplique por ID e reconcilie alterações.

import os
import requests

base = "https://leadcnpj.com.br/api/v1/sistema/crm/leads"
headers = {"Authorization": "Bearer " + os.environ["LEADCNPJ_SYSTEM_KEY"]}
leads_por_id = {}

# Sem status: não arquivados. Segunda passagem: arquivados.
for status in (None, "arquivado"):
    pagina = 1
    while True:
        filtros = {"page": pagina, "per_page": 100}
        if status:
            filtros["status"] = status
        resposta = requests.get(base, headers=headers, params=filtros, timeout=30)
        resposta.raise_for_status()  # Não interpretar 401/403/429 como lista vazia.
        resultado = resposta.json()
        for lead in resultado["data"]:
            leads_por_id[lead["id"]] = lead
        if not resultado["meta"]["has_more"]:
            break
        pagina += 1

for identificador, lead in leads_por_id.items():
    print(identificador, lead["nome"], lead["cnpj_empresa"])

O exemplo requer Python e o pacote requests. Defina LEADCNPJ_SYSTEM_KEY no ambiente. Em produção, trate 429 com espera conforme Retry-After quando informado e tentativas limitadas; não repita indefinidamente. Para consultar um ID retornado, use /sistema/crm/leads/123; para seus negócios, /sistema/crm/leads/123/oportunidades.

Como ler o resultado

data é uma lista nos endpoints de listagem e um objeto no detalhe do lead. meta.creditos_consumidos é zero. temperatura retorna a classificação efetiva; score_relevancia continua sendo um número separado. tags_personalizadas contém nomes usados pelo filtro tag. Datas sem fuso usam America/Sao_Paulo; CNPJ, telefone e valores monetários são strings para preservar a representação.

Nos negócios, id_lead identifica o contato principal, id_pipeline o funil e id_estagio a etapa. Não há exposição de notas rápidas ou internas. O valor previsto e o valor real são distintos; null significa ausência de informação, não zero.

Documentação da API LeadCNPJ