Como criar token de API e fazer sua primeira consulta de CNPJ

Passo a passo: gere seu token, autentique via Bearer, consulte um CNPJ. Exemplos prontos em cURL, Python, JavaScript e Ruby.

Como criar sua chave de API

A chave de API é sua credencial de autenticação para realizar consultas programáticas ao banco de dados da Oportunidados. Este processo é simples e está disponível diretamente na sua conta do programa.

Passo 1 — Acesse sua conta: Faça login no programa Oportunidados através do site app.oportunidados.com.br utilizando seu e-mail e senha cadastrados. Certifique-se de que sua assinatura está ativa, pois as requisições de API já estão incluídas no seu plano sem custos adicionais.

Passo 2 — Navegue até a área de API: No menu principal do programa, localize e clique na opção "API de CNPJ". Esta seção contém todas as ferramentas necessárias para gerenciar suas credenciais de acesso à API.

Passo 3 — Gere sua chave de acesso: Na área de API, você encontrará o botão "Gerenciar Tokens da API". Ao clicar, o sistema criará automaticamente uma chave única e exclusiva para sua conta. Escolha um nome descritivo para identificar o token (por exemplo: "Integração Produção" ou "Ambiente de Testes") e defina o período de expiração ou selecione a opção de token permanente.

Importante: Apenas usuários com permissão de administrador de faturamento podem criar tokens de API. O token digest é armazenado de forma segura usando hash SHA256.

Passo 4 — Armazene sua chave com segurança: Após a geração, sua chave será exibida na tela. É fundamental que você copie e armazene esta chave em um local seguro. Nunca compartilhe sua chave de API publicamente ou a inclua diretamente em código-fonte disponibilizado publicamente (como repositórios GitHub públicos). Utilize variáveis de ambiente ou sistemas de gerenciamento de segredos em seus projetos.

Gerenciamento de Tokens

• Tokens podem ser ativados ou desativados a qualquer momento na página de gerenciamento
• Tokens são automaticamente invalidados se a conta for suspensa por inadimplência
• Tokens podem ter data de expiração definida ou serem permanentes
• Recomendamos criar tokens diferentes para cada ambiente (produção, staging, desenvolvimento)
• Rotacione tokens periodicamente como medida de segurança
• Desative tokens que não estão sendo utilizados

Como fazer requisições

Fazer requisições à API de CNPJ da Oportunidados é um processo direto que segue padrões RESTful amplamente utilizados no mercado.

Autenticação

Existem duas maneiras de autenticar suas requisições:

Bearer Token (Recomendado): Envie o token no cabeçalho HTTP Authorization:

Authorization: Bearer {seu_token_digest}

Query Parameter: Envie o token como parâmetro na URL:

?api_token={seu_token_digest}

Estrutura da Requisição

A URL base para todas as requisições é: https://app.oportunidados.com.br

O endpoint principal para consulta de empresas segue este padrão:

GET /api/v1/brazilian_companies/{cnpj}/company

Onde {cnpj} deve ser substituído pelo número do CNPJ com 14 dígitos numéricos, sem pontos, barras ou hífens.

Exemplo em cURL

#!/bin/bash
API_TOKEN="seu_token_aqui"
CNPJ="12345678000190"
curl -X GET "https://app.oportunidados.com.br/api/v1/brazilian_companies/${CNPJ}/company" \
-H "Authorization: Bearer ${API_TOKEN}" \
-H "Content-Type: application/json" \
-w "\nHTTP Status: %{http_code}\n" \
--max-time 30

Exemplo em Python

import requests
import os
API_TOKEN = os.environ.get('OPORTUNIDADOS_API_TOKEN')
BASE_URL = 'https://app.oportunidados.com.br'
def get_company(cnpj):
url = f'{BASE_URL}/api/v1/brazilian_companies/{cnpj}/company'
headers = {
'Authorization': f'Bearer {API_TOKEN}'
}
try:
response = requests.get(url, headers=headers, timeout=30)
response.raise_for_status()
return response.json()
except requests.exceptions.HTTPError as e:
print(f'HTTP Error: {e.response.status_code}')
print(f'Message: {e.response.json()}')
return None
except requests.exceptions.Timeout:
print('Request timeout')
return None
# Uso
data = get_company('12345678000190')
if data:
print(f"Razão Social: {data['company']['razao_social']}")
print(f"Número de sócios: {len(data['socios'])}")

Exemplo em JavaScript

const API_TOKEN = process.env.OPORTUNIDADOS_API_TOKEN;
const BASE_URL = 'https://app.oportunidados.com.br';
async function getCompany(cnpj) {
const url = `${BASE_URL}/api/v1/brazilian_companies/${cnpj}/company`;
try {
const response = await fetch(url, {
headers: {
'Authorization': `Bearer ${API_TOKEN}`
},
timeout: 30000
});
if (!response.ok) {
const error = await response.json();
throw new Error(`HTTP ${response.status}: ${error.message}`);
}
return await response.json();
} catch (error) {
console.error('Error fetching company:', error);
return null;
}
}
// Uso
getCompany('12345678000190')
.then(data => {
if (data) {
console.log('Razão Social:', data.company.razao_social);
console.log('Número de sócios:', data.socios.length);
}
});

Exemplo em Ruby

require 'net/http'
require 'json'
require 'uri'
API_TOKEN = ENV['OPORTUNIDADOS_API_TOKEN']
BASE_URL = 'https://app.oportunidados.com.br'
def get_company(cnpj)
uri = URI("#{BASE_URL}/api/v1/brazilian_companies/#{cnpj}/company")
request = Net::HTTP::Get.new(uri)
request['Authorization'] = "Bearer #{API_TOKEN}"
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https', read_timeout: 30) do |http|
http.request(request)
end
case response
when Net::HTTPSuccess
JSON.parse(response.body)
else
error = JSON.parse(response.body)
puts "Error #{response.code}: #{error['message']}"
nil
end
rescue StandardError => e
puts "Exception: #{e.message}"
nil
end
# Uso
data = get_company('12345678000190')
if data
puts "Razão Social: #{data['company']['razao_social']}"
puts "Número de sócios: #{data['socios'].length}"
end