{"openapi":"3.1.0","info":{"title":"cnpj.ia.br API","version":"1.0.0","summary":"Dados de empresas brasileiras por CNPJ: cadastro, contatos, sócios e regime tributário, com a data da base em toda resposta de consulta e busca.","description":"API REST e servidor MCP sobre a base de 70 milhões de CNPJs da Receita Federal, enriquecida pela Oportunidados. Base atualizada mensalmente; `meta.data_as_of` informa a data nas respostas de consulta, busca e geração de filtro, e `GET /v1/status` a devolve sem chave. Cobrança em créditos, só em resposta 200: `basic` 1, `full` 6, busca 1 por empresa retornada, `gerar_filtro` 1. CPF de sócio e de representante só mascarado (`***123456**`), nunca completo. Pedidos de remoção (LGPD) valem para site e API.\n\nContrato 1.0.0 (soft launch em 2026-09-19): este documento é gerado pela implementação Rails (Rswag) e publicado em /openapi.json; o site cnpj.ia.br espelha o mesmo documento. Política de versionamento em https://cnpj.ia.br/docs/versionamento.","termsOfService":"https://cnpj.ia.br/termos","contact":{"name":"cnpj.ia.br","url":"https://cnpj.ia.br/contato","email":"suporte@cnpj.ia.br"},"x-logo":{"url":"https://cnpj.ia.br/assets/img/logo.svg"},"x-date-modified":"2026-09-19"},"servers":[{"url":"https://api.cnpj.ia.br","description":"Produção"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"Consulta","description":"Tudo sobre um CNPJ conhecido."},{"name":"Busca","description":"Encontrar empresas por filtros."},{"name":"Conta","description":"Uso e franquia da conta."},{"name":"Público","description":"Sem chave: status da base e demonstração."}],"paths":{"/v1/cnpjs/{cnpj}":{"get":{"operationId":"getCnpj","tags":["Consulta"],"summary":"Consultar um CNPJ","description":"Retorna o perfil `basic` (1 crédito) ou `full` (6 créditos) de uma empresa. Aceita CNPJ numérico ou alfanumérico, com ou sem pontuação.","x-credits":{"basic":1,"full":6},"x-plan-min":"free","x-mcp-tool":"consultar_cnpj","parameters":[{"$ref":"#/components/parameters/cnpj"},{"name":"profile","in":"query","schema":{"type":"string","enum":["basic","full"],"default":"basic"},"description":"`basic`: cadastro. `full`: cadastro + telefones, e-mails, site, sócios (CPF mascarado ou nulo), regime tributário, faixa de funcionários e faixa de faturamento."}],"responses":{"200":{"description":"Empresa encontrada. Se houver pedido de remoção ativo, `meta.suppressed` é `true`, os campos de contato e sócios são omitidos e a cobrança é de 1 crédito.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-Credits-Charged":{"$ref":"#/components/headers/X-Credits-Charged"},"X-Credits-Remaining":{"$ref":"#/components/headers/X-Credits-Remaining"},"X-Credits-Reset":{"$ref":"#/components/headers/X-Credits-Reset"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"}},"content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"oneOf":[{"$ref":"#/components/schemas/CompanyBasic"},{"$ref":"#/components/schemas/CompanyFull"}]},"meta":{"$ref":"#/components/schemas/Meta"}}},"examples":{"full":{"$ref":"#/components/examples/CompanyFullExample"}}}}},"400":{"$ref":"#/components/responses/InvalidCnpj"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/QuotaExceeded"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Maintenance"},"504":{"$ref":"#/components/responses/UpstreamTimeout"}}}},"/v1/cnpjs":{"get":{"operationId":"searchCnpjs","tags":["Busca"],"summary":"Buscar empresas por filtros","description":"Página de até 20 empresas com campos `basic`, ordenação fixa por CNPJ, paginação por cursor. Custa 1 crédito por empresa retornada; página vazia não custa. Não disponível no plano Free.","x-credits":{"por_empresa_retornada":1,"pagina_max":20},"x-plan-min":"starter","x-mcp-tool":"buscar_empresas","parameters":[{"name":"uf","in":"query","required":false,"description":"Sigla da UF (2 letras maiúsculas). Nível 1 — até 50 valores separados por vírgula.","schema":{"type":"string"}},{"name":"municipio","in":"query","required":false,"description":"Código IBGE de município existente (7 dígitos). Nível 1 — até 50 valores separados por vírgula.","schema":{"type":"string"}},{"name":"cnae","in":"query","required":false,"description":"CNAE fiscal (2, 3, 5 ou 7 dígitos: divisão, grupo, classe, subclasse). Nível 1 — até 50 valores separados por vírgula.","schema":{"type":"string"}},{"name":"porte","in":"query","required":false,"description":"Porte: ME, EPP ou DEMAIS. Nível 1 — até 50 valores separados por vírgula.","schema":{"type":"string"}},{"name":"situacao","in":"query","required":false,"description":"Situação: ATIVA, SUSPENSA, INAPTA, BAIXADA ou NULA. Nível 1 — até 50 valores separados por vírgula.","schema":{"type":"string"}},{"name":"simples","in":"query","required":false,"schema":{"type":"boolean"}},{"name":"mei","in":"query","required":false,"schema":{"type":"boolean"}},{"name":"natureza","in":"query","required":false,"description":"Código da natureza jurídica (4 dígitos). Nível 1 — até 50 valores separados por vírgula.","schema":{"type":"string"}},{"name":"capital_min","in":"query","required":false,"schema":{"type":"number","minimum":0}},{"name":"capital_max","in":"query","required":false,"schema":{"type":"number","minimum":0}},{"name":"abertura_de","in":"query","required":false,"schema":{"type":"string","format":"date"}},{"name":"abertura_ate","in":"query","required":false,"schema":{"type":"string","format":"date"}},{"name":"regime","in":"query","required":false,"description":"Nível 2 — Starter ou superior. Regime: LUCRO_PRESUMIDO, LUCRO_REAL, LUCRO_ARBITRADO, IMUNE ou ISENTA; até 50 valores separados por vírgula.","schema":{"type":"string"}},{"name":"cnae_secundario","in":"query","required":false,"description":"Nível 2 — Starter ou superior. Com true, inclui CNAEs secundários; exige cnae.","schema":{"type":"boolean"}},{"name":"natureza_categoria","in":"query","required":false,"description":"Nível 2 — Starter ou superior. Primeiro dígito da natureza jurídica (1 a 5); até 50 valores separados por vírgula.","schema":{"type":"string"}},{"name":"matriz_filial","in":"query","required":false,"description":"Nível 2 — Starter ou superior. Tipo de estabelecimento.","schema":{"type":"string","enum":["MATRIZ","FILIAL"]}},{"name":"filiais_min","in":"query","required":false,"description":"Nível 2 — Starter ou superior. Mínimo de filiais; deve ser menor ou igual a filiais_max.","schema":{"type":"integer","minimum":0}},{"name":"filiais_max","in":"query","required":false,"description":"Nível 2 — Starter ou superior. Máximo de filiais; deve ser maior ou igual a filiais_min.","schema":{"type":"integer","minimum":0}},{"name":"situacao_data_de","in":"query","required":false,"description":"Nível 2 — Starter ou superior. Data mínima da situação (YYYY-MM-DD), até situacao_data_ate; exclui a sentinela 1925-01-01.","schema":{"type":"string","format":"date"}},{"name":"situacao_data_ate","in":"query","required":false,"description":"Nível 2 — Starter ou superior. Data máxima da situação (YYYY-MM-DD), desde situacao_data_de; exclui a sentinela 1925-01-01.","schema":{"type":"string","format":"date"}},{"name":"motivo_situacao","in":"query","required":false,"description":"Nível 2 — Starter ou superior. Código do motivo da situação (2 dígitos); até 50 valores separados por vírgula.","schema":{"type":"string"}},{"name":"situacao_especial","in":"query","required":false,"description":"Nível 2 — Starter ou superior. Código da situação especial (1 a 8); até 50 valores separados por vírgula.","schema":{"type":"string"}},{"name":"municipio_excluir","in":"query","required":false,"description":"Nível 2 — Starter ou superior. Código IBGE de município existente (7 dígitos); até 50 valores separados por vírgula, todos excluídos.","schema":{"type":"string"}},{"name":"cep","in":"query","required":false,"description":"Nível 2 — Starter ou superior. Prefixo do CEP (1 a 8 dígitos).","schema":{"type":"string","pattern":"^[0-9]{1,8}$"}},{"name":"bairro","in":"query","required":false,"description":"Nível 2 — Starter ou superior. Bairro por igualdade exata (1 a 100 caracteres).","schema":{"type":"string","minLength":1,"maxLength":100}},{"name":"com_email","in":"query","required":false,"description":"Nível 2 — Starter ou superior. true exige e-mail; false exige ausência.","schema":{"type":"boolean"}},{"name":"com_site","in":"query","required":false,"description":"Nível 2 — Starter ou superior. true exige site; false exige ausência.","schema":{"type":"boolean"}},{"name":"com_telefone","in":"query","required":false,"description":"Nível 2 — Starter ou superior. true exige telefone; false exige ausência.","schema":{"type":"boolean"}},{"name":"com_celular","in":"query","required":false,"description":"Nível 2 — Starter ou superior. true exige celular; false exige ausência.","schema":{"type":"boolean"}},{"name":"nome","in":"query","required":false,"description":"Nível 2 — Starter ou superior. Texto contido na razão social ou nome fantasia (3 a 100 caracteres), sem diferenciar maiúsculas; barras e curingas são literais.","schema":{"type":"string","minLength":3,"maxLength":100}},{"name":"socio_nome","in":"query","required":false,"description":"Nível 3 — Pro ou superior. Texto contido no nome de algum sócio (3 a 100 caracteres), sem diferenciar maiúsculas; barras e curingas são literais.","schema":{"type":"string","minLength":3,"maxLength":100}},{"name":"socio_cnpj","in":"query","required":false,"description":"Nível 3 — Pro ou superior. CNPJ de sócio PJ, numérico ou alfanumérico: 14 caracteres após remover pontuação; CPF não é aceito.","schema":{"type":"string","pattern":"^[0-9A-Za-z./-]{14,18}$"}},{"name":"socio_qualificacao","in":"query","required":false,"description":"Nível 3 — Pro ou superior. Código de qualificação do sócio (1 ou 2 dígitos); até 50 valores separados por vírgula.","schema":{"type":"string"}},{"name":"cep_raio","in":"query","required":false,"description":"Nível 3 — Pro ou superior. CEP de 8 dígitos com coordenada conhecida; exige raio_metros e restringe ao município do CEP.","schema":{"type":"string","pattern":"^[0-9]{8}$"}},{"name":"raio_metros","in":"query","required":false,"description":"Nível 3 — Pro ou superior. Raio em metros (100 a 20000); exige cep_raio.","schema":{"type":"integer","minimum":100,"maximum":20000}},{"name":"faturamento","in":"query","required":false,"description":"Nível 3 — Pro ou superior. Faixa do perfil full: ATE_360MIL, DE_360MIL_A_4_8MI ou ACIMA_4_8MI; até 50 valores separados por vírgula.","schema":{"type":"string"}},{"name":"funcionarios_min","in":"query","required":false,"description":"Nível 3 — Pro ou superior. Mínimo do valor esperado de funcionários arredondado, como no perfil full; até funcionarios_max. Distribuição inválida não casa.","schema":{"type":"integer","minimum":0}},{"name":"funcionarios_max","in":"query","required":false,"description":"Nível 3 — Pro ou superior. Máximo do valor esperado de funcionários arredondado, como no perfil full; desde funcionarios_min. Distribuição inválida não casa.","schema":{"type":"integer","minimum":0}},{"name":"cursor","in":"query","required":false,"description":"Cursor opaco da página anterior (`meta.next_cursor`).","schema":{"type":"string"}},{"name":"explicacao","in":"query","required":false,"description":"Ignorada. Presente para que a saída de `generateFilter` possa ser repassada inteira; não filtra e não conta como filtro.","schema":{"type":"string"}}],"responses":{"200":{"description":"Página de resultados.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-Credits-Charged":{"$ref":"#/components/headers/X-Credits-Charged"},"X-Credits-Remaining":{"$ref":"#/components/headers/X-Credits-Remaining"},"X-Credits-Reset":{"$ref":"#/components/headers/X-Credits-Reset"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchPage"}}}},"400":{"$ref":"#/components/responses/InvalidFilter"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/QuotaExceeded"},"403":{"$ref":"#/components/responses/Forbidden"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/Maintenance"},"504":{"$ref":"#/components/responses/UpstreamTimeout"}}}},"/v1/filters/generate":{"post":{"operationId":"generateFilter","tags":["Busca"],"summary":"Gerar filtros de busca a partir de linguagem natural","description":"Converte uma descrição em português nos filtros aceitos por `searchCnpjs`. Custa 1 crédito. Tem limite próprio de uso por conta.","x-credits":{"chamada":1},"x-plan-min":"free","x-mcp-tool":"gerar_filtro","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["descricao"],"properties":{"descricao":{"type":"string","maxLength":500,"examples":["fabricantes de embalagens em Joinville com e-mail"]}}}}}},"responses":{"200":{"description":"Filtros sugeridos, prontos para `searchCnpjs`.","headers":{"X-Request-Id":{"$ref":"#/components/headers/X-Request-Id"},"X-Credits-Charged":{"$ref":"#/components/headers/X-Credits-Charged"},"X-Credits-Remaining":{"$ref":"#/components/headers/X-Credits-Remaining"},"X-Credits-Reset":{"$ref":"#/components/headers/X-Credits-Reset"},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"}},"content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"$ref":"#/components/schemas/SearchFilters"},"meta":{"$ref":"#/components/schemas/Meta"}}}}}},"400":{"$ref":"#/components/responses/InvalidFilter"},"401":{"$ref":"#/components/responses/Unauthorized"},"402":{"$ref":"#/components/responses/QuotaExceeded"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/v1/usage":{"get":{"operationId":"getUsage","tags":["Conta"],"summary":"Uso e franquia da conta","x-credits":{"chamada":0},"x-plan-min":"free","x-mcp-tool":"ver_uso","responses":{"200":{"description":"Uso do ciclo corrente.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Usage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/status":{"get":{"operationId":"getStatus","tags":["Público"],"summary":"Data da base e estado da API","security":[],"x-credits":{"chamada":0},"responses":{"200":{"description":"Estado atual.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Status"}}}}}}},"/v1/demo":{"get":{"operationId":"getDemo","tags":["Público"],"summary":"Demonstração sem chave","description":"Perfil `full` de instituições públicas de uma allowlist, sem o array `socios` (devolve `socios_count`). Cache de 1 hora, 10 requisições por minuto por IP. Serve o \"Testar agora\" do site.","security":[],"x-credits":{"chamada":0},"parameters":[{"name":"cnpj","in":"query","required":false,"schema":{"type":"string","default":"00000000000191"},"description":"CNPJ da allowlist. Fora dela responde 404."}],"responses":{"200":{"description":"Perfil de demonstração.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CompanyFull"},"meta":{"$ref":"#/components/schemas/Meta"}}}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"cnpj_live_<segredo>","description":"Chave da conta, criada em app.cnpj.ia.br. Só no header Authorization; nunca em query string."}},"parameters":{"cnpj":{"name":"cnpj","in":"path","required":true,"schema":{"$ref":"#/components/schemas/Cnpj"},"description":"CNPJ numérico ou alfanumérico, com ou sem pontuação."}},"headers":{"X-Request-Id":{"description":"Identificador da requisição para suporte.","schema":{"type":"string"}},"X-Credits-Charged":{"description":"Créditos debitados nesta resposta.","schema":{"type":"integer"}},"X-Credits-Remaining":{"description":"Créditos restantes (franquia + pacotes).","schema":{"type":"integer"}},"X-Credits-Reset":{"description":"Instante do próximo reset da franquia (RFC 3339).","schema":{"type":"string","format":"date-time"}},"X-RateLimit-Limit":{"description":"Requisições por minuto do plano (por conta).","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requisições restantes no minuto corrente.","schema":{"type":"integer"}},"Retry-After":{"description":"Só em 429 e 503: segundos até tentar de novo.","schema":{"type":"integer"}}},"schemas":{"Cnpj":{"type":"string","description":"14 caracteres após normalização. Numérico ou alfanumérico (letras nas 12 primeiras posições, dígitos verificadores numéricos).","pattern":"^[A-Za-z0-9.\\-/]{14,18}$","examples":["00000000000191","00.000.000/0001-91","12.ABC.345/01DE-35"]},"CodigoDescricao":{"type":"object","required":["codigo","descricao"],"properties":{"codigo":{"type":"string"},"descricao":{"type":["string","null"]}},"description":"Par código/descrição. Códigos são strings e preservam o zero à esquerda da tabela de origem da Receita Federal (ex.: situação cadastral \"02\", porte \"05\", tipo de sócio \"2\", qualificação \"10\"). A tabela de domínio de cada campo está em /docs/campos."},"Endereco":{"type":"object","properties":{"tipo_logradouro":{"type":["string","null"]},"logradouro":{"type":["string","null"]},"numero":{"type":["string","null"]},"complemento":{"type":["string","null"]},"bairro":{"type":["string","null"]},"cep":{"type":["string","null"]},"municipio":{"type":["string","null"]},"codigo_municipio_ibge":{"type":["string","null"],"description":"7 dígitos."},"codigo_municipio_siafi":{"type":["string","null"],"description":"Código usado pela Receita Federal."},"uf":{"type":["string","null"]}}},"Opcao":{"type":"object","properties":{"optante":{"type":["boolean","null"]},"data_opcao":{"type":["string","null"],"format":"date"},"data_exclusao":{"type":["string","null"],"format":"date"}}},"CompanyBasic":{"type":"object","description":"Perfil `basic`: 1 crédito.","required":["cnpj","razao_social","situacao_cadastral"],"properties":{"cnpj":{"$ref":"#/components/schemas/Cnpj"},"raiz_cnpj":{"type":"string","description":"8 primeiros caracteres; identifica matriz e filiais."},"razao_social":{"type":"string"},"nome_fantasia":{"type":["string","null"]},"matriz_filial":{"$ref":"#/components/schemas/CodigoDescricao"},"n_filiais":{"type":["integer","null"]},"data_inicio_atividade":{"type":["string","null"],"format":"date"},"situacao_cadastral":{"$ref":"#/components/schemas/CodigoDescricao"},"data_situacao_cadastral":{"type":["string","null"],"format":"date"},"motivo_situacao_cadastral":{"$ref":"#/components/schemas/CodigoDescricao"},"situacao_especial":{"oneOf":[{"$ref":"#/components/schemas/CodigoDescricao"},{"type":"null"}],"description":"null quando não há situação especial."},"data_situacao_especial":{"type":["string","null"],"format":"date"},"natureza_juridica":{"$ref":"#/components/schemas/CodigoDescricao"},"porte":{"$ref":"#/components/schemas/CodigoDescricao"},"capital_social":{"type":["number","null"]},"cnae_fiscal":{"$ref":"#/components/schemas/CodigoDescricao"},"cnaes_secundarios":{"type":"array","items":{"$ref":"#/components/schemas/CodigoDescricao"}},"endereco":{"$ref":"#/components/schemas/Endereco"},"simples":{"$ref":"#/components/schemas/Opcao"},"mei":{"$ref":"#/components/schemas/Opcao"},"has_email":{"type":"boolean"},"has_website":{"type":"boolean"},"has_phone":{"type":"boolean"},"has_mobile_phone":{"type":"boolean"}}},"Telefone":{"type":"object","properties":{"ddd":{"type":"string"},"numero":{"type":"string"}}},"ContatoExtra":{"type":"object","properties":{"tipo":{"type":"string","enum":["telefone","email","site","instagram","facebook","youtube","linkedin","twitter","whatsapp","tiktok","pinterest","outro"],"description":"Tipo do contato. `outro` quando o tipo coletado não está nesta lista."},"valor":{"type":"string"},"origem":{"type":["string","null"],"enum":["oportunidados","receita_federal",null],"description":"Fonte do contato. `oportunidados` para o enriquecimento da Oportunidados, `receita_federal` para a Receita Federal; null quando a fonte não foi registrada."}}},"Socio":{"type":"object","description":"cnpj_cpf_socio: máscara da Receita (`***123456**`) ou, para sócio PJ, CNPJ alfanumérico de 14 caracteres (DV validado na API); ausente ou valor que não casa sai null. Nunca CPF completo. representante.cpf_repres: só a máscara ou null.","properties":{"nome":{"type":"string"},"tipo":{"$ref":"#/components/schemas/CodigoDescricao"},"qualificacao":{"$ref":"#/components/schemas/CodigoDescricao"},"data_entrada":{"type":["string","null"],"format":"date"},"pais":{"$ref":"#/components/schemas/CodigoDescricao"},"faixa_etaria":{"$ref":"#/components/schemas/CodigoDescricao"},"representante":{"type":["object","null"],"properties":{"nome":{"type":"string"},"qualificacao":{"$ref":"#/components/schemas/CodigoDescricao"}}}}},"CompanyFull":{"description":"Perfil `full`: 6 créditos. Tudo do `basic` mais contatos, sócios e sinais.","allOf":[{"$ref":"#/components/schemas/CompanyBasic"},{"type":"object","properties":{"telefones":{"type":"array","items":{"$ref":"#/components/schemas/Telefone"}},"email":{"type":["string","null"]},"site":{"type":["string","null"]},"contatos_extras":{"type":"array","items":{"$ref":"#/components/schemas/ContatoExtra"}},"socios":{"type":"array","items":{"$ref":"#/components/schemas/Socio"}},"socios_count":{"type":["integer","null"],"description":"Presente no /v1/demo, que omite `socios`."},"faixa_faturamento":{"type":["object","null"],"description":"Faixa DERIVADA do porte declarado à Receita. Não é estimativa própria nem valor.","properties":{"faixa":{"type":"string","description":"Texto da faixa, igual à tabela de origem: \"Até R$360.000,00\", \"Entre R$360.000,00 e R$4.800.000,00\", \"Superior a R$4.800.000,00\" ou \"Não informado\"."},"origem":{"type":"string","const":"porte"}}},"faixa_funcionarios":{"type":["string","null"],"description":"Número exato ou intervalo em texto; `null` quando não há dado oficial."},"regime_tributario":{"type":["object","null"],"properties":{"regime":{"type":"string"},"ano":{"type":"integer"},"escrituracoes":{"type":["array","null"],"items":{"type":"string"},"description":"Siglas das escriturações (ECD, ECF). PENDENTE gate 6.0: a coluna de origem é inteira e o mapa para siglas ainda não existe."}}}}}]},"Meta":{"type":"object","required":["request_id","source","data_as_of","credits_charged","credits_remaining"],"properties":{"request_id":{"type":"string"},"profile":{"type":"string","enum":["basic","full"]},"source":{"type":"string","const":"rfb_open_data+oportunidados"},"data_as_of":{"type":"string","format":"date","description":"Data da foto mensal da base servida nesta resposta."},"suppressed":{"type":"boolean","default":false},"credits_charged":{"type":"integer"},"credits_remaining":{"type":"integer","description":"Saldo depois desta chamada, somando a franquia do ciclo e os pacotes válidos — o mesmo número do header `X-Credits-Remaining`. O campo homônimo de `GET /v1/usage` é só a franquia, com os pacotes à parte em `packs`."},"credits_reset_at":{"type":"string","format":"date-time"},"next_cursor":{"type":["string","null"]},"page_size":{"type":"integer"},"total_count_capped":{"type":["string","null"],"description":"Contagem com teto de exibição, ex. \"10000+\". Cache de 1 h."}}},"SearchPage":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","maxItems":20,"items":{"$ref":"#/components/schemas/CompanyBasic"}},"meta":{"$ref":"#/components/schemas/Meta"}}},"SearchFilters":{"type":"object","properties":{"uf":{"type":"string"},"municipio":{"type":"string"},"cnae":{"type":"string"},"porte":{"type":"string"},"situacao":{"type":"string"},"simples":{"type":"boolean"},"mei":{"type":"boolean"},"natureza":{"type":"string"},"capital_min":{"type":"number"},"capital_max":{"type":"number"},"abertura_de":{"type":"string"},"abertura_ate":{"type":"string"},"explicacao":{"type":"string"}}},"Usage":{"type":"object","properties":{"plan":{"type":"string","enum":["free","starter","pro","business","scale"]},"credits_allowance":{"type":"integer"},"credits_used":{"type":"integer"},"credits_remaining":{"type":"integer","description":"Só a franquia do ciclo (`credits_allowance - credits_used`); os pacotes vêm em `packs`. O `credits_remaining` do `meta` das respostas de dados é o total, franquia mais pacotes."},"packs":{"type":"array","items":{"type":"object","properties":{"sku":{"type":"string"},"credits_remaining":{"type":"integer"},"expires_at":{"type":"string","format":"date"}}}},"rpm":{"type":"integer"},"search_enabled":{"type":"boolean"},"cycle_reset_at":{"type":"string","format":"date-time"}}},"Status":{"type":"object","properties":{"api_version":{"type":"string"},"data_as_of":{"type":"string","format":"date"},"maintenance":{"type":"boolean"},"retry_after_seconds":{"type":["integer","null"]}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","request_id","retryable"],"properties":{"code":{"type":"string","enum":["invalid_cnpj","invalid_filter","invalid_api_key","key_expired","quota_exceeded","insufficient_plan","filter_not_in_plan","payment_required","account_suspended","not_found","rate_limited","maintenance","upstream_timeout","internal_error"]},"message":{"type":"string"},"request_id":{"type":"string"},"retryable":{"type":"boolean"},"docs_url":{"type":"string","format":"uri"}}}}}},"responses":{"InvalidCnpj":{"description":"CNPJ inválido (formato ou dígito).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"InvalidFilter":{"description":"Filtro desconhecido ou valor fora do enum.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthorized":{"description":"Chave ausente, desconhecida, revogada ou expirada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"QuotaExceeded":{"description":"Franquia e pacotes esgotados. Header X-Credits-Reset.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"`insufficient_plan` (operação fora do plano), `filter_not_in_plan` (filtro acima do nível do plano) ou `payment_required` (cobrança recusada há mais de 7 dias).","content":{"application/json":{"examples":{"filter_not_in_plan":{"summary":"Starter recusa filtro de funcionários do Pro","value":{"error":{"code":"filter_not_in_plan","message":"O filtro funcionarios_min exige o plano Pro ou superior.","request_id":"req_01J8ZK3Q9X","retryable":false,"docs_url":"https://cnpj.ia.br/docs/erros-e-retentativas#filter_not_in_plan"}}}},"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"CNPJ válido ausente na base, ou removido a pedido do titular.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Requisições por minuto da conta excedidas. Header Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"$ref":"#/components/headers/Retry-After"}}},"Maintenance":{"description":"Janela mensal de atualização da base. Header Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"UpstreamTimeout":{"description":"Timeout de consulta. `retryable: true`; nada é cobrado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"examples":{"CompanyFullExample":{"summary":"Perfil full de uma instituição pública (Banco do Brasil)","description":"Valores ILUSTRATIVOS do formato; substituir por resposta real capturada antes do lançamento.","value":{"data":{"cnpj":"00000000000191","raiz_cnpj":"00000000","razao_social":"BANCO DO BRASIL SA","nome_fantasia":"DIRECAO GERAL","matriz_filial":{"codigo":"1","descricao":"Matriz"},"n_filiais":4000,"data_inicio_atividade":"1966-08-01","situacao_cadastral":{"codigo":"02","descricao":"Ativa"},"data_situacao_cadastral":"2005-11-03","motivo_situacao_cadastral":{"codigo":"00","descricao":"Sem motivo"},"situacao_especial":null,"data_situacao_especial":null,"natureza_juridica":{"codigo":"2038","descricao":"Sociedade de Economia Mista"},"porte":{"codigo":"05","descricao":"Demais"},"capital_social":120000000000,"cnae_fiscal":{"codigo":"6422100","descricao":"Bancos múltiplos, com carteira comercial"},"cnaes_secundarios":[],"endereco":{"tipo_logradouro":"Quadra","logradouro":"SAUN QUADRA 5 LOTE B","numero":"S/N","complemento":"TORRES I, II E III","bairro":"ASA NORTE","cep":"70040912","municipio":"Brasília","codigo_municipio_ibge":"5300108","codigo_municipio_siafi":"9701","uf":"DF"},"simples":{"optante":false,"data_opcao":null,"data_exclusao":null},"mei":{"optante":false,"data_opcao":null,"data_exclusao":null},"has_email":true,"has_website":true,"has_phone":true,"has_mobile_phone":false,"telefones":[{"ddd":"61","numero":"34939002"}],"email":"exemplo@bb.com.br","site":"https://www.bb.com.br","contatos_extras":[],"socios":[{"nome":"NOME DO DIRIGENTE","tipo":{"codigo":"2","descricao":"Pessoa Física"},"qualificacao":{"codigo":"10","descricao":"Diretor"},"data_entrada":"2025-01-01","pais":{"codigo":"105","descricao":"Brasil"},"faixa_etaria":{"codigo":"6","descricao":"51 a 60 anos"},"representante":null}],"faixa_faturamento":{"faixa":"Superior a R$4.800.000,00","origem":"porte"},"faixa_funcionarios":null,"regime_tributario":{"regime":"Lucro Real","ano":2025,"escrituracoes":["ECD","ECF"]}},"meta":{"request_id":"req_01J8ZK3Q9X","profile":"full","source":"rfb_open_data+oportunidados","data_as_of":"2026-08-01","suppressed":false,"credits_charged":6,"credits_remaining":99994,"credits_reset_at":"2026-10-01T00:00:00-03:00"}}}}}}