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.
https://prospecte.me/api/v1Dados 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:
Authorization: Bearer SEU_TOKENUse 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.
curl --request GET \
--url 'https://prospecte.me/api/v1/cnpj/33000167000101' \
--header "Authorization: Bearer $PROSPECTE_API_TOKEN"// 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'));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ção | Consumo |
|---|---|
| Consulta por CNPJ | 1 crédito por empresa retornada |
| Pesquisa de empresas | 1 crédito a cada 10 registros, arredondado para cima em cada página |
| Consulta de saldo | 0 créditos |
| Resultado vazio ou erro | 0 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.
Por conta, somando todos os tokens. Consultar o saldo também conta no limite.
| Cabeçalho | Como usar |
|---|---|
X-Credits-Charged | Créditos cobrados nesta requisição. |
X-RateLimit-Limit | Limite de chamadas por minuto. |
X-RateLimit-Remaining | Chamadas restantes na janela atual. |
X-RateLimit-Reset | Fim da janela, em segundos Unix. |
Retry-After | Em respostas 429, quantos segundos aguardar. |
X-Request-Id | Identificador 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
/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.
{
"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
/cnpj/searchCombine filtros para encontrar empresas na base. Informe pelo menos um entre q, activity, section, uf e city.
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âmetro | Descrição |
|---|---|
q | Razão social, nome fantasia ou CNPJ. Até 120 caracteres. |
activity | Nome da atividade ou código CNAE. Até 120 caracteres. |
section | Seção CNAE, de A a U. |
uf · city | Sigla do estado e nome da cidade. |
status | ativa (padrão), baixada, inapta, suspensa ou nula. Vazio: todas. |
hasPhone · hasEmail | true para exigir telefone ou e-mail. Padrão: false. |
headquartersOnly | true para retornar somente matrizes. Padrão: false. |
page | Página, de 1 a 4.000. Padrão: 1. O último registro da página deve estar entre os primeiros 200 mil resultados. |
pageSize | De 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
/creditsVeja o saldo antes de iniciar um lote. Esta chamada não consome créditos.
curl 'https://prospecte.me/api/v1/credits' \
--header "Authorization: Bearer $PROSPECTE_API_TOKEN"{
"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.
{
"error": {
"code": "insufficient_credits",
"message": "Créditos disponíveis insuficientes."
}
}| HTTP | Significado | Próximo passo |
|---|---|---|
| 400 | Parâmetros inválidos | Confira filtros, CNPJ e paginação. |
| 401 | Token inválido | Confira o cabeçalho, a validade e a revogação do token. |
| 402 | Saldo insuficiente | Adicione créditos ou diminua o tamanho da página. |
| 403 | Acesso não permitido | Confira o estado da conta e a permissão de quem criou o token. |
| 404 | CNPJ não encontrado | Confira o número consultado. |
| 405 | Método não permitido | Use o método GET. |
| 429 | Limite atingido ou base ocupada | Aguarde o prazo em Retry-After. |
| 500 · 502 · 503 · 504 | Falha ou indisponibilidade | Tente 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.