Documentacao da API REST

Base URL

https://basecnpj.app/api/v1/

Autenticação

Rotas protegidas exigem token Bearer no header Authorization.

Authorization: Bearer SEU_TOKEN

Gere sua chave em Minha conta → API Keys (requer plano Pro ou Business).

Limites por plano

Plano	Consultas/dia (site)	Requisições/dia (API)	Preço
Free	10	—	R$ 0
Pro	Ilimitadas	5.000	R$ 49/mês
Business	Ilimitadas	Ilimitadas	Sob consulta

Formato de resposta

Sucesso

{
  "ok": true,
  "data": { ... }
}

Erro

{
  "ok": false,
  "error": {
    "code": "not_found",
    "message": "Empresa não encontrada."
  }
}

GET Público Status

GET /api/v1/?route=status

Resposta

{
  "ok": true,
  "data": {
    "status": "ok",
    "version": "1.0.0",
    "database": "up",
    "counts": {
      "empresas": 67482931
    }
  }
}

Postman: GET https://basecnpj.app/api/v1/?route=status — sem headers adicionais

GET Bearer Busca

GET /api/v1/?route=busca&q=TERMO&page=1&per_page=15

Parâmetros

Param	Tipo	Obrig.	Descrição
`q`	string	Sim	Termo de busca (razão social ou CNPJ)
`page`	int	Não	Página (default: 1)
`per_page`	int	Não	Itens por página (1-50, default: 15)

Resposta

{
  "ok": true,
  "data": {
    "query": "banco do brasil",
    "page": 1,
    "per_page": 15,
    "total": 342,
    "total_pages": 23,
    "items": [
      {
        "cnpj_basico": "00000000",
        "cnpj_formatado": "00.000.000/0001-91",
        "razao_social": "BANCO DO BRASIL SA",
        "porte_codigo": "05",
        "porte_descricao": "Demais",
        "uf": "DF",
        "situacao_cadastral": "02",
        "situacao_descricao": "Ativa",
        "ativa": true
      }
    ]
  }
}

Postman: GET https://basecnpj.app/api/v1/?route=busca&q=banco+do+brasil
Header: Authorization: Bearer SEU_TOKEN

GET Público Detalhe do CNPJ

GET /api/v1/?route=cnpj&cnpj=XXXXXXXX

Parâmetros

Param	Tipo	Obrig.	Descrição
`cnpj`	string	Sim	CNPJ base (8 dígitos) ou completo (14 dígitos)

Resposta (resumida)

{
  "ok": true,
  "data": {
    "cnpj_basico": "00000000",
    "cnpj_completo_formatado": "00.000.000/0001-91",
    "razao_social": "BANCO DO BRASIL SA",
    "capital_social": 120000000.00,
    "porte_descricao": "Demais",
    "natureza_juridica_descricao": "Sociedade de Economia Mista",
    "regime_tributario_texto": "Lucro real",
    "simples": { "opcao_simples": false, "opcao_mei": false },
    "estabelecimento_matriz": {
      "nome_fantasia": "BANCO DO BRASIL",
      "situacao_descricao": "Ativa",
      "email": "contato@bb.com.br",
      "logradouro": "SBS QUADRA 1",
      "uf": "DF",
      "municipio": "BRASILIA"
    },
    "telefones": [
      { "tipo": "comercial", "ddd": "61", "numero": "34939000" }
    ],
    "socios": [
      {
        "nome_razao": "FULANO DE TAL",
        "tipo_socio": "1",
        "qualificacao_descricao": "Diretor"
      }
    ],
    "estabelecimentos": [ ... ],
    "cnaes": [ ... ]
  }
}

Postman: GET https://basecnpj.app/api/v1/?route=cnpj&cnpj=00000000 — sem headers adicionais

GET Bearer Sugestão (Autocomplete)

GET /api/v1/?route=sugestao&q=ME

Parâmetros

Param	Tipo	Obrig.	Descrição
`q`	string	Sim	Termo de busca (mín. 2 caracteres)

Resposta

{
  "ok": true,
  "data": {
    "items": [
      {
        "cnpj_basico": "19707600",
        "cnpj_formatado": "19.707.600/0001-00",
        "razao_social": "METTRIC DATA TECHNOLOGY LTDA",
        "porte_codigo": "01",
        "ativa": true
      }
    ]
  }
}

Postman: GET https://basecnpj.app/api/v1/?route=sugestao&q=mettric
Header: Authorization: Bearer SEU_TOKEN

Códigos de erro

HTTP	Código	Descrição
`400`	missing_q / invalid_cnpj	Parâmetros inválidos ou ausentes
`403`	forbidden	Token inválido ou sem permissão
`404`	not_found / unknown_route	Empresa ou rota não encontrada
`405`	method_not_allowed	Use GET (POST/PUT não suportados)
`500`	server_error	Erro interno no servidor

Testando no Postman

Configure uma variável de ambiente no Postman:

Variável	Valor
`base_url`	`https://basecnpj.app/api/v1`
`api_token`	Sua chave gerada em API Keys

Exemplos prontos

Teste	Método	URL	Auth
Health check	GET	`{{base_url}}/?route=status`	Nenhuma
Buscar empresa	GET	`{{base_url}}/?route=busca&q=petrobras`	Bearer {{api_token}}
Detalhe CNPJ	GET	`{{base_url}}/?route=cnpj&cnpj=33592510`	Nenhuma
Autocomplete	GET	`{{base_url}}/?route=sugestao&q=nubank`	Bearer {{api_token}}

Curl de teste rápido

curl -s "https://basecnpj.app/api/v1/?route=status" | python3 -m json.tool

← Voltar para área dev