Início rápido da API de CNPJ

Antes de começar

Você precisa de uma conta num plano pago com assinatura ativa. A API faz parte do plano, sem custo à parte, e cada requisição admitida conta 1 chamada da cota do mês, mesmo quando a resposta é 404. Veja a cota de cada plano.

Fazer isso nos primeiros 8 dias encerra a garantia da primeira assinatura. Ver regra

1. Crie o token

No app, abra Configurações › Integrações › Tokens da API.
Clique em Novo token.
Em Nome do Token, diga onde ele será usado, por exemplo Integração Produção.
Escolha a Validade do Token e clique em Criar Token.
Copie o token na hora: ele aparece uma vez só.

As validades e o que fazer quando o token vaza estão em Autenticação.

2. Guarde o token

Deixe o token numa variável de ambiente. Os exemplos abaixo leem OPORTUNIDADOS_API_TOKEN:

Terminal

export OPORTUNIDADOS_API_TOKEN="seu_token_aqui"

Em toda chamada, o token vai no cabeçalho:

Cabeçalho

Authorization: Bearer seu_token_aqui

3. Consulte um CNPJ

A ficha de uma empresa fica em GET /api/v1/brazilian_companies/{cnpj}/company. Envie o CNPJ com 14 caracteres, sem pontos, barras nem hífen, e troque 12345678000190 pelo CNPJ que você quer consultar.

cURL

curl "https://app.oportunidados.com.br/api/v1/brazilian_companies/12345678000190/company" \
  -H "Authorization: Bearer $OPORTUNIDADOS_API_TOKEN" \
  --max-time 30

Python

Usa a biblioteca requests (pip install requests).

Python

import os
import requests

API_TOKEN = os.environ["OPORTUNIDADOS_API_TOKEN"]
BASE_URL = "https://app.oportunidados.com.br/api/v1"


def consultar_cnpj(cnpj):
    resposta = requests.get(
        f"{BASE_URL}/brazilian_companies/{cnpj}/company",
        headers={"Authorization": f"Bearer {API_TOKEN}"},
        timeout=30,
    )
    if resposta.status_code == 404:
        return None
    resposta.raise_for_status()
    return resposta.json()


ficha = consultar_cnpj("12345678000190")
if ficha:
    print(ficha["company"]["razao_social"])
    print(len(ficha["socios"]), "sócios")

JavaScript

Roda no Node.js 18 ou mais novo, com o fetch nativo, num arquivo .mjs.

JavaScript (.mjs)

const API_TOKEN = process.env.OPORTUNIDADOS_API_TOKEN;
const BASE_URL = "https://app.oportunidados.com.br/api/v1";

async function consultarCnpj(cnpj) {
  const resposta = await fetch(`${BASE_URL}/brazilian_companies/${cnpj}/company`, {
    headers: { Authorization: `Bearer ${API_TOKEN}` },
    signal: AbortSignal.timeout(30000),
  });
  if (resposta.status === 404) return null;
  if (!resposta.ok) throw new Error(`HTTP ${resposta.status}: ${await resposta.text()}`);
  return resposta.json();
}

const ficha = await consultarCnpj("12345678000190");
if (ficha) {
  console.log(ficha.company.razao_social);
  console.log(ficha.socios.length, "sócios");
}

4. O que volta

Com 200, a resposta é um JSON com quatro seções:

Trecho da resposta

{
  "company": { "cnpj": "12345678000190", "razao_social": "EMPRESA EXEMPLO LTDA", "uf": "SP" },
  "socios": [ { "nome_socio": "JOAO SILVA", "cnpj_cpf_socio": "***456789**" } ],
  "contatos_extras": [],
  "contexto": { "empresas_mesmo_cnae_cidade": 412 }
}

Cada campo está em Campos da ficha. Se a resposta não for 200, veja Erros e retentativas.

Próximos passos

Contar empresas e obras de um recorte: Endpoints do token.
Planejar o volume do mês: Cota e limites.
Usar a base num assistente de IA, sem programar: MCP.

Referência interativa: Swagger do app, com todos os parâmetros e exemplos de resposta.