GET /sistema/crm/leads/{id} · API

Endpoints · Sistema

Consulta um lead visível

GET /api/v1/sistema/crm/leads/{id}

Mesmas permissões e conta da listagem; recurso de outra conta responde 404.

Parâmetros

Nome	Em	Obrigatório	Descrição
`id`	path	sim

Respostas

Status	Descrição
200	Dados do sistema. meta.creditos_consumidos é sempre 0; datas sem fuso usam America/Sao_Paulo.
401	Chave inválida ou revogada.
403	Finalidade, conta, papel ou plano não permitem o acesso.
404	Recurso ausente ou fora da visão do titular.
405	A API do sistema aceita apenas GET.
422	Parâmetros inválidos.
429	Limite de chamadas atingido.
500	Leitura indisponível. Não representa saldo ou total zero.

Exemplo curl

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

Exemplo de resultado (200)

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

{
    "data": {
        "id": 123,
        "nome": "Ana Souza",
        "nome_empresa": "Empresa Exemplo Ltda",
        "cnpj_empresa": "12345678000190",
        "email": "ana@example.com",
        "telefone": null,
        "whatsapp": "5511999990000",
        "cargo": "Gerente",
        "setor": "Comercial",
        "status": "qualificado",
        "score_relevancia": 55,
        "temperatura": "quente",
        "origem": "manual",
        "tags": [],
        "tags_personalizadas": [
            "Cliente potencial"
        ],
        "id_usuario_responsavel": 10,
        "data_criacao": "2026-10-01 09:00:00",
        "data_atualizacao": "2026-10-16 08:00:00"
    },
    "meta": {
        "creditos_consumidos": 0,
        "consultado_em": "2026-10-16T08:00:00-03:00",
        "timezone": "America/Sao_Paulo"
    }
}

Campos retornados em data

Campo	Tipo	Descrição
`id`	`integer`	Identificador único do registro.
`nome`	`string`	nome
`nome_empresa`	`string`	nome empresa
`cnpj_empresa`	`string`	CNPJ da empresa, como texto. Vários leads podem compartilhar este CNPJ.
`email`	`string`	email
`telefone`	`string`	telefone
`whatsapp`	`string`	whatsapp
`cargo`	`string`	cargo
`setor`	`string`	setor
`status`	`string`	status
`score_relevancia`	`integer`	Score de 0 a 100; separado da classificação de temperatura.
`temperatura`	`string`	Classificação efetiva: quente, morno ou frio.
`origem`	`string`	origem
`tags`	`array`	Campo legado de tags; pode não conter as tags personalizadas.
`tags_personalizadas`	`array<string>`	Nomes das tags personalizadas usadas pelo filtro tag.
`id_usuario_responsavel`	`integer`	ID do responsável dentro da conta.
`data_criacao`	`string`	data criacao
`data_atualizacao`	`string`	data atualizacao

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