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):

A API REST usa chave de API. Os aplicativos de IA também podem usar OAuth no servidor MCP, com autorização pelo navegador. Tokens OAuth são exclusivos do 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). A paginação cobre os 50.000 registros mais recentes de cada busca: página que começa depois disso responde 400 page_out_of_range (sem consumir a busca) com a última página válida em max_page; refine os filtros para chegar aos demais.
• Buscas simultâneas — no máximo 2 requisições de resource=empresas (JSON ou CSV) em andamento ao mesmo tempo por contrato usam o índice de busca, somando todas as chaves, os operadores e o painel web. A 3ª simultânea (ou qualquer uma com o índice ocupado ou fora do ar) segue pela rota secundária: os filtros são os mesmos, a resposta é mais lenta, o total pode vir aproximado (total_capped) e a busca muito ampla pode terminar em 500 query_error (veja o tempo limite, abaixo). Integrações em lote rendem mais com as chamadas em série.
• Tempo limite — a busca que não termina a tempo responde 500 query_error e não é cobrada (o corpo do erro traz "charged": false). Ela só acontece na rota secundária, a que atende a busca quando o índice de busca não pode (filtro que o índice não tem, índice ocupado ou fora do ar). Da 3ª busca do mesmo usuário (o dono da chave ou do token; no painel, o login) que passa do tempo limite na mesma hora (contada a partir da 1ª) em diante, esse usuário fica 10 minutos sem a rota secundária: nesse intervalo, as buscas que o índice atende (a maioria) e a busca por CNPJ exato seguem normais, e a que precisaria da rota secundária responde 429 too_many_timeouts com Retry-After (segundos) e "applies_to": "user", sem consumir a cota. Com 10 na mesma hora somando os usuários do contrato (no máximo 3 de cada um), a pausa vale para o contrato inteiro ("applies_to": "contract"). Vale para JSON e CSV, a API e o painel juntos (no RapidAPI, a conta é a do assinante). Erro interno não conta. Refine a busca com período, UF, cidade ou situação antes de repetir.
• Restrição de IP da API REST — se sua conta tiver allowlist, só os IPs listados podem usar suas chaves na API REST (403 ip_not_allowed caso contrário). O MCP dispensa essa allowlist; bloqueios globais de IP continuam valendo.
• 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"
    }
  ]
}

Campos de cada linha (JSON)

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); só no MCP, também "teto_diario_mcp" (teto diário de leads da conexão atingido). 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.

Leia sempre total_capped: com false, total é a contagem exata da busca. Em buscas muito amplas (período aberto ou busca por termo) o total pode vir 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. total_pages conta só as páginas dentro da janela de 50.000 registros, mesmo quando total é maior.

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). Até 100 sócios. Cada sócio traz tipo, nome, documento (CNPJ da sócia PJ; CPF mascarado da PF; para a sócia estrangeira, o CNPJ dela quando o nome resolve para uma única empresa de natureza 2216, senão null), qualificacao, faixa_etaria, data_entrada, representante ({ "nome", "qualificacao" } do representante legal, ou null) e pais (só do sócio estrangeiro).

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 173.410 estabelecimentos na base de outubro/2026, em qualquer situação cadastral, quase todos matrizes de empresas estrangeiras; a contagem só das inscrições ativas, por natureza jurídica e país de domicílio, está em empresas estrangeiras com CNPJ no Brasil); ou (b) o código de município veio malformado na origem da RFB e não corresponde a nenhum município (47 estabelecimentos na base de setembro/2026, ~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)".

Blocos do dossiê além do cadastro

Os mesmos blocos que o dossiê do site mostra para a mesma conta e plano, com as mesmas regras (titulares com restrição de exibição continuam fora). Bloco sem dado vem null. Nas listas com contagem (total, ou o campo de contagem que a tabela indica, como operacoes, projetos, em_operacao, contagem e total_documentos), o número é o real mesmo quando os itens param no teto. As listas marcadas sem total na tabela (indicios_socio, participacoes_exterior, procuradores, historico, regulado, inpi_contratos e os registros do BCB, da Lista Suja e de grande devedor estadual) param no teto sem dizer quantos ficaram de fora. Com chave de marketplace, as listas que também são seção própria (filiais, grupo, aeronaves, dominios, obras, contratos, ibama) vêm só com o total e itens: null: a lista sai pelo caminho da seção, cobrado por chamada.

Cache do dia: o dossiê completo de uma empresa fica guardado até a meia-noite (horário de Brasília) e vale para todas as contas, até mudar a base, a fonte de algum bloco, uma restrição de exibição ou o código do serviço. A validade do e-mail (contato.email_invalido) é recalculada em todo pedido. A cobrança não muda: cada pedido reserva a cota de dossiês, registra a consulta (janela de 30 dias do dl) e conta no uso, venha o dossiê do cache ou não. Dossiê com parcial fica guardado só 5 minutos; dossiê em que a leitura de algum bloco falhou não fica guardado.

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. Nessas chaves, resource=meta traz os dados da base, a lista de recursos e um bloco account só com um aviso, sem limites nem uso: a chave é compartilhada entre os assinantes do anúncio.

GET?resource=consultadas

As empresas que você consultou: com dossiê (no site ou pela API) ou só com o contato revelado (lead). Mostra até quando o resource=dl vale para cada uma sem nova consulta. Não consome quota. Vale só para a chave do painel: chave de marketplace recebe 403 not_available, porque é compartilhada pelos assinantes do anúncio.

curl "https://cfo.com.br/api?resource=consultadas&tipo=dossie" -H "Authorization: Bearer cfo_live_SUA_CHAVE"

Parâmetros: tipo (dossie, lead ou omitido para os dois), page e per_page (até 500; padrão 100). Cada item traz cnpj, razao_social, tipo, primeira_em e ultima_em (do dossiê; null em linha só de lead), lead_em, vezes e dl_ate (até quando o download vale; null = consulte a empresa de novo). Só as suas linhas, sem IP; o dono de uma organização vê as dos operadores no painel da organização.

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.

Chave em carência não gera outra. Rotacionar uma chave que já tem prazo devolve 409: ela segue valendo até o fim da carência, e a próxima rotação parte da chave nova. Assim, a rotação nunca aumenta o número de chaves sem prazo da conta.

Aviso por e-mail. A cada rotação pela API, o e-mail da conta recebe os prefixos da chave anterior e da nova, a data e o IP de origem. Se a rotação não foi sua, o painel mostra de qual chave cada uma nasceu e oferece Revogar esta e as derivadas, que funciona também numa chave já revogada.

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 na trilha da conta como apikey_rotacionada, com data, IP de origem e os prefixos da chave anterior 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

Planilha. Abra com o separador ;. Texto que começa com =, +, - ou @ sai com um apóstrofo na frente, para a planilha não executar como fórmula, inclusive numero ou bairro iguais a -, que saem como '-. Número puro sai igual.

Tempo limite. Cada requisição CSV tem cerca de 25 segundos para ler as linhas. Se o tempo acabar antes (página muito grande com o servidor ocupado), o arquivo traz as linhas já lidas e termina com a linha # aviso: exportação parcial — N de M linha(s) desta página…. Só as linhas entregues contam como registros. Confira o rodapé antes de seguir para a próxima página: peça a mesma página de novo ou use um per_page menor.

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 — consultas por agentes de IA

Authorization: Bearer <SUA_CHAVE_DE_API>

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

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.