Pular para o conteúdo
Ver planos
DocumentaçãoCampos da ficha

Campos da ficha

A ficha de uma empresa vem em JSON, com quatro seções. Os campos vêm como a base os guarda: códigos da Receita Federal e datas ISO.

Atualizado em · API v1

Como chamar está em Início rápido. A resposta tem quatro seções:

  1. company: dados cadastrais da empresa
  2. socios: sócios e administradores
  3. contatos_extras: e-mails, telefones, sites e redes sociais adicionais
  4. contexto: comparativos da empresa no mesmo CNAE e município, ranking, similares e obras

Seção company: dados cadastrais

Os campos abaixo vêm como a base os guarda: códigos da Receita Federal e datas em formato ISO. Campos sem valor costumam vir como null; as exceções estão descritas em cada campo.

Identificação

  • cnpj: CNPJ como texto (string), com 14 posições e sem formatação
  • razao_social: Razão social da empresa
  • nome_fantasia: Nome fantasia
  • raiz_cnpj: Raiz do CNPJ como texto (string), os 8 primeiros caracteres
  • matriz_filial: código do estabelecimento (1 matriz, 2 filial)

Atividade econômica

  • cnae_fiscal: CNAE principal, só com os números (por exemplo, "6201501")
  • cnaes_secundarios: lista com os CNAEs secundários
  • natureza_juridica: descrição da natureza jurídica
  • cod_nat_juridica: código da natureza jurídica

Situação cadastral

  • situacao_cadastral: código da situação cadastral (veja a lista abaixo)
  • data_situacao: data da situação cadastral
  • motivo_situacao: motivo da situação cadastral
  • data_inicio_atividade: data de início das atividades

Porte, faixa de faturamento e regime

  • capital_social: capital social (número decimal)
  • porte: código do porte declarado à Receita Federal (veja a lista abaixo)
  • faturamento: faixa de faturamento, ou "Não disponível"
  • opc_simples: opção pelo Simples Nacional, em código da Receita Federal (por exemplo, S ou N)
  • data_opc_simples: data da opção pelo Simples
  • data_exc_simples: data de exclusão do Simples
  • opc_mei: opção pelo MEI, em código da Receita Federal (S ou N)
  • data_opc_mei: data de opção pelo MEI
  • data_exc_mei: data de exclusão do MEI
  • regime_tributario: regime tributário declarado (por exemplo, "Lucro Real", "Lucro Presumido", "Simples Nacional")
  • ano_regime_tributario: ano de referência do regime tributário (inteiro)
  • escrituracoes_regime_tributario: código das escriturações associadas ao regime (inteiro)
  • numero_funcionarios: Número de funcionários, sempre em texto: um número (ex: "42"), uma faixa (ex: "Entre 30 e 65") ou "Sem dados oficiais". Disponível nos planos Prata, Ouro, Diamante e Black, inclusive os anuais; a chave fica ausente nos outros planos.

Endereço

  • tipo_logradouro: tipo do logradouro (RUA, AVENIDA e outros)
  • logradouro: nome do logradouro
  • numero: número do endereço
  • complemento: complemento do endereço
  • bairro: bairro
  • cep: CEP
  • uf: sigla do estado
  • municipio: nome do município
  • cod_municipio: código do município

Contatos

  • ddd_1, ddd_2, ddd_3: DDD dos telefones 1, 2 e 3
  • telefone_1, telefone_2, telefone_3: telefones 1, 2 e 3 (o telefone_1 é o principal)
  • email: e-mail principal cadastrado na Receita Federal
  • has_email: indica se a empresa tem e-mail
  • has_website: indica se a empresa tem site

A presença de telefone e e-mail varia por empresa. Veja de onde vêm os contatos.

Exemplo da seção company

JSON
"company": {
  "cnpj": "12345678000190",
  "razao_social": "EMPRESA EXEMPLO LTDA",
  "nome_fantasia": "Empresa Exemplo",
  "cnae_fiscal": "6201501",
  "cnaes_secundarios": ["6202300", "6203100"],
  "data_inicio_atividade": "2020-01-15",
  "situacao_cadastral": "02",
  "data_situacao": "2020-01-15",
  "motivo_situacao": "SEM MOTIVO",
  "natureza_juridica": "Sociedade Empresária Limitada",
  "cod_nat_juridica": "206-2",
  "capital_social": 100000.0,
  "porte": "03",
  "faturamento": "Não disponível",
  "opc_simples": "S",
  "data_opc_simples": "2020-01-15",
  "opc_mei": "N",
  "matriz_filial": "1",
  "tipo_logradouro": "RUA",
  "logradouro": "DAS FLORES",
  "numero": "100",
  "complemento": "SALA 1",
  "bairro": "CENTRO",
  "cep": "01310-100",
  "uf": "SP",
  "cod_municipio": "7107",
  "municipio": "São Paulo",
  "ddd_1": "11",
  "telefone_1": "99999-9999",
  "email": "contato@empresa.com.br",
  "has_email": true,
  "has_website": false,
  "raiz_cnpj": "12345678",
  "regime_tributario": "Lucro Presumido",
  "ano_regime_tributario": 2024,
  "escrituracoes_regime_tributario": 1,
  "numero_funcionarios": "Entre 30 e 65"
}

Seção socios

Lista com os sócios e administradores que constam na Receita Federal. Pode vir vazia.

Dados de cada sócio

  • nome_socio: Nome completo do sócio
  • cnpj_cpf_socio: Sócio pessoa física: CPF mascarado no formato da Receita Federal (ex: "***456789**") ou null, nunca completo. Sócio pessoa jurídica: CNPJ completo, sem formatação.
  • cod_qualificacao: Código da qualificação do sócio
  • qualificacao_socio: Descrição da qualificação (ex: "Sócio-Administrador")
  • tipo_socio: Código do tipo (1=Pessoa Jurídica, 2=Pessoa Física, 3=Estrangeiro)
  • tipo_socio_descricao: Descrição do tipo de sócio
  • data_entrada: Data de entrada na sociedade
  • faixa_etaria: Faixa etária do sócio (apenas para pessoas físicas)
  • nome_repres, cpf_repres, cod_qualif_repres, qualificacao_representante: Nome, CPF, código de qualificação e qualificação do representante legal. O cpf_repres segue a mesma regra do CPF do sócio: mascarado ou null.
  • cod_pais_ext, pais_exterior: Código e nome do país, para sócio estrangeiro

Exemplo da seção socios

JSON
"socios": [
  {
    "nome_socio": "JOAO SILVA",
    "cnpj_cpf_socio": "***456789**",
    "cod_qualificacao": "49",
    "qualificacao_socio": "Sócio-Administrador",
    "tipo_socio": "2",
    "tipo_socio_descricao": "Pessoa Física",
    "data_entrada": "2020-01-15",
    "faixa_etaria": "41 a 50 anos",
    "cpf_repres": null
  }
]

Seção contatos_extras

Lista com e-mails, telefones, sites e redes sociais adicionais. Reúne os contatos de todos os estabelecimentos da mesma raiz de CNPJ (os 8 primeiros caracteres), ou seja, uma filial herda os contatos da matriz e das outras filiais, mais os contatos que a sua empresa cadastrou na Oportunidados.

Dados de cada contato

  • cnpj: CNPJ do estabelecimento de origem do contato
  • tipo_contato: Tipo do contato: "email", "phone" ou "url"
  • tipo_website: Para "url", "website" ou o nome da rede (ex: "facebook", "instagram", "linkedin"); null para e-mail e telefone
  • contato: O e-mail, o telefone ou a URL

Exemplo da seção contatos_extras

JSON
"contatos_extras": [
  {
    "cnpj": "12345678000190",
    "tipo_contato": "email",
    "tipo_website": null,
    "contato": "vendas@empresa.com.br"
  },
  {
    "cnpj": "12345678000271",
    "tipo_contato": "url",
    "tipo_website": "facebook",
    "contato": "https://facebook.com/empresa"
  }
]

Seção contexto

Objeto com comparativos da empresa: empresas_mesmo_cnae_cidade (empresas ativas no mesmo CNAE e município), ranking_capital_cidade_cnae (posicao e total), similares (uma lista curta de empresas parecidas) e obras (total e ativas). A chave obras só aparece quando a empresa tem obras cadastradas, e a contagem e o ranking podem vir null.

Códigos da Receita Federal

Porte

  • 00: Não informado
  • 01: Microempresa
  • 03: Empresa de Pequeno Porte
  • 05: Demais

Situação cadastral

  • 01: Nula (cadastro anulado)
  • 02: Ativa
  • 03: Suspensa
  • 04: Inapta perante a Receita Federal
  • 08: Baixada (a empresa encerrou as atividades)

Tipo de sócio

  • 1: Pessoa Jurídica
  • 2: Pessoa Física
  • 3: Estrangeiro

Ao processar a resposta

  1. Confira o código de status HTTP antes de ler o JSON. Os códigos estão em Erros e retentativas.
  2. Confira se as seções esperadas estão na resposta.
  3. As listas socios e contatos_extras podem vir vazias.
  4. Campos de texto podem vir como null.
  5. Valores numéricos, como capital_social, vêm como número decimal.
  6. Datas seguem o formato ISO (AAAA-MM-DD).
  7. cnpj e raiz_cnpj são strings, sem formatação. Guarde como texto: podem ter zeros à esquerda e letras.

Privacidade

  • Empresas removidas a pedido não são devolvidas por nenhuma operação da API nem pelo MCP.
  • O CPF de sócio pessoa física sai mascarado no formato da Receita Federal ou como null, nunca completo. O mesmo vale para o CPF do representante legal.
  • Os telefones e o e-mail de company vêm da Receita Federal. Os de contatos_extras reúnem os estabelecimentos da mesma raiz e os que a sua empresa cadastrou. A presença varia por empresa: veja de onde vêm os contatos.

Referência interativa: Swagger do app, com todos os parâmetros e exemplos de resposta.