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"

URLs

Todos os recursos aceitam duas formas equivalentes — a clássica por querystring e o caminho REST introduzido em 08/2026 (usado por marketplaces e ferramentas que importam OpenAPI):

O contrato completo em OpenAPI é público e gerado do código (nunca diverge do comportamento real): /api/v1/openapi (3.1) · ?spec=3.0 (3.0.3, para importadores). Health check sem autenticação: GET /api/v1/ping.

Autenticação

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

Além da chave, a API aceita token OAuth (cfo_at_…) no mesmo header Authorization: Bearer — é o que os agentes de IA usam. Veja MCP.

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

Seu plano tem quatro réguas mensais, cada uma com contador próprio (numa conta com operadores, o pool é do contrato — compartilhado entre todos os logins):

• Buscas por mês — cada requisição de resource=empresas com resultado conta 1. Requisições que retornam 0 registros não consomem (são estornadas). Ao estourar, a API responde 429 quota_exceeded até a virada do mês.
• Leads revelados por mês — na lista, e-mail e telefone saem mascarados (fin***@emp***.com.br, (51) 9****-**34). Revelar o contato de 1 empresa = 1 lead: adicione reveal=1 à busca. O estouro é parcial-gracioso: a resposta é 200, revela até onde o saldo alcança na ordem das linhas e mascara o resto com contato_mascarado: "cota". Empresa revelada (ou com dossiê consultado) fica aberta por 30 dias para o mesmo usuário, sem novo consumo.
• Empresas com dossiê integrado por mês — resource=empresa consome 1 por empresa nova no mês; reabrir a mesma empresa dentro do mês-calendário é grátis (vale para o contrato inteiro). resource=screening consome desta mesma régua: 1 por CNPJ encontrado e novo no mês. Ao estourar: 429 empresa_quota_exceeded.
• Registros por busca — 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 busca).
• 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 e resource=dl não consomem quota.

Toda resposta traz os headers das três réguas de consumo:

X-RateLimit-Limit: 2000        # buscas/mês (ou "unlimited")
X-RateLimit-Remaining: 1987    # buscas restantes neste mês
X-RateLimit-Reset: 1751337600  # unix ts da virada do mês
X-Leads-Limit: 10000           # leads/mês
X-Leads-Remaining: 9958        # leads restantes
X-Empresas-Limit: 1000         # empresas com dossiê/mês
X-Empresas-Remaining: 993      # empresas restantes

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 busca. E-mail e telefone saem mascarados por padrão — reveal=1 revela os contatos da página consumindo leads do plano (1 por empresa; linha já aberta pela janela de 30 dias não consome de novo).

Parâmetros

Exemplos — empresas em que uma pessoa é sócia, empresas titulares de uma marca, e construtoras com obra ativa:

curl "https://cfo.com.br/api?resource=empresas&termo=s%C3%B3cio:JOAO%20DA%20SILVA&dias=0" \
  -H "Authorization: Bearer cfo_live_SUA_CHAVE"
curl "https://cfo.com.br/api?resource=empresas&termo=marca:NATURA&dias=0" \
  -H "Authorization: Bearer cfo_live_SUA_CHAVE"
curl "https://cfo.com.br/api?resource=empresas&cnae=4120&obra=sim&uf=SP&dias=0" \
  -H "Authorization: Bearer cfo_live_SUA_CHAVE"

Resposta

{
  "meta": {
    "total": 458, "total_capped": false,
    "page": 1, "per_page": 50, "returned": 50,
    "total_pages": 10, "capped": false,
    "fonte": "dados abertos do governo federal",
    "quota": { "limit": 2000, "remaining": 1987 }
  },
  "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) 9****-**00", "email": "con***@exe***.com.br" },
      "contato_mascarado": "janela"
    }
  ]
}

Contatos: linha mascarada traz contato_mascarado com o motivo — "janela" (empresa fora da sua janela de 30 dias; use reveal=1) ou "cota" (saldo de leads do mês esgotado). Linha com contato aberto (revelada agora ou dentro da janela) não traz o campo. A máscara é aplicada no servidor — o contato completo não trafega em linha mascarada. Em CSV, linhas mascaradas geram um aviso no rodapé do arquivo.

Em buscas muito amplas (período aberto ou busca por termo) o total é capado: a partir de ~2.000 ele deixa de ser exato e vira um piso — leia como “2.000+”. Nesse caso total_capped vem true e a lista traz os registros mais recentes. É uma proteção anti-DoS (evita COUNT sobre a base inteira), não um erro. Refine os filtros para uma contagem exata.

GET?resource=empresa&cnpj=…

Detalhe completo de um CNPJ: cadastro, endereço, Simples/MEI e quadro societário. Consome 1 empresa com dossiê (régua própria, não busca) — e só na primeira consulta da empresa no mês: reabrir o mesmo CNPJ dentro do mês-calendário é grátis para o contrato inteiro. Consultar também abre a janela de 30 dias da empresa (downloads via resource=dl e contato aberto na lista). O cnpj tem 14 caracteres — aceita o numérico legado ou o novo formato alfanumérico (12 alfanuméricos + 2 dígitos, RFB IN 2.229/2024, válido a partir de jul/2026); pontuação é ignorada.

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

Retorna { "data": { … , "simples": {…}, "socios": [ … ], "sinais": {…} } }. CPF de sócio pessoa física vem mascarado na origem (padrão da RFB). Cada sócio traz tipo, nome, documento (CNPJ da sócia PJ; CPF mascarado da PF), qualificacao, faixa_etaria e data_entrada.

O endereco aqui é mais completo que o da busca: além de logradouro/número/bairro/município/UF/CEP, traz complemento e codigo_ibge — o código IBGE do município com 7 dígitos, pronto para uso fiscal (ex.: campo cMun do DPS na emissão de NFS-e).

codigo_ibge pode vir null, e isso não é falha de consulta: (a) o estabelecimento é no exterior — a RFB o registra com o município 9707 EXTERIOR, que não tem contrapartida no IBGE porque não há município brasileiro (é o caso de 172,5 mil estabelecimentos, quase todos matrizes de empresas estrangeiras); ou (b) o código de município veio malformado na origem da RFB e não corresponde a nenhum município (47 estabelecimentos em toda a base, ~0,00006%). Nos demais o campo sempre resolve: o de-para RFB→IBGE cobre os 5.571 municípios, sincronizado mensalmente da API de localidades do IBGE.

cnae_secundario: lista (possivelmente vazia) de { "codigo", "descricao" } com todas as atividades secundárias registradas na RFB.

regime_tributario: objeto { "regime", "fonte", "ano_referencia" }. Para optantes, regime é "MEI" ou "Simples Nacional" (opção vigente na base do CNPJ; ano_referencia nulo). Para não-optantes, vem a forma de tributação declarada na ECF (dado aberto da RFB): "Lucro Real", "Lucro Presumido", "Lucro Arbitrado" ou imune/isenta — com ano_referencia do último ano-calendário publicado (defasagem típica de ~2 anos, ex.: em 2026 a referência é 2024). Empresa não-optante sem ECF publicada recebe o rótulo genérico "Lucro Presumido ou Real (não optante do Simples; sem ECF pública)".

Bloco sinais (KYC · dado aberto)

Presente só quando a empresa tem algum sinal (negativo ou positivo — inclui registro no INPI ou no cadastro do BCB). Camada de compliance/KYC agregada dos dados abertos do governo federal. Leitura honesta: cada item é indício, não prova, é auditável na fonte, e traz fonte + data. Não há score nem nota — só a contagem e os itens; a decisão é de quem consulta. Sanção com prazo já vencido vem com vigente: false (histórico, não alerta ativo).

"sinais": {
  "aviso": "Indício, não prova. Dado aberto/auditável...; sem score.",
  "contagem": { "negativos": 1, "positivos": 0 },
  "negativos": {
    "divida_ativa": false, "divida_ativa_valor": null, "divida_ajuizada": false,
    "inidonea_ceis": true, "punida_cnep": false,
    "sancao_vigente": true, "sancao_multa": null,
    "sancoes": [
      { "cadastro": "CEIS", "categoria": "Impedimento...", "orgao": "...",
        "processo": "27222/2021", "data_inicio": "2022-06-20",
        "data_final": "2027-06-20", "valor_multa": null, "vigente": true }
    ],
    "dividas": [
      { "tipo_debito": "NAO_PREV", "situacao": "Em cobrança",
        "receita_principal": "...", "data_inscricao": "2021-03-10",
        "ajuizado": false, "valor": 12345.67 }
    ]
  },
  "parcelamento_rfb": {
    "total": 2, "saldo_devedor": 18234.56,
    "itens": [
      { "programa": "especial_sn", "modalidade": "RELP-SN",
        "adesao": "2022-05-01", "qtde_parcelas": 77, "fim_estimado": "2028-10-01",
        "valor_parcelado": 22412.08, "saldo_devedor": 5907.79 }
    ]
  },
  "positivos": {
    "bndes": false, "bndes_total": null, "finep": false,
    "fornecedor_gov": false, "pncp_total": null, "aeronave": false,
    "cvm": false, "anp": false,
    "inpi": { "marcas": 567, "patentes": 5, "desenhos_industriais": 0, "softwares": 24 },
    "bcb":  { "tipo": "Banco Múltiplo", "situacao": "Autorizada em Atividade", "pix": true },
    "dominios": 12, "veiculos": null, "obras": 8
  },
  "fontes": ["CGU/Portal da Transparência (CEIS/CNEP)", "PGFN (Dívida Ativa)", "BNDES", "FINEP", "PNCP", "ANAC/RAB", "CVM", "ANP", "INPI", "BCB (entidades supervisionadas/Pix)", "ANM/SIGMINE (títulos minerários)", "ANM/CFEM (royalty mineral)", "Portal da Transparência (emendas parlamentares)", "Transferegov/SICONV (convênios)", "SIASG/Compras.gov.br (fornecedor federal)", "RFB — Parcelamentos de débitos"],
  "atualizado": "2026-07-01 22:23:11"
}

Sanções (CEIS/CNEP) vêm da CGU/Portal da Transparência; dívidas vêm da PGFN (Dívida Ativa da União). Cada lista traz até 50 itens, os mais relevantes primeiro. inpi resume marcas, patentes, desenhos industriais e programas de computador em nome da empresa (titular/depositante; fonte INPI) — null quando não há registro. bcb indica entidade do cadastro de supervisionadas do Banco Central (a situacao é a do cadastro e inclui autorizações encerradas) e se é participante do Pix/SPI — null quando fora do cadastro. Ausência de sinal ≠ idoneidade comprovada — significa apenas que nada foi encontrado nas bases abertas.

GET?resource=screening&cnpjs=…

Triagem KYC em lote: até 50 CNPJs por chamada, com os sinais agregados de cada um (alertas + capacidade). Aceita GET ou POST (form ou JSON). Cada item da lista pode ser o CNPJ completo de 14 caracteres (numérico ou alfanumérico; pontuação é ignorada) ou só a raiz de 8 (cnpj_basico) — a leitura é sempre por raiz, com razão social e situação da matriz.

curl "https://cfo.com.br/api?resource=screening&cnpjs=53113791000122,11396646000156" \
  -H "Authorization: Bearer cfo_live_SUA_CHAVE"

# ou POST com JSON (lista como array):
curl "https://cfo.com.br/api?resource=screening" \
  -H "Authorization: Bearer cfo_live_SUA_CHAVE" -H "Content-Type: application/json" \
  -d '{"cnpjs": ["53113791000122", "11396646000156"]}'

Custo: 1 empresa (régua de dossiês) por CNPJ encontrado e novo no mês — CNPJ não encontrado não conta, e CNPJ já consumido no mês do contrato (por screening ou por resource=empresa) não conta de novo: re-screening do mesmo portfólio dentro do mês custa 0. O campo meta.custo_empresas informa quantos foram cobrados na chamada. Se o saldo mensal não comportar os CNPJs novos do lote, a chamada retorna 429 empresa_quota_exceeded e nada é cobrado (o lote é negado inteiro — divida-o ou aguarde a virada).

Resposta

Uma entrada por CNPJ enviado, na mesma ordem. CNPJ inexistente na base (ou item inválido) vem como { "cnpj": "…", "found": false }. Empresa existente sem nenhum sinal vem com found: true e todos os flags false / contagens 0.

{
  "meta": {
    "aviso": "Indício, não prova. Dado aberto/auditável do governo federal; sanção vale pela vigência...; sem score.",
    "solicitados": 2, "encontrados": 2, "custo_empresas": 2,
    "fontes": ["CGU/Portal da Transparência (CEIS/CNEP)", "PGFN (Dívida Ativa)", "BNDES", "FINEP", "PNCP", "ANAC/RAB", "CVM", "ANP", "INPI", "BCB (entidades supervisionadas/Pix)", "ANM/SIGMINE (títulos minerários)", "ANM/CFEM (royalty mineral)", "Portal da Transparência (emendas parlamentares)", "Transferegov/SICONV (convênios)", "SIASG/Compras.gov.br (fornecedor federal)", "RFB — Parcelamentos de débitos"],
    "quota": { "limit": 2000, "remaining": 1987 },
    "empresas": { "limit": 1000, "remaining": 991 }
  },
  "data": [
    {
      "cnpj": "53113791000122",
      "cnpj_basico": "53113791",
      "found": true,
      "razao_social": "TOTVS S.A.",
      "situacao_cadastral": { "codigo": 2, "descricao": "Ativa" },
      "alertas": {
        "divida_ativa": { "flag": true, "valor": 30235487.48, "ajuizada": true },
        "ceis_vigente": false,
        "cnep_vigente": false,
        "sancao_multa": null
      },
      "capacidade": { "bndes": true, "finep": true, "gov": true, "aeronave": false,
                      "cvm": true, "anp": false, "inpi": true, "bcb": false },
      "neg_count": 1,
      "pos_count": 5
    },
    {
      "cnpj": "11396646000156",
      "cnpj_basico": "11396646",
      "found": true,
      "razao_social": "MARMORARIA NACIONAL COMERCIO DE ARTEFATOS DE CIMENTO E SERVICOS DE MAO DE OBRA LTDA",
      "situacao_cadastral": { "codigo": 2, "descricao": "Ativa" },
      "alertas": {
        "divida_ativa": { "flag": false, "valor": null, "ajuizada": false },
        "ceis_vigente": false,
        "cnep_vigente": true,
        "sancao_multa": 6865.99
      },
      "capacidade": { "bndes": false, "finep": false, "gov": false, "aeronave": false,
                      "cvm": false, "anp": false, "inpi": false, "bcb": false },
      "neg_count": 1,
      "pos_count": 0
    }
  ]
}

O screening é o resumo (flags do rollup, reconstruído a cada carga das fontes). Para o detalhe auditável — sanções item a item com órgão/processo/vigência, dívidas por natureza, marcas/patentes INPI, situação BCB/Pix e quadro societário — consulte resource=empresa de cada CNPJ que acender alerta. Ausência de sinal ≠ idoneidade comprovada: significa apenas que nada foi encontrado nas bases abertas na data da última carga.

GET?resource=dl&recurso=…&cnpj=…

Baixa uma seção detalhada de uma empresa que você consultou nos últimos 30 dias — no site ou pela API (resource=empresa). Não consome consulta: o acesso já foi pago pela consulta, e o consumo é unificado site + API (consultou no site hoje, baixa pela API amanhã). Se a empresa não estiver na janela de 30 dias, retorna 403 not_consulted.

recurso ∈ marcas, dominios, veiculos, obras, aeronaves, contratos, grupo, filiais, divida, sancoes, ibama. cnpj = 14 caracteres (numérico ou alfanumérico; pontuação ignorada). format=json (padrão) ou csv.

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

Retorna { "recurso": "marcas", "cnpj": "…", "count": N, "data": [ {…}, … ] } (até 50.000 linhas por seção). Com &format=csv devolve um CSV (mesmas colunas do download do site). Fluxo: consulte a empresa (site ou resource=empresa) → por 30 dias baixe qualquer seção dela por aqui, sem nova cobrança; consultar de novo renova a janela.

Cada seção também tem caminho próprio

As nove seções abaixo respondem igualmente em /api/v1/<seção>?cnpj=… — mesmo motor, mesma trava de 30 dias, mesma resposta, custo zero. Existem porque um caminho por seção é o que os marketplaces (e a maioria dos clientes gerados por OpenAPI) esperam:

curl "https://cfo.com.br/api/v1/dominios?cnpj=33000167000101" \
  -H "Authorization: Bearer cfo_live_SUA_CHAVE"

# equivalente a:
curl "https://cfo.com.br/api?resource=dl&recurso=dominios&cnpj=33000167000101" \
  -H "Authorization: Bearer cfo_live_SUA_CHAVE"

/api/v1/ + dominios, marcas, contratos, grupo, filiais, veiculos, obras, aeronaves, ibama.

divida e sancoes ficam fora dos caminhos próprios de propósito: elas já saem completas dentro do resource=empresa (bloco sinais.negativos), então não há o que buscar em separado — continuam disponíveis via ?recurso= para quem quiser só o CSV.

Chaves de marketplace têm tetos próprios

Chave emitida para um marketplace (RapidAPI) tem dois limites por requisição que não valem para a integração direta, porque lá a cobrança é por chamada: com reveal=1 a página traz no máximo 25 linhas (sem reveal, a página vai cheia), e o screening aceita no máximo 10 CNPJs por lote. Sua chave do painel continua com 1.000 registros por página e 50 CNPJs por lote.

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"

POST?resource=rotate_key

Rotaciona a própria chave: autentica com a chave atual e devolve uma nova. Não consome quota. Serve para trocar o segredo periodicamente ou reagir a uma suspeita de vazamento sem passar pelo painel.

# corte imediato (default): a chave antiga morre no mesmo instante
curl -X POST "https://cfo.com.br/api?resource=rotate_key" \
  -H "Authorization: Bearer cfo_live_SUA_CHAVE_ATUAL"

# com carência: a antiga continua valendo por 30 min (troca sem downtime)
curl -X POST "https://cfo.com.br/api?resource=rotate_key" \
  -H "Authorization: Bearer cfo_live_SUA_CHAVE_ATUAL" \
  -d "grace_minutes=30"

{
  "data": {
    "api_key": "cfo_live_a1b2c3…",          // única vez que a chave aparece
    "key_prefix": "cfo_live_a1b2c3…",
    "label": "producao",
    "rotated_at": "2026-08-05T21:30:00-03:00",
    "anterior": {
      "key_prefix": "cfo_live_9f8e7d…",
      "grace_minutes": 30,
      "valida_ate": "2026-08-05T22:00:00-03:00"   // null quando grace_minutes=0
    },
    "aviso": "Guarde agora: a chave não será exibida de novo…"
  }
}

grace_minutes (opcional, 0–1440): quanto tempo a chave anterior ainda funciona depois da rotação.

• 0 (default) — corte imediato: no instante em que a chamada retorna 200, a antiga já responde 401. Use quando estiver rotacionando por suspeita de vazamento — qualquer carência mantém quem tem a chave dentro pelo mesmo tempo.
• 1–1440(24h) — as duas chaves valem durante a janela: aplique a nova nos seus serviços com calma e a antiga se encerra sozinha no vencimento. Depois disso ela responde 401 com "code": "key_expired" e a hora exata em que venceu.

A chave em carência aparece no painel com o selo “expira dd/mm hh:mm” em vez de “ativa”, e pode ser revogada antes da hora pelo botão Revogar. Valor fora da faixa (ou não inteiro) devolve 400.

Guarde a resposta. O servidor só armazena o hash — se você perder o corpo desta chamada, não há como recuperar a chave; crie outra pelo painel (você não perde o acesso à conta, só àquela chave).

Só POST. Em GET a resposta traria o segredo numa requisição que costuma ser registrada em log/histórico/proxy, e um prefetch poderia disparar rotação sem intenção — por isso GET devolve 405. Limite de 5 rotações por hora por conta (429 acima disso), como proteção contra laço de integração. O label da chave é preservado.

Precisa de troca sem downtime (duas chaves válidas ao mesmo tempo)? Crie a segunda chave pelo painel, migre os serviços e revogue a antiga — o limite de chaves ativas do seu plano se aplica.

Auditoria. Toda rotação fica registrada: aparece no histórico da conta (aba Auditoria do painel) como apikey_rotacionada, com data, IP de origem e os prefixos da chave revogada e da nova — e também no log de chamadas da API. O segredo nunca é gravado: só o prefixo (primeiros caracteres) e o hash SHA-256.

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"];

MCP — para agentes de IA

O CFO expõe um servidor MCP (Model Context Protocol) em https://cfo.com.br/mcp: é assim que Claude, ChatGPT e outros agentes consultam a base sem você escrever código. Transporte Streamable HTTP, protocolo 2025-06-18, JSON-RPC.

Exige plano pago. Conta do plano gratuito recebe -32001 ao executar uma ferramenta. A descoberta (initialize, tools/list) é aberta — só a execução é restrita.

As três ferramentas

As ferramentas gastam a mesma cota da API REST — não existe régua separada para MCP.

Conectando com a sua chave

Em clientes que aceitam um header fixo (Claude Code, Cursor, Zed…):

{
  "mcpServers": {
    "cfo": {
      "url": "https://cfo.com.br/mcp",
      "headers": { "Authorization": "Bearer cfo_live_…" }
    }
  }
}

Conectando por OAuth

Clientes que não guardam header fixo — o conector remoto do Claude.ai, por exemplo — usam OAuth: você cola só a URL https://cfo.com.br/mcp, o cliente descobre o resto sozinho e abre uma tela de consentimento onde você entra com a sua conta do CFO e autoriza. Não há nada para configurar à mão.

Para quem implementa o cliente, os endpoints estão nos documentos de metadados:

O token de acesso (cfo_at_…) vale 1 hora; o de renovação, 30 dias, com rotação — cada renovação invalida o anterior. Reapresentar um código ou um token de renovação já usado é tratado como vazamento e revoga toda a família de tokens daquele cliente, que precisa autorizar de novo. Um token OAuth vale exatamente o que a sua conta vale: mesma cota, mesmos limites, mesma allowlist de IP.

Quando falta credencial, o /mcp responde 401 apontando o caminho — é o que permite ao cliente se virar sozinho:

WWW-Authenticate: Bearer realm="CFO", error="invalid_token",
  resource_metadata="https://cfo.com.br/.well-known/oauth-protected-resource/mcp"

Feeds JSON dos observatórios (sem chave)

Os observatórios — as páginas públicas de dado agregado — servem o mesmo resumo mensal em JSON, na mesma URL com .json no fim. Não exigem chave, não exigem cadastro e não consomem cota: é dado público sob licença aberta, publicado para um agente chamar o dado em vez de raspar a página.

curl -s https://cfo.com.br/dados.json                       # catálogo de todos os feeds
curl -s https://cfo.com.br/movimentacoes-empresariais-sc.json
curl -s "https://cfo.com.br/movimentacoes-empresariais-sc.json?ref=2026-07"  # outro mês

Feeds no ar

A URL do feed é sempre a da página humana + .json. A própria página anuncia o feed no <head> (<link rel="alternate" type="application/json">) e no JSON-LD schema.org/Dataset, como uma DataDownload de application/json.

Parâmetros

Campos da resposta

Cache e requisição condicional

Um mês não muda depois de calculado, então vale a pena não baixar duas vezes:

ETag: "43b12dcdec097e9f9f874fea2b22b1b61074627c"
Last-Modified: Thu, 10 Sep 2026 04:21:59 GMT
Cache-Control: public, max-age=3600, s-maxage=86400
Access-Control-Allow-Origin: *

Reenvie o ETag em If-None-Match e a resposta é 304 sem corpo. O feed também responde a HEAD e é liberado para fetch() de qualquer origem (CORS *).

Licença e citação

Os feeds estão sob CC BY 4.0, com atribuição a CFO (cfo.com.br). O dado bruto é público (Receita Federal, IBGE); o que se licencia é a compilação — o recorte mensal, as derivadas e a série, que só existem porque a versão anterior da base foi preservada antes da substituição pela Receita Federal. Forma sugerida de citar:

CFO (cfo.com.br), <dataset>, referência <mês>, acessado em <data>

Erros

Estes feeds são agregados: nenhuma empresa, sócio ou CNPJ é identificado. Para dado por empresa, é a API (com chave).

Erros

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

Durante a atualização mensal da base a API responde 503 maintenance com o header Retry-After (segundos). É um estado transitório de poucos minutos — repita a chamada após o intervalo indicado. Nenhuma requisição nesse período consome sua cota.

Tabelas de código

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