prospecte.me
Meus tokensCriar conta
Nesta documentação

PARA DESENVOLVEDORES

Dados de empresas.
Dentro do seu sistema.

Consulte CNPJ e encontre empresas por atividade, cidade e estado. Uma API com autenticação e consumo sob seu controle.

URL basehttps://prospecte.me/api/v1

Dados abertos da Receita Federal, em uma base atualizada periodicamente. A versão consultada aparece em datasetVersion quando disponível.

Autenticação

Crie sua conta e acesse API e integrações. O responsável e os administradores podem gerar um token com nome e validade de 1 a 365 dias. O padrão é 90 dias.

O token completo aparece uma única vez. Copie-o para uma variável de ambiente no seu servidor e envie-o no cabeçalho de cada requisição:

Cabeçalho HTTP
Authorization: Bearer SEU_TOKEN

Use o token somente no servidor. Não publique em páginas, aplicativos distribuídos ou repositórios. Você pode revogá-lo a qualquer momento no painel; um token revogado deixa de autorizar novas chamadas.

A API usa tokens Bearer e não aceita o cookie de login como autenticação. Tokens deixam de funcionar se a conta for suspensa ou o criador perder a permissão necessária.

Sua primeira consulta

Defina a variável PROSPECTE_API_TOKEN no seu ambiente e escolha um exemplo abaixo. Uma consulta individual concluída consome 1 crédito.

Requisição · cURL
curl --request GET \
  --url 'https://prospecte.me/api/v1/cnpj/33000167000101' \
  --header "Authorization: Bearer $PROSPECTE_API_TOKEN"
Requisição · Node.js
// Execute no seu servidor, com o token em uma variável de ambiente.
const response = await fetch(
  'https://prospecte.me/api/v1/cnpj/33000167000101',
  { headers: { Authorization: `Bearer ${process.env.PROSPECTE_API_TOKEN}` } }
);
const data = await response.json();
if (!response.ok) throw new Error(data.error.message);
console.log(data.item);
console.log('Créditos:', response.headers.get('X-Credits-Charged'));
Requisição · Python
import json
import os
import urllib.request

request = urllib.request.Request(
    'https://prospecte.me/api/v1/cnpj/33000167000101',
    headers={'Authorization': 'Bearer ' + os.environ['PROSPECTE_API_TOKEN']}
)
with urllib.request.urlopen(request, timeout=30) as response:
    data = json.load(response)
    print(data['item'])
    print('Créditos:', response.headers['X-Credits-Charged'])

A API v1 aceita somente GET e retorna JSON. Confira o status HTTP antes de usar os dados e acompanhe o custo em X-Credits-Charged.

Créditos e limites

Os tokens usam o saldo da sua conta, compartilhado com as operações do app. Consulte o consumo e os tokens em API e integrações e adicione saldo em Créditos.

OperaçãoConsumo
Consulta por CNPJ1 crédito por empresa retornada
Pesquisa de empresas1 crédito a cada 10 registros, arredondado para cima em cada página
Consulta de saldo0 créditos
Resultado vazio ou erro0 créditos

Na pesquisa, 1 a 10 registros custam 1 crédito; 11 a 20 custam 2. Uma página com 100 registros custa 10 créditos. Antes de consultar, reservamos o custo máximo da página (ceil(pageSize / 10)); a parte não utilizada é liberada ao concluir. Você precisa ter esse valor disponível para iniciar.

60 requisições por minuto

Por conta, somando todos os tokens. Consultar o saldo também conta no limite.

CabeçalhoComo usar
X-Credits-ChargedCréditos cobrados nesta requisição.
X-RateLimit-LimitLimite de chamadas por minuto.
X-RateLimit-RemainingChamadas restantes na janela atual.
X-RateLimit-ResetFim da janela, em segundos Unix.
Retry-AfterEm respostas 429, quantos segundos aguardar.
X-Request-IdIdentificador para conferir a requisição.

Ao atingir o limite, aguarde o prazo informado antes de repetir. Uma nova consulta concluída é cobrada novamente, mesmo que você consulte o mesmo CNPJ.

Consulta CNPJ

GET/cnpj/{cnpj}

Retorna cadastro, endereço, contatos, atividade econômica, situação cadastral e, quando disponíveis, regime tributário e quadro societário. Informe o CNPJ com 14 dígitos, sem pontuação.

Resposta simplificada · exemplo de estrutura
{
  "item": {
    "id": "cnpj:33000167000101",
    "kind": "cnpj",
    "name": "PETROBRAS",
    "cnpj": "33.000.167/0001-01",
    "status": "Ativa",
    "city": "Rio de Janeiro",
    "uf": "RJ"
  },
  "source": "dataset",
  "datasetVersion": "2026-07"
}

O exemplo é ilustrativo e omite campos para facilitar a leitura. Os campos ausentes na fonte podem vir vazios ou nulos. CPFs de sócios são mascarados. Consulte o esquema completo no arquivo OpenAPI.

Pesquisa de empresas

GET/cnpj/search

Combine filtros para encontrar empresas na base. Informe pelo menos um entre q, activity, section, uf e city.

Pesquisa · cURL
curl --get 'https://prospecte.me/api/v1/cnpj/search' \
  --header "Authorization: Bearer $PROSPECTE_API_TOKEN" \
  --data-urlencode 'activity=padaria' \
  --data-urlencode 'city=Campinas' \
  --data-urlencode 'uf=SP' \
  --data-urlencode 'pageSize=10'
ParâmetroDescrição
qRazão social, nome fantasia ou CNPJ. Até 120 caracteres.
activityNome da atividade ou código CNAE. Até 120 caracteres.
sectionSeção CNAE, de A a U.
uf · citySigla do estado e nome da cidade.
statusativa (padrão), baixada, inapta, suspensa ou nula. Vazio: todas.
hasPhone · hasEmailtrue para exigir telefone ou e-mail. Padrão: false.
headquartersOnlytrue para retornar somente matrizes. Padrão: false.
pagePágina, de 1 a 4.000. Padrão: 1. O último registro da página deve estar entre os primeiros 200 mil resultados.
pageSizeDe 1 a 100 registros. Padrão: 10. Cada página tem cobrança própria.

A resposta inclui rows, total, totalCapped, page, pageSize, source e datasetVersion. A condição (page - 1) * pageSize + pageSize ≤ 200000 precisa ser atendida. Para a próxima página, mantenha os filtros e aumente page. Pare quando a página vier vazia ou com menos registros que o tamanho solicitado.

O total em pesquisas por nome pode ser aproximado. Use os registros recebidos para controlar a paginação. A origem dataset indica a base dedicada; public indica a fonte alternativa de consulta individual.

Consulta de saldo

GET/credits

Veja o saldo antes de iniciar um lote. Esta chamada não consome créditos.

Saldo · cURL
curl 'https://prospecte.me/api/v1/credits' \
  --header "Authorization: Bearer $PROSPECTE_API_TOKEN"
Resposta · exemplo ilustrativo
{
  "wallet": {
    "balance": 100,
    "reserved": 10,
    "available": 90
  }
}

balance é o saldo total; reserved, a parte comprometida com operações em andamento; available, o que você pode usar em novas consultas.

Códigos de erro

Uma falha retorna o status HTTP e um objeto error com código e mensagem. Erros não consomem créditos.

Resposta · HTTP 402
{
  "error": {
    "code": "insufficient_credits",
    "message": "Créditos disponíveis insuficientes."
  }
}
HTTPSignificadoPróximo passo
400Parâmetros inválidosConfira filtros, CNPJ e paginação.
401Token inválidoConfira o cabeçalho, a validade e a revogação do token.
402Saldo insuficienteAdicione créditos ou diminua o tamanho da página.
403Acesso não permitidoConfira o estado da conta e a permissão de quem criou o token.
404CNPJ não encontradoConfira o número consultado.
405Método não permitidoUse o método GET.
429Limite atingido ou base ocupadaAguarde o prazo em Retry-After.
500 · 502 · 503 · 504Falha ou indisponibilidadeTente novamente com espera crescente e limite de tentativas.

Evite tentativas repetidas sem intervalo. Registre o X-Request-Id, o horário e o status para investigar falhas. Nunca registre o token completo.