---
title: "Campos da resposta"
description: "Todos os campos dos perfis basic e full, do envelope meta e do envelope de erro, com tipo, nulabilidade e descrição, mais as tabelas de códigos da Receita Federal."
canonical: "https://cnpj.ia.br/docs/campos"
date_modified: 2026-09-02
source: "cnpj.ia.br"
---

docs · base agosto/2026 Atualizado em 02/09/2026

# Campos da resposta

Todos os campos dos perfis basic e full, do envelope meta e do envelope de erro, com tipo, nulabilidade e descrição, mais as tabelas de códigos da Receita Federal.

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](https://cnpj.ia.br/openapi/openapi.json); 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](https://cnpj.ia.br/docs/campos#enum-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](https://cnpj.ia.br/docs/campos#enum-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](https://cnpj.ia.br/docs/campos#enum-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](https://cnpj.ia.br/docs/campos#enum-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](https://cnpj.ia.br/docs/campos#enum-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](https://cnpj.ia.br/docs/campos#enum-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](https://cnpj.ia.br/docs/campos#enum-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](https://cnpj.ia.br/docs/campos#enum-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](https://cnpj.ia.br/docs/campos#enum-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](https://cnpj.ia.br/docs/campos#enum-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](https://cnpj.ia.br/docs/campos#enum-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](https://cnpj.ia.br/docs/campos#enum-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](https://cnpj.ia.br/docs/campos#enum-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](https://cnpj.ia.br/docs/campos#enum-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](https://cnpj.ia.br/docs/campos#enum-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](https://cnpj.ia.br/docs/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](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](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](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](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](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](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](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](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](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](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](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](https://cnpj.ia.br/docs/consulta-cnpj) e [Busca de empresas](https://cnpj.ia.br/docs/busca-empresas), onde estes campos aparecem.
- [Dados e frescor](https://cnpj.ia.br/docs/dados-e-frescor): de onde vem cada grupo de campos e com que frequência muda.
- [Referência gerada do OpenAPI](https://cnpj.ia.br/docs/referencia): os schemas como o contrato os declara.