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

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, 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.

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

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.