Campos da resposta · Docs cnpj.ia.br

Esta página lista cada campo que a API devolve, nos dois perfis e nos envelopes, com tipo, se aceita null e o que significa. Nomes, tipos e nulabilidade espelham o contrato OpenAPI; o build falha se divergirem. As descrições vêm da documentação oficial dos dados abertos da Receita Federal e das regras de derivação da Oportunidados, indicadas campo a campo.

Como ler

Perfil: basic (1 crédito) é o cadastro; full (6 créditos) inclui tudo do basic mais contatos, sócios e regime tributário. meta acompanha as respostas de consulta, busca e geração de filtro; erro é o envelope de qualquer resposta de erro. Nenhum dos dois entra na contagem de créditos.
Nulo?: ausência de dado é null, nunca chave omitida. As duas exceções são deliberadas: os campos suprimidos por pedido de remoção (meta.suppressed: true) e o array socios em GET /v1/demo, substituído por socios_count.
Códigos: campos com codigo e descricao seguem as tabelas da Receita Federal, reproduzidas mais abaixo com fonte.
Derivados: faixa_faturamento é derivada do porte declarado à Receita Federal e carrega origem: "porte". Não é estimativa de faturamento, e nenhuma integração deve apresentá-la como tal. faixa_funcionarios é texto: pode vir um número exato ou um intervalo, e null sem dado oficial.

Perfil basic

Campo	Tipo	Nulo?	Perfil	Descrição
`cnpj`	`string`	não	basic	CNPJ do estabelecimento, 14 caracteres sem pontuação, com zeros à esquerda. Vem da Receita Federal; aceita entrada numérica ou alfanumérica, com ou sem pontuação.
`raiz_cnpj`	`string`	não	basic	Os 8 primeiros caracteres do CNPJ, que identificam a empresa e são compartilhados por matriz e filiais. Campo da Receita Federal (CNPJ BÁSICO).
`razao_social`	`string`	não	basic	Nome empresarial registrado na Receita Federal. É o único nome sempre presente.
`nome_fantasia`	`string`	sim	basic	Nome fantasia declarado para o estabelecimento, na Receita Federal. `null` quando a empresa não declarou.
`matriz_filial.codigo`	`string`	não	basic	Código que diz se o estabelecimento é matriz ou filial, conforme a Receita Federal. Valores em matriz_filial.
`matriz_filial.descricao`	`string`	sim	basic	Descrição do código de matriz/filial, traduzida pela tabela de domínio da Receita Federal.
`n_filiais`	`integer`	sim	basic	Quantidade de estabelecimentos filiais sob a mesma raiz de CNPJ. Derivado: contagem calculada pela Oportunidados sobre a base da Receita, não é campo do layout oficial.
`data_inicio_atividade`	`string (date)`	sim	basic	Data de início de atividade do estabelecimento (abertura), campo da Receita Federal, em formato ISO `YYYY-MM-DD`.
`situacao_cadastral.codigo`	`string`	não	basic	Código da situação cadastral do estabelecimento na Receita Federal, com dois dígitos. É o campo que diz se a empresa está ativa. Valores em situacao_cadastral.
`situacao_cadastral.descricao`	`string`	sim	basic	Descrição da situação cadastral, traduzida do código pela tabela de domínio da Receita Federal.
`data_situacao_cadastral`	`string (date)`	sim	basic	Data do evento que gerou a situação cadastral atual, campo da Receita Federal.
`motivo_situacao_cadastral.codigo`	`string`	não	basic	Código do motivo da situação cadastral, campo da Receita Federal. Vem `00` quando não há motivo, então só é significativo quando a situação é diferente de Ativa. Valores em motivo_situacao_cadastral.
`motivo_situacao_cadastral.descricao`	`string`	sim	basic	Descrição do motivo da situação cadastral, traduzida pela tabela de domínio da Receita Federal.
`situacao_especial.codigo`	`string`	sim	basic	Código da situação especial da empresa (falência, recuperação judicial, liquidação e afins). A Receita Federal publica este campo como texto, sem tabela de códigos no layout oficial; o código exposto vem da tabela interna da Oportunidados. Valores em situacao_especial. (a confirmar)
`situacao_especial.descricao`	`string`	sim	basic	Descrição da situação especial. `null` (ou objeto inteiro `null`) quando a empresa não está em situação especial, que é o caso da grande maioria.
`data_situacao_especial`	`string (date)`	sim	basic	Data em que a empresa entrou na situação especial, campo da Receita Federal. `null` quando não há situação especial.
`natureza_juridica.codigo`	`string`	não	basic	Código de 4 dígitos da natureza jurídica da empresa, campo da Receita Federal (tabela de domínio derivada da classificação da CONCLA/IBGE). Valores em natureza_juridica.
`natureza_juridica.descricao`	`string`	sim	basic	Nome da natureza jurídica, traduzido do código pela tabela de domínio da Receita Federal.
`porte.codigo`	`string`	não	basic	Código do porte declarado à Receita Federal. É um porte cadastral, não uma medida de faturamento observado. Valores em porte.
`porte.descricao`	`string`	sim	basic	Descrição do porte, traduzida do código pela tabela de domínio da Receita Federal.
`capital_social`	`number`	sim	basic	Capital social declarado à Receita Federal, em reais. É valor de registro, não patrimônio atual.
`cnae_fiscal.codigo`	`string`	não	basic	Código CNAE da atividade econômica principal do estabelecimento, 7 dígitos, campo da Receita Federal.
`cnae_fiscal.descricao`	`string`	sim	basic	Nome da atividade econômica principal, traduzido do código pela tabela de CNAEs da Receita Federal.
`cnaes_secundarios[].codigo`	`string`	não	basic	Código CNAE de cada atividade econômica secundária do estabelecimento, campo da Receita Federal. O array vem vazio quando não há atividade secundária.
`cnaes_secundarios[].descricao`	`string`	sim	basic	Nome de cada atividade econômica secundária, traduzido pela tabela de CNAEs da Receita Federal.
`endereco.tipo_logradouro`	`string`	sim	basic	Tipo do logradouro (Rua, Avenida, Quadra e afins), campo da Receita Federal.
`endereco.logradouro`	`string`	sim	basic	Nome do logradouro onde o estabelecimento está localizado, campo da Receita Federal.
`endereco.numero`	`string`	sim	basic	Número do endereço, campo da Receita Federal. Vem como `S/N` quando não há número preenchido.
`endereco.complemento`	`string`	sim	basic	Complemento do endereço, campo da Receita Federal, em texto livre.
`endereco.bairro`	`string`	sim	basic	Bairro do estabelecimento, campo da Receita Federal.
`endereco.cep`	`string`	sim	basic	CEP do logradouro, 8 dígitos sem pontuação, campo da Receita Federal.
`endereco.municipio`	`string`	sim	basic	Nome do município de jurisdição do estabelecimento, traduzido pela tabela de municípios da Receita Federal.
`endereco.codigo_municipio_ibge`	`string`	sim	basic	Código IBGE do município, 7 dígitos. Derivado: convertido pela Oportunidados a partir do código da Receita, porque o layout oficial não traz o código do IBGE.
`endereco.codigo_municipio_siafi`	`string`	sim	basic	Código de município usado pela Receita Federal no layout do CNPJ (tabela SIAFI), tal como publicado. Não é o código do IBGE.
`endereco.uf`	`string`	sim	basic	Sigla da unidade da federação do estabelecimento, campo da Receita Federal.
`simples.optante`	`boolean`	sim	basic	Indica opção pelo Simples Nacional, dos dados do Simples publicados pela Receita Federal. `null` quando o indicador vem em branco (caso ‘outros’ do layout).
`simples.data_opcao`	`string (date)`	sim	basic	Data de opção pelo Simples Nacional, campo da Receita Federal.
`simples.data_exclusao`	`string (date)`	sim	basic	Data de exclusão do Simples Nacional, campo da Receita Federal.
`mei.optante`	`boolean`	sim	basic	Indica opção pelo MEI, dos dados do Simples publicados pela Receita Federal. `null` quando o indicador vem em branco.
`mei.data_opcao`	`string (date)`	sim	basic	Data de opção pelo MEI, campo da Receita Federal.
`mei.data_exclusao`	`string (date)`	sim	basic	Data de exclusão do MEI, campo da Receita Federal.
`has_email`	`boolean`	não	basic	Indica se a empresa tem e-mail na base, sem revelar o e-mail. Sinal derivado, calculado no processamento da Oportunidados; serve para filtrar antes de gastar o perfil `full`.
`has_website`	`boolean`	não	basic	Indica se há site institucional para a empresa. Sinal derivado do enriquecimento da Oportunidados, já que a Receita Federal não publica site.
`has_phone`	`boolean`	não	basic	Indica se a empresa tem pelo menos um telefone na base. Sinal derivado, calculado no processamento da Oportunidados.
`has_mobile_phone`	`boolean`	não	basic	Indica se algum dos telefones é celular. Sinal derivado, calculado no processamento da Oportunidados.

Perfil full

Só os campos exclusivos do full; o restante é o basic acima.

Campo	Tipo	Nulo?	Perfil	Descrição
`regime_tributario.regime`	`string`	sim	full	Regime de tributação do lucro apurado pela empresa no ano informado. Vem dos dados de regime tributário da Receita Federal, que são publicados fora do layout do CNPJ; o objeto inteiro é `null` quando não há registro. Valores em regime_tributario.
`regime_tributario.ano`	`integer`	sim	full	Ano-calendário a que o regime tributário se refere, campo da Receita Federal.
`regime_tributario.escrituracoes`	`array[string]`	sim	full	Escriturações contábeis e fiscais registradas para a empresa no ano (por exemplo ECD e ECF), da Receita Federal. (a confirmar)
`telefones[].ddd`	`string`	não	full	DDD de cada telefone cadastrado. Os dois primeiros pares DDD/telefone são campos da Receita Federal; o array vem vazio quando não há telefone. (a confirmar)
`telefones[].numero`	`string`	não	full	Número do telefone, sem DDD e sem pontuação, cadastrado na Receita Federal.
`email`	`string`	sim	full	Endereço de correio eletrônico do contribuinte, campo da Receita Federal. `null` quando a empresa não tem e-mail na base.
`site`	`string`	sim	full	Site institucional da empresa. Enriquecimento da Oportunidados (a Receita Federal não publica site): escolha determinística de uma URL institucional, pela confiança da fonte e depois pela coleta mais recente.
`contatos_extras[].tipo`	`string`	não	full	Tipo do contato extra (telefone, e-mail, perfil em rede social e afins). Enriquecimento da Oportunidados; o array vem vazio quando não há contato extra.
`contatos_extras[].valor`	`string`	não	full	Valor do contato extra, como coletado no enriquecimento da Oportunidados.
`contatos_extras[].origem`	`string`	sim	full	Identificador da fonte de coleta do contato extra, no enriquecimento da Oportunidados. `null` quando a fonte não foi registrada.
`socios[].nome`	`string`	não	full	Nome do sócio pessoa física, ou razão social do sócio pessoa jurídica, como publicado pela Receita Federal. Nunca acompanhado de CPF ou CNPJ do sócio.
`socios[].tipo.codigo`	`string`	não	full	Código do identificador de sócio (pessoa jurídica, física ou estrangeiro), campo da Receita Federal. Valores em tipo_socio.
`socios[].tipo.descricao`	`string`	sim	full	Descrição do identificador de sócio, traduzida do código do layout da Receita Federal.
`socios[].qualificacao.codigo`	`string`	não	full	Código da qualificação do sócio na sociedade, campo da Receita Federal. Valores em qualificacao_socio.
`socios[].qualificacao.descricao`	`string`	sim	full	Nome da qualificação do sócio, traduzido pela tabela de qualificações da Receita Federal.
`socios[].data_entrada`	`string (date)`	sim	full	Data de entrada do sócio na sociedade, campo da Receita Federal.
`socios[].pais.codigo`	`string`	não	full	Código do país do sócio, campo da Receita Federal. O layout oficial o define como país do sócio estrangeiro; para sócios no Brasil o código é 105. Valores em pais.
`socios[].pais.descricao`	`string`	sim	full	Nome do país, traduzido pela tabela de países da Receita Federal.
`socios[].faixa_etaria.codigo`	`string`	não	full	Código da faixa etária do sócio, calculado pela Receita Federal a partir da data de nascimento do CPF. A data de nascimento e o CPF não são publicados nem retornados. Valores em faixa_etaria. (a confirmar)
`socios[].faixa_etaria.descricao`	`string`	sim	full	Descrição do intervalo de idade do sócio, conforme a regra de faixa etária do layout da Receita Federal.
`socios[].representante.nome`	`string`	sim	full	Nome do representante legal do sócio, campo da Receita Federal. O objeto `representante` é `null` quando o sócio não tem representante; o CPF do representante nunca é retornado.
`socios[].representante.qualificacao.codigo`	`string`	sim	full	Código da qualificação do representante legal, campo da Receita Federal, na mesma tabela de qualificações dos sócios. Valores em qualificacao_socio.
`socios[].representante.qualificacao.descricao`	`string`	sim	full	Nome da qualificação do representante legal, traduzido pela tabela de qualificações da Receita Federal.
`socios_count`	`integer`	sim	full	Quantidade de sócios da empresa. Derivado; presente apenas em `/v1/demo`, que omite o array `socios`.
`faixa_faturamento.faixa`	`string`	sim	full	Faixa de faturamento DERIVADA do porte declarado à Receita Federal, em texto. Não é estimativa própria, não é valor apurado e não é faturamento observado. Valores em faixa_faturamento.
`faixa_faturamento.origem`	`string`	sim	full	Origem da faixa, constante `porte`, para deixar explícito que o valor é derivado do porte e de nada mais. Vem `null` junto com o objeto `faixa_faturamento` inteiro quando não há faixa.
`faixa_funcionarios`	`string`	sim	full	Número de funcionários em texto: pode ser um número exato ou um intervalo (por exemplo `Entre 12 e 40`). Enriquecimento da Oportunidados; `null` quando não há dado oficial.

Envelope meta

Campo	Tipo	Nulo?	Perfil	Descrição
`meta.request_id`	`string`	não	meta	Identificador da requisição, o mesmo do header `X-Request-Id`. É o que o suporte pede para rastrear uma chamada.
`meta.profile`	`string`	não	meta	Perfil de campos servido na resposta. Só aparece nas operações que servem campos de empresa. Valores em perfil_resposta.
`meta.source`	`string`	não	meta	Origem dos dados da resposta. Constante `rfb_open_data+oportunidados`: dados abertos da Receita Federal mais enriquecimento da Oportunidados.
`meta.data_as_of`	`string (date)`	não	meta	Data da base servida na resposta. A base é atualizada mensalmente; este campo está em toda resposta porque a consulta responde pela foto do mês, não pelo instante da chamada.
`meta.suppressed`	`boolean`	não	meta	Indica pedido de remoção ativo do titular. Quando `true`, os campos de contato e sócios são omitidos e a cobrança é de 1 crédito.
`meta.credits_charged`	`integer`	não	meta	Créditos debitados nesta resposta, o mesmo valor do header `X-Credits-Charged`. Erro, 404 e limite custam 0.
`meta.credits_remaining`	`integer`	não	meta	Créditos restantes na conta, somando franquia do plano e pacotes avulsos.
`meta.credits_reset_at`	`string (date-time)`	não	meta	Instante do próximo reset da franquia, no primeiro dia do mês-calendário. É o mesmo valor do header `X-Credits-Reset`.
`meta.next_cursor`	`string`	sim	meta	Cursor opaco da próxima página da busca. `null` na última página; ignorado nas outras operações.
`meta.page_size`	`integer`	não	meta	Quantidade de empresas na página de busca, no máximo 20. Só aparece nas respostas de busca.
`meta.total_count_capped`	`string`	sim	meta	Contagem total da coorte com teto de exibição, em texto (por exemplo `10000+`). Tem cache de 1 hora.

Envelope de erro

Campo	Tipo	Nulo?	Perfil	Descrição
`error.code`	`string`	não	erro	Código estável do erro, de uma lista fechada de 12 valores. É o que o cliente deve testar, não a mensagem. Valores em error_code.
`error.message`	`string`	não	erro	Mensagem do erro em português, para leitura humana. Pode mudar sem aviso; o contrato estável é o `code`.
`error.request_id`	`string`	não	erro	Identificador da requisição que falhou, o mesmo do header `X-Request-Id`. É o que o suporte pede para rastrear a chamada.
`error.retryable`	`boolean`	não	erro	Indica se a mesma chamada pode ser repetida com backoff. `false` significa que repetir não muda o resultado sem corrigir a causa antes.
`error.docs_url`	`string (uri)`	não	erro	URL da seção de `/docs/erros-e-retentativas` que explica o código. É o único campo opcional do envelope de erro.

O comportamento de cada código está em Erros e retentativas.

Tabelas de códigos

Os valores abaixo são os publicados pela Receita Federal no layout dos dados abertos do CNPJ, salvo onde a tabela indica origem interna. Tabelas de CNAE e de município não são reproduzidas aqui: são milhares de linhas e a procedência está na descrição de cada campo.

Valores de `situacao_cadastral.codigo`

Códigos e nomes do layout oficial (seção ESTABELECIMENTOS). O PDF imprime 2, 3 e 4 sem zero à esquerda; os dados vêm com dois dígitos e a API sempre devolve dois dígitos.

Código	Nome
`01`	Nula
`02`	Ativa
`03`	Suspensa
`04`	Inapta
`08`	Baixada

Fonte: https://www.gov.br/receitafederal/dados/cnpj-metadados.pdf

Valores de `motivo_situacao_cadastral.codigo`

Lista completa: 68 valores na tabela interna, distribuídos entre os códigos 01 e 80 (com lacunas). O layout oficial só define o campo; a tabela de domínio vem no arquivo Motivos dos dados abertos. Abaixo, os códigos mais úteis para interpretar uma situação não Ativa.

Tabela completa: 68 valores na fonte; abaixo, os reproduzidos nesta página.

Código	Nome
`00`	Sem motivo
`01`	Extinção por Encerramento, Liquidação Voluntária
`02`	Incorporação
`03`	Fusão
`04`	Cisão Total
`09`	Não Início de Atividade
`15`	Inexistente de Fato
`17`	Baixa Iniciada e Ainda Não Deferida
`18`	Interrupção Temporária das Atividades
`21`	Pedido de Baixa Indeferida
`54`	Baixa - Tratamento Diferenciado Dado às ME e EPP (Lei Complementar Número 123/2006)
`62`	Falta de Pluralidade de Sócios
`63`	Omissão de Declarações
`64`	Localização Desconhecida
`66`	Inaptidão
`71`	Inaptidão (Lei 11.941/2009 Art.54)
`73`	Omissão Contumaz

Fonte: https://dados.gov.br/dados/conjuntos-dados/cadastro-nacional-da-pessoa-juridica---cnpj

A confirmar — 00: Ausente da tabela interna, que começa em 01; o valor ‘Sem motivo’ aparece no exemplo do openapi.json. Confirmar contra o arquivo Motivos dos dados abertos.

Valores de `porte.codigo`

Códigos e nomes do layout oficial (seção EMPRESAS), verbatim. A API atual devolve 05 como ‘Empresa de Médio e Grande Porte’ (ver _data/example_response.json); o contrato público usa ‘Demais’, que é o texto da Receita Federal.

Código	Nome
`00`	Não informado
`01`	Micro Empresa
`03`	Empresa de Pequeno Porte
`05`	Demais

Fonte: https://www.gov.br/receitafederal/dados/cnpj-metadados.pdf

Valores de `natureza_juridica.codigo`

Tabela completa da RFB, ~90 valores; ver fonte (arquivo Naturezas dos dados abertos, derivado da classificação da CONCLA/IBGE). Abaixo, 10 exemplos escolhidos por relevância para a documentação; a frequência real na base NÃO foi medida.

Tabela completa: 89 valores na fonte; abaixo, os reproduzidos nesta página.

Código	Nome
`2135`	Empresário (Individual)
`2062`	Sociedade Empresária Limitada
`2240`	Sociedade Simples Limitada
`2054`	Sociedade Anônima Fechada
`2046`	Sociedade Anônima Aberta
`2143`	Cooperativa
`3999`	Associação Privada
`3069`	Fundação Privada
`2038`	Sociedade de Economia Mista
`4120`	Produtor Rural (Pessoa Física)

Fonte: https://dados.gov.br/dados/conjuntos-dados/cadastro-nacional-da-pessoa-juridica---cnpj

Valores de `socios[].qualificacao.codigo, socios[].representante.qualificacao.codigo`

79 valores, contíguos de 1 a 79, da tabela interna espelhada do arquivo Qualificacoes dos dados abertos. A mesma tabela vale para sócio e para representante legal.

Tabela completa: 79 valores na fonte; abaixo, os reproduzidos nesta página.

Código	Nome
`1`	Acionista
`2`	Acionista Controlador
`3`	Acionista Diretor
`4`	Acionista Presidente
`5`	Administrador
`6`	Administradora de consórcio de Empresas ou Grupo de Empresas
`7`	Comissário
`8`	Conselheiro de Administração
`9`	Curador
`10`	Diretor
`11`	Interventor
`12`	Inventariante
`13`	Liquidante
`14`	Mãe
`15`	Pai
`16`	Presidente
`17`	Procurador
`18`	Secretário
`19`	Síndico (Condomínio)
`20`	Sociedade Consorciada
`21`	Sociedade Filiada
`22`	Sócio
`23`	Sócio Capitalista
`24`	Sócio Comanditado
`25`	Sócio Comanditário
`26`	Sócio de Indústria
`27`	Sócio Residente ou Domiciliado no Exterior
`28`	Sócio-Gerente
`29`	Sócio ou Acionista Incapaz ou Relativamente Incapaz (exceto menor)
`30`	Sócio ou Acionista Menor (Assistido/Representado)
`31`	Sócio Ostensivo
`32`	Tabelião
`33`	Tesoureiro
`34`	Titular de Empresa Individual Imobiliária
`35`	Tutor
`36`	Gerente-Delegado
`37`	Sócio Pessoa Jurídica Domiciliado no Exterior
`38`	Sócio Pessoa Física Residente ou Domiciliado no Exterior
`39`	Diplomata
`40`	Cônsul
`41`	Representante de Organização Internacional
`42`	Oficial de Registro
`43`	Responsável
`44`	Sócio Participante
`45`	Sócio Investidor
`46`	Ministro de Estado das Relações Exteriores
`47`	Sócio Pessoa Física Residente no Brasil
`48`	Sócio Pessoa Jurídica Domiciliado no Brasil
`49`	Sócio-Administrador
`50`	Empresário
`51`	Candidato a Cargo Político Eletivo
`52`	Sócio com Capital
`53`	Sócio sem Capital
`54`	Fundador
`55`	Sócio Comanditado Residente no Exterior
`56`	Sócio Comanditário Pessoa Física Residente no Exterior
`57`	Sócio Comanditário Pessoa Jurídica Domiciliado no Exterior
`58`	Sócio Comanditário Incapaz
`59`	Produtor Rural
`60`	Cônsul Honorário
`61`	Responsável Indígena
`62`	Representante das Instituições Extraterritoriais
`63`	Cotas em Tesouraria
`64`	Administrador Judicial
`65`	Titular Pessoa Física Residente ou Domiciliado no Brasil
`66`	Titular Pessoa Física Residente ou Domiciliado no Exterior
`67`	Titular Pessoa Física Incapaz ou Relativamente Incapaz (exceto menor)
`68`	Titular Pessoa Física Menor (Assistido/Representado)
`69`	Beneficiário Final
`70`	Administrador Residente ou Domiciliado no Exterior
`71`	Conselheiro de Administração Residente ou Domiciliado no Exterior
`72`	Diretor Residente ou Domiciliado no Exterior
`73`	Presidente Residente ou Domiciliado no Exterior
`74`	Sócio-Administrador Residente ou Domiciliado no Exterior
`75`	Fundador Residente ou Domiciliado no Exterior
`76`	Protetor
`77`	Vice-Presidente
`78`	Titular Pessoa Jurídica Domiciliada no Brasil
`79`	Titular Pessoa Jurídica Domiciliada no Exterior

Fonte: https://dados.gov.br/dados/conjuntos-dados/cadastro-nacional-da-pessoa-juridica---cnpj

Valores de `socios[].faixa_etaria.codigo`

Regra 4 do layout oficial (Campo Faixa Etária, no Layout Sócios), verbatim: a faixa é calculada pela Receita Federal a partir da data de nascimento do CPF do sócio. Nem a data nem o CPF são publicados.

Código	Nome
`0`	Não se aplica
`1`	0 a 12 anos
`2`	13 a 20 anos
`3`	21 a 30 anos
`4`	31 a 40 anos
`5`	41 a 50 anos
`6`	51 a 60 anos
`7`	61 a 70 anos
`8`	71 a 80 anos
`9`	Maiores de 80 anos

Fonte: https://www.gov.br/receitafederal/dados/cnpj-metadados.pdf

Valores de `socios[].tipo.codigo`

Campo IDENTIFICADOR DE SÓCIO do layout oficial (seção SÓCIOS), verbatim.

Código	Nome
`1`	Pessoa Jurídica
`2`	Pessoa Física
`3`	Estrangeiro

Fonte: https://www.gov.br/receitafederal/dados/cnpj-metadados.pdf

Valores de `matriz_filial.codigo`

Campo IDENTIFICADOR MATRIZ/FILIAL do layout oficial (seção ESTABELECIMENTOS), verbatim. Matriz e filiais compartilham a mesma raiz de CNPJ.

Código	Nome
`1`	Matriz
`2`	Filial

Fonte: https://www.gov.br/receitafederal/dados/cnpj-metadados.pdf

Valores de `situacao_especial.codigo`

O layout oficial define SITUAÇÃO ESPECIAL apenas como ‘situação especial da empresa’, sem tabela de códigos. Os códigos abaixo vêm da tabela interna da Oportunidados e NÃO foram confirmados contra tabela publicada da Receita Federal.

Código	Nome
`0`	Não definida ou não aplicável
`1`	Inventário do empresário, do titular de EIRELI ou do titular de empresa individual imobiliária
`2`	Falido
`3`	Em recuperação judicial
`4`	Encerramento da liquidação extrajudicial
`5`	Início da intervenção
`6`	Encerramento da liquidação judicial
`7`	Início da liquidação extrajudicial
`8`	Início da liquidação judicial

Fonte: https://www.gov.br/receitafederal/dados/cnpj-metadados.pdf

A confirmar: os códigos desta tabela ainda não foram conferidos contra tabela publicada da Receita Federal. Ver _data/campos-notes.md.

Valores de `regime_tributario.regime`

Chave da tabela: código interno do regime, não exposto na resposta; o campo devolve o texto

Regime de tributação do lucro. Não faz parte do layout do CNPJ; vem dos dados de regime tributário da Receita Federal. O mapa código → nome abaixo é o da tabela interna e NÃO foi confirmado contra tabela publicada.

Código	Nome
`0`	Não aplicável
`1`	Lucro Presumido
`2`	Lucro Real
`3`	Lucro Arbitrado
`4`	Lucro Presumido Real
`5`	Lucro Presumido Arbitrado
`6`	Lucro Real Arbitrado
`7`	Lucro Presumido Real Arbitrado
`8`	Imune do IRPJ
`9`	Isenta do IRPJ

Fonte: https://dados.gov.br/dados/conjuntos-dados/cadastro-nacional-da-pessoa-juridica---cnpj

A confirmar: os códigos desta tabela ainda não foram conferidos contra tabela publicada da Receita Federal. Ver _data/campos-notes.md.

Valores de `socios[].pais.codigo`

Tabela completa no arquivo Paises dos dados abertos; 255 valores na tabela interna, com códigos de 3 dígitos. Não reproduzida aqui: ver fonte. Brasil é 105.

Tabela completa: 255 valores na fonte; abaixo, os reproduzidos nesta página.

Código	Nome
`105`	Brasil

Fonte: https://dados.gov.br/dados/conjuntos-dados/cadastro-nacional-da-pessoa-juridica---cnpj

Valores de `faixa_faturamento.faixa`

Chave da tabela: porte.codigo

Não é enum da Receita Federal: é a tradução determinística do código de porte em texto de faixa. Um único porte, um único texto. Os quatro textos estão no openapi.json; o mapa porte → texto vem da tabela interna e não é publicado (ver campos-notes.md).

Código	Nome
`01`	Até R$360.000,00
`03`	Entre R$360.000,00 e R$4.800.000,00
`05`	Superior a R$4.800.000,00
`00`	Não informado

Fonte: derivado do porte declarado à Receita Federal (openapi.json, `faixa_faturamento.origem: porte`)

A confirmar: os códigos desta tabela ainda não foram conferidos contra tabela publicada da Receita Federal. Ver _data/campos-notes.md.

Valores de `meta.profile`

Enum do contrato, não da Receita Federal. Os créditos de cada perfil vivem em _data/pricing.yml.

Código	Nome
`basic`	Perfil basic
`full`	Perfil full

Fonte: openapi/openapi.json (`Meta.profile`, enum do contrato)

Valores de `error.code`

Enum do contrato, 12 valores estáveis. A API não devolve descrição de erro, devolve message; os textos abaixo dizem quando cada código ocorre. Status HTTP, Retry-After e política de retentativa são assunto de /docs/erros-e-retentativas.

Código	Nome
`invalid_cnpj`	Formato ou dígito verificador inválido
`invalid_filter`	Filtro desconhecido ou valor fora do enum
`invalid_api_key`	Chave ausente, desconhecida ou revogada
`key_expired`	Chave com validade vencida
`quota_exceeded`	Franquia e pacotes esgotados
`insufficient_plan`	Operação fora do plano da conta
`payment_required`	Pagamento em atraso
`not_found`	CNPJ válido ausente da base, ou suprimido por pedido do titular
`rate_limited`	Limite de requisições por minuto da conta
`maintenance`	Janela de atualização da base
`upstream_timeout`	Timeout de consulta
`internal_error`	Erro interno

Fonte: openapi/openapi.json (`Error.error.code`, enum do contrato) e doc 12 §2.3

Relacionados

Consulta por CNPJ e Busca de empresas, onde estes campos aparecem.
Dados e frescor: de onde vem cada grupo de campos e com que frequência muda.
Referência gerada do OpenAPI: os schemas como o contrato os declara.

Como ler

Perfil basic

Perfil full

Envelope meta

Envelope de erro

Tabelas de códigos

Valores de situacao_cadastral.codigo

Valores de motivo_situacao_cadastral.codigo

Valores de porte.codigo

Valores de natureza_juridica.codigo

Valores de socios[].qualificacao.codigo, socios[].representante.qualificacao.codigo

Valores de socios[].faixa_etaria.codigo

Valores de socios[].tipo.codigo

Valores de matriz_filial.codigo

Valores de situacao_especial.codigo

Valores de regime_tributario.regime

Valores de socios[].pais.codigo

Valores de faixa_faturamento.faixa

Valores de meta.profile

Valores de error.code

Relacionados

Valores de `situacao_cadastral.codigo`

Valores de `motivo_situacao_cadastral.codigo`

Valores de `porte.codigo`

Valores de `natureza_juridica.codigo`

Valores de `socios[].qualificacao.codigo, socios[].representante.qualificacao.codigo`

Valores de `socios[].faixa_etaria.codigo`

Valores de `socios[].tipo.codigo`

Valores de `matriz_filial.codigo`

Valores de `situacao_especial.codigo`

Valores de `regime_tributario.regime`

Valores de `socios[].pais.codigo`

Valores de `faixa_faturamento.faixa`

Valores de `meta.profile`

Valores de `error.code`