API REST
Integre 70 milhões de empresas brasileiras com histórico evolutivo completo ao seu produto em minutos. Autenticação simples por API Key, 3 níveis de consulta e respostas em menos de 50ms.
Como usar
Toda requisição deve incluir sua API Key no header X-API-Key.
Crie uma conta gratuita, acesse o painel e gere sua chave em Configurações → API Keys.
Todas as chaves iniciam com o prefixo vxd_.
O rate limit opera em duas camadas independentes.
Ultrapassar qualquer uma resulta em 429 Too Many Requests.
Todas as chaves têm um limite fixo de 100 req/min. Aplica-se independentemente do plano contratado.
Quota horária definida pelo plano. Soma o uso de todas as suas API Keys.
| Plano | Acesso API | Req / hora |
|---|---|---|
| Trial | ✘ Não incluso | — |
| Início | ✘ Não incluso | — |
| Profissional | ✔ Incluído | 500 |
| Empresarial | ✔ Incluído | 2.000 |
Headers de resposta (janela horária por plano):
A janela horária reinicia no minuto zero da hora seguinte (UTC). Ao atingir o limite, aguarde o reset ou faça upgrade de plano.
# Formato obrigatório do header GET https://api.vixdados.com.br/v1/public/cnpj/12345678000199 X-API-Key: vxd_sua_chave_aqui Content-Type: application/json Accept: application/json
{
"error": "UNAUTHORIZED",
"message": "API Key ausente ou inválida",
"statusCode": 401
}
Profundidade de dados
Escolha o nível de detalhe conforme sua necessidade. Cada nível consome uma quantidade diferente de créditos.
Dados cadastrais atuais da empresa e todos os seus estabelecimentos registrados na Receita Federal.
empresa)estabelecimentos)?nivel=simples
Tudo do nível básico mais sócios, status no Simples Nacional e lista de concorrentes por CNAE.
socios)simples_nacional)concorrentes)?nivel=intermediaria
Dados completos + histórico campo a campo de cada alteração registrada + mapeamento de empresas colocalizadas no mesmo endereço.
historico.eventos)endereco_inteligente)?nivel=auditoria
Endpoint
Um único endpoint para consultar qualquer empresa brasileira.
/v1/public/cnpj/{CNPJ}
Retorna os dados cadastrais completos de uma empresa pelo CNPJ. O parâmetro nivel controla a profundidade da resposta e o consumo de créditos.
| Nome | Local | Tipo | Obrigatório | Descrição |
|---|---|---|---|---|
CNPJ |
path | string | sim | CNPJ com 8 a 14 dígitos (com ou sem formatação). 8 dígitos = CNPJ raiz (retorna todos os estabelecimentos); 14 dígitos = estabelecimento específico |
nivel |
query | string | não | simples | intermediaria | auditoria (padrão: simples) |
X-API-Key |
header | string | sim | Sua API Key no formato vxd_... |
| Campo | Tipo | Nível mínimo | Descrição |
|---|---|---|---|
empresa |
object | Básico | Dados cadastrais principais da empresa |
empresa.cnpj_basico |
string | Básico | 8 primeiros dígitos do CNPJ |
empresa.razao_social |
string | Básico | Razão social registrada na Receita Federal |
empresa.capital_social |
number | Básico | Capital social em reais |
empresa.porte |
string | Básico | ME / EPP / DEMAIS |
estabelecimentos |
array | Básico | Todos os estabelecimentos (matriz + filiais) |
socios |
array | Intermediário | Quadro de sócios e administradores |
simples_nacional |
object | Intermediário | Status no Simples Nacional e datas de opção/exclusão |
concorrentes |
array | Intermediário | Empresas com mesmo CNAE na mesma cidade |
historico.eventos |
array | Auditoria | Linha do tempo de todas as alterações detectadas |
endereco_inteligente |
object | Auditoria | Empresas cadastradas no mesmo CEP e número + alerta de colocalização (≥10 empresas) |
Integração
Copie e cole. Substitua SUA_API_KEY e CNPJ pelos seus valores reais.
# Consulta nível auditoria — retorna histórico completo (5 créditos) curl -s -X GET \ "https://api.vixdados.com.br/v1/public/cnpj/12345678000199?nivel=auditoria" \ -H "X-API-Key: SUA_API_KEY" \ -H "Accept: application/json" \ | python3 -m json.tool
// Node.js 18+ — fetch nativo (sem dependências adicionais) const API_KEY = 'SUA_API_KEY'; const CNPJ = '12.345.678/0001-99'; // com ou sem formatação const NIVEL = 'intermediaria'; // simples | intermediaria | auditoria async function consultarEmpresa(cnpj, nivel = 'simples') { const cnpjLimpo = cnpj.replace(/\D/g, ''); const url = `https://api.vixdados.com.br/v1/public/cnpj/${cnpjLimpo}?nivel=${nivel}`; const resp = await fetch(url, { method: 'GET', headers: { 'X-API-Key': API_KEY, 'Accept': 'application/json', }, }); if (!resp.ok) { const err = await resp.json(); throw new Error(`Erro ${resp.status}: ${err.message}`); } return resp.json(); } // Uso consultarEmpresa(CNPJ, NIVEL) .then(data => console.log('Razão social:', data.empresa.razao_social)) .catch(console.error);
# pip install requests import re import requests API_KEY = "SUA_API_KEY" BASE_URL = "https://api.vixdados.com.br/v1/public/cnpj" def consultar_empresa(cnpj: str, nivel: str = "simples") -> dict: cnpj_limpo = re.sub(r"\D", "", cnpj) url = f"{BASE_URL}/{cnpj_limpo}" resp = requests.get( url, params={"nivel": nivel}, headers={ "X-API-Key": API_KEY, "Accept": "application/json", }, timeout=10, ) resp.raise_for_status() return resp.json() # Uso dados = consultar_empresa("12.345.678/0001-99", nivel="intermediaria") print(f"Empresa: {dados['empresa']['razao_social']}") print(f"Sócios: {len(dados['socios'])} registrados")
# PowerShell 7+ — Invoke-RestMethod nativo $ApiKey = "SUA_API_KEY" $Cnpj = "12345678000199" $Nivel = "intermediaria" # simples | intermediaria | auditoria $Headers = @{ "X-API-Key" = $ApiKey "Accept" = "application/json" } $Response = Invoke-RestMethod ` -Uri "https://api.vixdados.com.br/v1/public/cnpj/${Cnpj}?nivel=${Nivel}" ` -Method "GET" ` -Headers $Headers # Acesso aos dados Write-Host "Empresa:" $Response.empresa.razao_social Write-Host "Capital:" $Response.empresa.capital_social Write-Host "Sócios:" ($Response.socios).Count # Exportar para JSON $Response | ConvertTo-Json -Depth 10 | Out-File "empresa.json"
<?php // PHP 8+ — usando cURL nativo $apiKey = 'SUA_API_KEY'; $cnpj = preg_replace('/\D/', '', '12.345.678/0001-99'); $nivel = 'intermediaria'; $url = "https://api.vixdados.com.br/v1/public/cnpj/{$cnpj}?nivel={$nivel}"; $ch = curl_init($url); curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ "X-API-Key: {$apiKey}", 'Accept: application/json', ], CURLOPT_TIMEOUT => 10, ]); $body = curl_exec($ch); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch); if ($status !== 200) { throw new RuntimeException("Erro HTTP {$status}: {$body}"); } $dados = json_decode($body, true); echo "Empresa: " . $dados['empresa']['razao_social'] . PHP_EOL; echo "Sócios: " . count($dados['socios']) . PHP_EOL;
intermediaria{
"nivel": "intermediaria",
"creditos_consumidos": 3,
"empresa": {
"cnpj_basico": "12345678",
"razao_social": "EXEMPLO TECNOLOGIA LTDA",
"capital_social": 150000.00,
"porte": "01",
"natureza_juridica_codigo": "2062",
"natureza_juridica": "SOCIEDADE EMPRESÁRIA LIMITADA",
"qualificacao_responsavel": "SÓCIO-ADMINISTRADOR",
"ente_federativo_responsavel": null
},
"estabelecimentos": [
{
"cnpj_completo": "12345678000199",
"identificador_matriz_filial": "1",
"nome_fantasia": "EXEMPLO TECH",
"situacao_cadastral": "02",
"data_inicio_atividade": "2018-03-10",
"tipo_logradouro": "RUA",
"logradouro": "GETÚLIO VARGAS",
"numero": "100",
"complemento": null,
"bairro": "CENTRO",
"cep": "01310100",
"uf": "SP",
"municipio_nome": "SÃO PAULO",
"cnae_fiscal_principal": "6201501",
"cnae_descricao": "Desenvolvimento de programas de computador sob encomenda",
"motivo_situacao": null,
"ddd1": "11",
"telefone1": "999999999",
"ddd2": null,
"telefone2": null,
"email": "contato@exemplo.com.br"
}
],
"socios": [
{
"nome_socio": "JOÃO DA SILVA",
"identificador_socio": "1",
"cpf_cnpj_socio": null,
"qualificacao_socio_codigo": "49",
"qualificacao_descricao": "SÓCIO-ADMINISTRADOR",
"data_entrada_sociedade": "2018-03-10",
"pais_codigo": null,
"representante_legal_nome": null,
"representante_legal_cpf": null,
"representante_legal_qualificacao_codigo": null,
"faixa_etaria": "4"
}
],
"simples_nacional": {
"opcao_simples": "S",
"data_opcao_simples": "2018-04-01",
"data_exclusao_simples": null,
"opcao_mei": "N",
"data_opcao_mei": null,
"data_exclusao_mei": null
},
"concorrentes": [
{
"cnpj_basico": "98765432",
"razao_social": "CONCORRENTE DIGITAL LTDA",
"capital_social": 500000.00,
"porte": "03",
"nome_fantasia": null,
"situacao_cadastral": "02",
"data_inicio_atividade": "2015-06-01",
"municipio_nome": "SÃO PAULO",
"uf": "SP",
"cnae_descricao": "Desenvolvimento de programas de computador sob encomenda"
}
]
}
Tratamento de erros
A API retorna sempre um JSON com error, message e statusCode em caso de falha.
| Código | Status | Descrição |
|---|---|---|
| 200 | OK | Consulta realizada com sucesso |
| 400 | BAD_REQUEST | CNPJ inválido ou parâmetro nivel desconhecido |
| 401 | UNAUTHORIZED | Header X-API-Key ausente ou inválido |
| 402 | PAYMENT_REQUIRED | Saldo de créditos insuficiente para o nível solicitado |
| 404 | NOT_FOUND | CNPJ não encontrado na base da Receita Federal |
| 429 | RATE_LIMITED | Limite de requisições atingido: 100 req/min por API Key ou quota horária do plano (500/hora no Profissional, 2.000/hora no Empresarial) |
| 500 | INTERNAL_ERROR | Erro interno no servidor |
Crie sua conta grátis e receba créditos iniciais para testar a API agora mesmo. Sem cartão de crédito, sem prazo de expiração.