Carregando VixDados
REST API OpenAPI / Swagger 70M+ CNPJs Auditoria Campo a Campo <50ms Resposta Dados Receita Federal Histórico Evolutivo 100 req/min · 500–2k req/hora REST API OpenAPI / Swagger 70M+ CNPJs Auditoria Campo a Campo <50ms Resposta Dados Receita Federal Histórico Evolutivo 100 req/min · 500–2k req/hora
VixDados

API REST

Documentação
Completa da API

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

Autenticação

Toda requisição deve incluir sua API Key no header X-API-Key.

Obtendo sua 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_.

Criar conta grátis

Rate Limiting

O rate limit opera em duas camadas independentes. Ultrapassar qualquer uma resulta em 429 Too Many Requests.

1 Por API Key — janela de 1 minuto

Todas as chaves têm um limite fixo de 100 req/min. Aplica-se independentemente do plano contratado.

2 Por assinante — janela de 1 hora

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):

X-RateLimit-Limit 500 (ou 2000)
X-RateLimit-Remaining 487

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.

Boas práticas de segurança

  • Nunca exponha sua chave em código client-side
  • Use variáveis de ambiente no servidor
  • Rotacione a chave periodicamente no painel
  • Monitore o uso na dashboard de API Keys
requisição autenticada
# 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
resposta erro 401
{
  "error": "UNAUTHORIZED",
  "message": "API Key ausente ou inválida",
  "statusCode": 401
}

Profundidade de dados

Níveis de Consulta

Escolha o nível de detalhe conforme sua necessidade. Cada nível consome uma quantidade diferente de créditos.

Básico
simples
1
crédito

Dados cadastrais atuais da empresa e todos os seus estabelecimentos registrados na Receita Federal.

Dados da empresa (empresa)
Todos os estabelecimentos (estabelecimentos)
Sócios e quadro societário
Simples Nacional / MEI
Histórico de alterações
?nivel=simples
MAIS USADO
Intermediário
intermediaria
3
créditos

Tudo do nível básico mais sócios, status no Simples Nacional e lista de concorrentes por CNAE.

Dados da empresa + estabelecimentos
Quadro societário (socios)
Simples Nacional / MEI (simples_nacional)
Empresas concorrentes (concorrentes)
Histórico de alterações
?nivel=intermediaria
Auditoria
auditoria
5
créditos

Dados completos + histórico campo a campo de cada alteração registrada + mapeamento de empresas colocalizadas no mesmo endereço.

Tudo do nível Intermediário
Histórico de eventos (historico.eventos)
Endereço enriquecido (endereco_inteligente)
Linha do tempo de sócios
Evolução de capital social
?nivel=auditoria

Endpoint

Referência da API

Um único endpoint para consultar qualquer empresa brasileira.

GET /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.

Parâmetros

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_...

Campos da Resposta

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

Exemplos de Código

Copie e cole. Substitua SUA_API_KEY e CNPJ pelos seus valores reais.

consulta nível auditoria — cURL
# 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
consulta.js — Node.js 18+
// 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);
consulta.py — Python 3.8+
# 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")
consulta.ps1 — PowerShell 7+
# 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"
consulta.php — PHP 8+
<?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;

Exemplo de Resposta — nível intermediaria

200 OK — application/json
{
  "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

Códigos HTTP

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
VixDados

Pronto para integrar?

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.