Documentação da API

Toda chamada à API pública exige header x-api-key: cnpj_live_…. Sem o header → HTTP 401.

Como criar a chave

1. Logar em /login (magic-link) — exige plano Pro ou superior.
2. Abrir /dashboard/api.
3. Clicar em "Criar chave" e dar um nome descritivo (ex: "CRM produção").
4. A chave plena aparece UMA única vez (formato cnpj_live_…). Copiar imediatamente pro gerenciador de senhas. Depois, só o prefixo (cnpj_live_t1G8…) fica visível — sem opção de re-revelar.
5. Revogar: também em /dashboard/api. Revogação é instantânea — qualquer integração começa a retornar 401 imediatamente.

Free e Starter usam só a UI (/buscar). API pública via x-api-key é Pro+. Ver planos.

Base URL: https://cnpjplatform.com.br/api

Três endpoints públicos. Todos exigem x-api-key. Headers e formato de resposta são iguais — só o path muda.

curl -H "x-api-key: cnpj_live_SUACHAVE" \
  https://cnpjplatform.com.br/api/v1/public/cnpj/33000167000101

// Node 20+ (fetch nativo, sem deps)
const res = await fetch(
  'https://cnpjplatform.com.br/api/v1/public/cnpj/33000167000101',
  { headers: { 'x-api-key': process.env.CNPJ_API_KEY } },
);
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const empresa = await res.json();
console.log(empresa.empresa.razaoSocial);
// → "PETROLEO BRASILEIRO S A PETROBRAS"

import os, requests

r = requests.get(
    "https://cnpjplatform.com.br/api/v1/public/cnpj/33000167000101",
    headers={"x-api-key": os.environ["CNPJ_API_KEY"]},
    timeout=10,
)
r.raise_for_status()
empresa = r.json()
print(empresa["empresa"]["razaoSocial"])
# → "PETROLEO BRASILEIRO S A PETROBRAS"

{
  "cnpj": "33000167000101",
  "cnpjBasico": "33000167",
  "empresa": {
    "razaoSocial": "PETROLEO BRASILEIRO S A PETROBRAS",
    "naturezaJuridica": 2038,
    "naturezaJuridicaDesc": "Sociedade de Economia Mista",
    "capitalSocial": "205431960490.52",
    "porte": "05"
  },
  "estabelecimento": {
    "matriz": true,
    "nomeFantasia": "PETROBRAS - EDISE",
    "situacaoCadastral": 2,
    "situacaoCadastralDesc": "ATIVA",
    "dataInicioAtividade": "1966-09-28",
    "uf": "RJ",
    "municipio": "RIO DE JANEIRO",
    "cep": "20031912",
    "email": null,
    "telefone": "21 32242000"
  },
  "socios": [ /* … lista de sócios qualificação RF … */ ],
  "score": {
    "commercial": 92,
    "risk": 88,
    "segment": "Energia / Óleo & Gás",
    "persona": "Holding"
  }
}

# UF + porte
curl -H "x-api-key: cnpj_live_SUACHAVE" \
  "https://cnpjplatform.com.br/api/v1/public/search?q=banco&uf=SP&porte=05&limit=20"

# Refinar por município (código da Receita Federal — 7107 = São Paulo,
# 6001 = Rio de Janeiro, 6291 = Campinas, 4123 = Belo Horizonte):
curl -H "x-api-key: cnpj_live_SUACHAVE" \
  "https://cnpjplatform.com.br/api/v1/public/search?uf=SP&municipios=7107&porte=01&limit=20"

# Lookup nome → código RF (público, sem auth, audit 2026-05-10):
curl "https://cnpjplatform.com.br/api/v1/lookup/municipios?q=belo"
# → {"items":[{"codigoRf":4123,"nome":"BELO HORIZONTE","uf":null}, ...]}

const params = new URLSearchParams({
  q: 'banco',
  uf: 'SP',
  // Município é array — append múltiplos códigos RF se quiser várias cidades
  municipios: '7107',  // São Paulo (código RF, NÃO IBGE)
  porte: '05',
  limit: '20',
});
const res = await fetch(
  `https://cnpjplatform.com.br/api/v1/public/search?${params}`,
  { headers: { 'x-api-key': process.env.CNPJ_API_KEY } },
);
const { items, total } = await res.json();
console.log(`${total} encontrados, mostrando ${items.length}`);

r = requests.get(
    "https://cnpjplatform.com.br/api/v1/public/search",
    headers={"x-api-key": os.environ["CNPJ_API_KEY"]},
    # municipios aceita lista — códigos da Receita Federal (não IBGE)
    params={"q": "banco", "uf": "SP", "municipios": [7107], "porte": "05", "limit": 20},
    timeout=10,
)
data = r.json()
print(f"{data['total']} encontrados, mostrando {len(data['items'])}")

{
  "total": 2857,
  "totalEstimated": true,
  "limit": 20,
  "offset": 0,
  "items": [
    {
      "cnpj": "00000000000191",
      "cnpjBasico": "00000000",
      "razaoSocial": "BANCO DO BRASIL SA",
      "nomeFantasia": "DIRECAO GERAL",
      "porte": "05",
      "capitalSocial": "120000000000.00",
      "uf": "DF",
      "municipio": "BRASILIA",
      "cnaePrincipal": 6422100,
      "score": {
        "commercial": 95,
        "risk": 96,
        "segment": "Bancos",
        "persona": "Holding"
      }
    },
    /* … mais 19 items … */
  ]
}

curl -H "x-api-key: cnpj_live_SUACHAVE" \
  https://cnpjplatform.com.br/api/v1/public/stats

const res = await fetch('https://cnpjplatform.com.br/api/v1/public/stats', {
  headers: { 'x-api-key': process.env.CNPJ_API_KEY },
});
const stats = await res.json();
console.log(`Release ${stats.release}: ${stats.counts.empresas.toLocaleString('pt-BR')} empresas`);

r = requests.get(
    "https://cnpjplatform.com.br/api/v1/public/stats",
    headers={"x-api-key": os.environ["CNPJ_API_KEY"]},
    timeout=5,
)
stats = r.json()
print(f"Release {stats['release']}: {stats['counts']['empresas']:,} empresas")

{
  "counts": {
    "empresas": 67635192,
    "estabelecimentos": 70833888,
    "estabelecimentosAtivos": 28564948,
    "socios": 27495940,
    "cnaes": 1359
  },
  "release": "2026-04",
  "releaseFinishedAt": "2026-05-02T08:44:57-03",
  "fetchedAt": "2026-05-08T16:24:48.382Z"
}

curl -X POST -H "x-api-key: cnpj_live_SUACHAVE" \
  -H "Content-Type: application/json" \
  https://cnpjplatform.com.br/api/v1/public/enrich-batch \
  -d '{"cnpjs": ["00000000000191", "33000167000101", "abc"]}'

const res = await fetch('https://cnpjplatform.com.br/api/v1/public/enrich-batch', {
  method: 'POST',
  headers: {
    'x-api-key': process.env.CNPJ_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    cnpjs: ['00000000000191', '33000167000101', 'abc'],
  }),
});
const { items, summary } = await res.json();
console.log(`Enriquecidas: ${summary.enriched} / Não encontradas: ${summary.not_found} / Inválidas: ${summary.invalid_cnpj}`);

r = requests.post(
    "https://cnpjplatform.com.br/api/v1/public/enrich-batch",
    headers={"x-api-key": os.environ["CNPJ_API_KEY"]},
    json={"cnpjs": ["00000000000191", "33000167000101", "abc"]},
    timeout=15,
)
data = r.json()
for item in data["items"]:
    if item["status_lookup"] == "enriched":
        print(item["empresa"]["razao_social"], item["empresa"]["uf"])
    else:
        print(f"{item['input']}: {item['status_lookup']}")

{
  "ok": true,
  "count": 3,
  "items": [
    {
      "input": "00000000000191",
      "cnpj": "00.000.000/0001-91",
      "status_lookup": "enriched",
      "empresa": {
        "razao_social": "BANCO DO BRASIL SA",
        "nome_fantasia": null,
        "uf": "DF",
        "municipio": "BRASILIA",
        "cnae_principal": 6422100,
        "porte": "05",
        "situacao": "ATIVA",
        "email": null,
        "telefone": "61 32932000",
        "capital_social": "120000000000.00",
        "data_inicio_atividade": "1966-08-01",
        "lead_score": {
          "commercial": 95,
          "risk": 96,
          "segment": "Bancos",
          "persona": "Holding"
        }
      }
    },
    {
      "input": "33000167000101",
      "cnpj": "33.000.167/0001-01",
      "status_lookup": "enriched",
      "empresa": { /* PETROLEO BRASILEIRO S A PETROBRAS … */ }
    },
    {
      "input": "abc",
      "status_lookup": "invalid_cnpj",
      "error_reason": "CNPJ inválido (formato ou DV)."
    }
  ],
  "summary": {
    "total": 3,
    "enriched": 2,
    "not_found": 0,
    "invalid_cnpj": 1
  },
  "tookMs": 142
}

# Últimos 30 dias, qualquer UF, primeiras 50:
curl -H "x-api-key: cnpj_live_SUACHAVE" \
  "https://cnpjplatform.com.br/api/v1/public/aberturas?dias=30&limit=50"

# Últimos 7 dias em SP, CNAE 6201500 (desenv. de software):
curl -H "x-api-key: cnpj_live_SUACHAVE" \
  "https://cnpjplatform.com.br/api/v1/public/aberturas?dias=7&uf=SP&cnae=6201500&limit=50"

# Últimos 30 dias na cidade de Campinas (código RF=6291, não IBGE):
curl -H "x-api-key: cnpj_live_SUACHAVE" \
  "https://cnpjplatform.com.br/api/v1/public/aberturas?dias=30&uf=SP&municipio=6291&limit=50"

const params = new URLSearchParams({
  dias: '30',
  uf: 'SP',
  cnae: '6201500',  // desenvolvimento de software
  limit: '50',
});
const res = await fetch(
  `https://cnpjplatform.com.br/api/v1/public/aberturas?${params}`,
  { headers: { 'x-api-key': process.env.CNPJ_API_KEY } },
);
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const { items } = await res.json();
for (const empresa of items) {
  console.log(empresa.data_inicio_atividade, empresa.razao_social, empresa.uf);
}

r = requests.get(
    "https://cnpjplatform.com.br/api/v1/public/aberturas",
    params={"dias": 7, "uf": "SP", "cnae": 6201500, "limit": 50},
    headers={"x-api-key": os.environ["CNPJ_API_KEY"]},
    timeout=15,
)
r.raise_for_status()
for emp in r.json()["items"]:
    print(emp["data_inicio_atividade"], emp["razao_social"], emp["uf"])

{
  "ok": true,
  "dias": 30,
  "limit": 50,
  "offset": 0,
  "items": [
    {
      "cnpj": "12.345.678/0001-90",
      "razao_social": "EXEMPLO SOFTWARE LTDA",
      "nome_fantasia": "Exemplo",
      "uf": "SP",
      "municipio": "SAO PAULO",
      "cnae_principal": 6201500,
      "porte": "01",
      "situacao": "ATIVA",
      "email": "contato@exemplo.com.br",
      "telefone": "11 999998888",
      "capital_social": "10000.00",
      "data_inicio_atividade": "2026-05-01",
      "matriz": true,
      "lead_score": {
        "commercial": 72,
        "risk": 65,
        "segment": "Tecnologia",
        "persona": "Pequena empresa"
      }
    }
    /* … até 50 itens (Pro) ou 200 (Enterprise) … */
  ],
  "tookMs": 38
}

Exportação grande (até 1M linhas no Enterprise) acontece via UI em /buscar — não via API pública. O fluxo é assíncrono (job na fila + polling) e os arquivos saem em CSV ou XLSX nativo.

CSV vs Excel (XLSX)

Como pedir o formato

A request POST de export aceita campo format:

POST /v1/exports
Content-Type: application/json

# CSV (default — compatibilidade com integrações antigas)
{
  "filters": { "uf": ["SP"], "porte": ["05"], "comEmail": true },
  "format": "csv",
  "maxRows": 5000
}

# XLSX nativo (abre direto no Excel/Google Sheets/LibreOffice)
{
  "filters": { "uf": ["SP"], "porte": ["05"], "comEmail": true },
  "format": "xlsx",
  "maxRows": 5000
}

Sem o campo format, o default é "csv" (compatibilidade com integrações antigas). Setar "format": "xlsx" gera um .xlsx nativo (Excel aceita sem conversão).

Score nas colunas: regra honesta

Lead Score é determinístico — calculado em SQL puro sobre dados públicos da Receita Federal. Sem rede neural, sem LLM, sem caixa-preta. Detalhes: FAQ.

Limite por plano (export via UI)

• Free: 100 linhas/mês · max 100 linhas/export · CSV ou XLSX (sem score)
• Starter: 10.000 linhas/mês · max 5.000 linhas/export · CSV ou XLSX (sem score)
• Pro: 200.000 linhas/mês · max 50.000 linhas/export · CSV ou XLSX (com score)
• Enterprise: 5M linhas/mês · max 1M linhas/export · CSV ou XLSX (com score)

Subir um arquivo com sua lista de CNPJs e receber de volta o mesmo arquivo enriquecido com razão social, situação, CNAE, UF, município, capital social e — para Pro+ — Lead Score. Ideal para quem já tem uma base própria e quer cruzar com a Receita Federal sem buscar CNPJ por CNPJ.

Disponibilidade por plano

• Free: bulk upload NÃO incluso (rota retorna 402 plan_required com upgrade pra Starter).
• Starter: 500 linhas/mês · 500 por job · arquivo até 10 MB.
• Pro: 5.000 linhas/mês · 2.000 por job · arquivo até 10 MB · inclui colunas de Lead Score no output.
• Enterprise: 20.000 linhas/mês · 5.000 por job · arquivo até 10 MB · inclui colunas de Lead Score.

Como subir

1. Logar em /login (magic-link).
2. Abrir /dashboard/enriquecer.
3. Arrastar o arquivo CSV ou XLSX. A primeira linha precisa ter um header chamado cnpj (case-insensitive).
4. O job processa em background. Você acompanha pelo status ("Na fila" → "Processando" → "Pronto") e baixa o resultado quando terminar.

Formatos

status_lookup por linha

O output marca cada linha com um dos três valores. Linhas inválidas não derrubam o job — você recebe o arquivo completo e revisa o que falhou.

• enriched — CNPJ válido + encontrado na base RF; colunas preenchidas.
• not_found — CNPJ válido (DV módulo-11 OK) mas não consta na base RF (pode ter sido baixado antes da última release; coluna error_reason traz o motivo).
• invalid_cnpj — não passou no check de 14 dígitos ou DV; error_reason mostra o que veio no campo.

Cota mensal

Audit-pos-Bulk-Upload Fase B (2026-05-08): a cota é compartilhada entre exports e enriquecimento. O backend soma export_jobs.rows_written + enrich_jobs.ok_rows (apenas jobs status='done'), ambos do mês corrente, e compara com o cap do plano. Você vê o breakdown na tela de /dashboard/enriquecer.

• Apenas enriched conta pra cota — linhas not_found e invalid_cnpj NÃO bilham. Você só paga pelo lookup com sucesso.
• Jobs failed/cancelled NÃO contam. Falha de worker não é cobrada.
• Tombstones contam (anti-abuse). Apagar um job done não devolve cota — mesma lógica do export.

Segurança

• Não aceita .xlsm (planilhas com macros) — bloqueado por segurança.
• Magic-byte check — extensão renomeada não engana o detector (PDF/JPEG disfarçados de CSV são rejeitados).
• Anti zip-bomb — XLSX com inflação > 100× do tamanho do upload é bloqueado.
• Anti formula injection — qualquer célula que comece com =, +, -, @ recebe prefixo ' no output (Excel renderiza como texto).
• CSV linha > 10 KB rejeitada (defesa DoS via linha gigante).
• Arquivo de upload é descartado logo após o processamento. O arquivo enriquecido (output) expira em 7 dias e é removido automaticamente.
• Download é por sessão — outro usuário tentar baixar seu arquivo via token recebe 404.

Onde abrir

/dashboard/enriquecer (logado, plano Starter ou superior). Dúvidas operacionais — formato esperado, o que fazer com not_found, como dividir arquivo grande em jobs menores — /faq.

Buscas salvas (atalho de filtros)

Buscas salvas são recurso do dashboard, não da API pública. A rota /v1/saved-searches exige sessão de cookie e NÃO aceita x-api-key nesta versão. Salve filtros que usa com frequência em /buscar clicando em "Salvar busca", e gerencie em /dashboard/buscas-salvas.

Salvar combinações de filtros pra reaplicar depois. Recurso exclusivo do dashboard — não é endpoint da API pública nesta versão. A rota /v1/saved-searches exige sessão de cookie e NÃO aceita x-api-key nem Authorization Bearer.

Limites por plano

• Free: 1 busca salva.
• Starter: 5 buscas salvas.
• Pro: 20 buscas salvas.
• Enterprise: 100 buscas salvas.

Como usar

1. Logar em /login.
2. Abrir /buscar, montar combinação de filtros (UF, CNAE, capital, abertura, etc.).
3. Clicar em "Salvar busca" ao lado de "Exportar". Dar um nome (1–80 caracteres) e confirmar.
4. Gerenciar as buscas salvas em /dashboard/buscas-salvas — aplicar, renomear, apagar.

Endpoints (cookie-only)

Reusáveis pelo SPA do dashboard. NÃO aceitam x-api-key — qualquer chamada com API key recebe 401. Cliente curl/server-to-server via Bearer JWT também é rejeitado.

• GET /v1/saved-searches — lista buscas ativas + cota do plano.
• POST /v1/saved-searches — cria com { name, filters }.
• PATCH /v1/saved-searches/:id — renomeia ou atualiza filters.
• POST /v1/saved-searches/:id/touch — atualiza last_used_at (Aplicar).
• DELETE /v1/saved-searches/:id — soft-delete (devolve slot).

O que NÃO está aqui

• Sem alerta por email quando algo muda na base.
• Sem cron / scheduler rodando suas buscas em background.
• Sem notificação automática via WhatsApp / push / Slack.
• Sem export agendado a partir de busca salva.

Se você precisa disso pra prospecção contínua, hoje a alternativa é: agendar um cron do seu lado que chame a API pública (/v1/public/search) com os mesmos filtros — assim você controla cadência, formato e onde mandar. Buscas salvas ficam pro fluxo manual no dashboard.

Pra acelerar o setup local, baixe a collection Postman pronta — tem os 3 endpoints + variáveis configuradas ({{api_key}}, {{base_url}}):

Baixar Postman collection (.json)

Insomnia também importa collections Postman direto (File → Import → escolher o JSON). Não precisamos manter format próprio.