Documentação da API

https://cfo.com.br/api

Início rápido

Toda chamada é um GET com sua chave no header e os filtros na query string.

curl "https://cfo.com.br/api?resource=empresas&uf=SP&cnae=6201&dias=30&per_page=50" \
  -H "Authorization: Bearer cfo_live_SUA_CHAVE"

Autenticação

Envie a chave de uma destas formas (em ordem de preferência):

A chave aparece uma única vez na criação (guardamos só o hash). Perdeu? Gere outra no painel. Revogar uma chave a invalida na hora.

Limites & quota

• Consultas por mês — cada requisição com resultado conta 1. Requisições que retornam 0 registros não consomem cota (são estornadas). Ao estourar, a API responde 429 até a virada do mês.
• Registros por consulta — teto de linhas por requisição: o per_page é limitado ao seu plano (max_records) e, no máximo, a 1.000 em JSON / 50.000 em CSV. Use page para paginar além disso (cada página é 1 consulta).
• Restrição de IP — se sua conta tiver allowlist, só os IPs listados podem usar suas chaves (403 ip_not_allowed caso contrário).
• resource=meta não consome quota.

Toda resposta traz os headers:

X-RateLimit-Limit: 5000        # cota mensal (ou "unlimited")
X-RateLimit-Remaining: 4987    # quanto resta neste mês
X-RateLimit-Reset: 1751337600  # unix ts da virada do mês

GET?resource=empresas

Lista paginada de estabelecimentos pelos filtros. Período default = últimos 30 dias de abertura (use dias=0 para qualquer período). Consome 1 consulta.

Parâmetros

Resposta

{
  "meta": {
    "total": 458, "page": 1, "per_page": 50, "returned": 50,
    "total_pages": 10, "capped": false,
    "fonte": "dados abertos do governo federal",
    "quota": { "limit": 5000, "remaining": 4987 }
  },
  "data": [
    {
      "cnpj": "12.345.678/0001-90",
      "cnpj_raw": "12345678000190",
      "razao_social": "EXEMPLO TECNOLOGIA LTDA",
      "nome_fantasia": "Exemplo",
      "matriz": true,
      "situacao": { "codigo": 2, "descricao": "Ativa" },
      "data_inicio": "2026-06-02",
      "cnae_principal": { "codigo": "6201501", "descricao": "Desenvolvimento de programas..." },
      "porte": { "codigo": "01", "descricao": "Micro (ME)" },
      "capital_social": 50000.0,
      "endereco": { "logradouro": "RUA EXEMPLO", "numero": "100", "bairro": "Centro",
                    "municipio": "São Paulo", "uf": "SP", "cep": "01000000" },
      "contato": { "telefone": "(11) 999990000", "email": "[email protected]" }
    }
  ]
}

GET?resource=empresa&cnpj=…

Detalhe completo de um CNPJ (14 dígitos): cadastro, endereço, Simples/MEI e quadro societário. Consome 1 consulta.

curl "https://cfo.com.br/api?resource=empresa&cnpj=12345678000190" \
  -H "Authorization: Bearer cfo_live_SUA_CHAVE"

Retorna { "data": { … , "simples": {…}, "socios": [ … ] } }. CPF de sócio pessoa física vem mascarado na origem (padrão da RFB).

GET?resource=meta

Introspecção: limites e uso da sua conta + horizonte dos dados. Não consome quota.

curl "https://cfo.com.br/api?resource=meta" -H "Authorization: Bearer cfo_live_SUA_CHAVE"

Exportar CSV

Adicione format=csv para receber um arquivo (UTF-8 com BOM, separador ;, pronto pro Excel). O streaming permite páginas grandes — respeitando o teto da sua conta.

curl -L "https://cfo.com.br/api?resource=empresas&uf=RS&dias=60&per_page=1000&format=csv" \
  -H "Authorization: Bearer cfo_live_SUA_CHAVE" -o empresas.csv

Exemplos em código

const r = await fetch(
  "https://cfo.com.br/api?resource=empresas&uf=SP&cnae=6201&dias=30",
  { headers: { Authorization: "Bearer cfo_live_SUA_CHAVE" } }
);
const { meta, data } = await r.json();
console.log(meta.total, data.length);

import requests
r = requests.get("https://cfo.com.br/api", params={
    "resource": "empresas", "uf": "SP", "cnae": "6201", "dias": 30
}, headers={"Authorization": "Bearer cfo_live_SUA_CHAVE"})
payload = r.json()
print(payload["meta"]["total"], len(payload["data"]))

$ch = curl_init("https://cfo.com.br/api?resource=empresas&uf=SP&cnae=6201&dias=30");
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Authorization: Bearer cfo_live_SUA_CHAVE"],
]);
$res = json_decode(curl_exec($ch), true);
echo $res["meta"]["total"];

Erros

Erros vêm como { "error": { "code": "...", "message": "..." } } com o status HTTP correspondente.

Tabelas de código

Dados públicos (dados abertos do governo federal), atualizados com frequência. CFO não é um órgão público.