GET /sistema/crm/leads · API

Endpoints · Sistema

Lista os leads visíveis no CRM

GET /api/v1/sistema/crm/leads

Paginação ordenada por id, filtros cumulativos. Sem status, exclui arquivados. Não retorna CPF, notas internas nem histórico de conversa. Use updated_since em RFC3339 para filtrar atualizações; não é um log de exclusões.

Parâmetros

Nome	Em	Obrigatório	Descrição
`page`	query	não	Página, começando em 1. Padrão: 1.
`per_page`	query	não	Leads por página: 1 a 100. Padrão: 25.
`status`	query	não	Status exato: novo, em_prospeccao, qualificado, em_negociacao, convertido, sem_resposta, descartado ou arquivado. Sem filtro, exclui arquivados.
`q`	query	não	Trecho literal no nome da pessoa, nome da empresa ou e-mail; filtros combinados com AND.
`updated_since`	query	não	Atualizados após esta data RFC3339, por exemplo 2026-10-16T00:00:00-03:00.
`nome`	query	não	Trecho literal apenas no nome da pessoa. Ex.: Ana.
`empresa`	query	não	Trecho literal no nome da empresa. Pode retornar vários leads da mesma empresa.
`cnpj`	query	não	CNPJ exato da empresa, com ou sem pontuação. Retorna todos os seus leads visíveis.
`tag`	query	não	Nome completo de uma tag personalizada, sem distinguir maiúsculas; não é trecho nem ID.
`temperatura`	query	não	Classificação efetiva do CRM: escolha manual/ICP é preservada; sem classificação, usa o score.

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

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",
        "page": 1,
        "per_page": 25,
        "total": 1,
        "has_more": false
    }
}

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