Dados retornados pela API: JSON com empresa, sócios e contatos

Estrutura JSON completa: dados cadastrais, endereço, telefones, email, CNAEs, sócios com qualificação, faixa etária e contatos extras.

A API retorna dados em formato JSON estruturado em quatro seções principais:

1. company: Dados cadastrais completos da empresa
2. socios: Lista de sócios e administradores
3. contatos_extras: E-mails, telefones, sites e redes sociais adicionais
4. contexto: Comparativos da empresa (mesmo CNAE e município, ranking, similares e obras)

Seção: Company (Dados Cadastrais)

Esta seção contém todas as informações cadastrais da empresa.

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: Indica se é MATRIZ ou FILIAL

Atividade Econômica:

• cnae_fiscal: CNAE principal (formato: código/subclasse)
• cnaes_secundarios: Array com 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: Status da empresa (ATIVA, SUSPENSA, BAIXADA, etc.)
• data_situacao: Data da situação cadastral
• motivo_situacao: Motivo da situação cadastral
• data_inicio_atividade: Data de início das atividades

Informações Financeiras:

• capital_social: Capital social da empresa (número decimal)
• porte: Código do porte da empresa (01=Micro, 03=Pequena, 05=Demais)
• faturamento: Faixa de faturamento derivada do porte, ou "Não disponível". Não é o faturamento real da empresa.
• opc_simples: Se optante do Simples Nacional (SIM/NÃO)
• data_opc_simples: Data da opção pelo Simples
• data_exc_simples: Data de exclusão do Simples
• opc_mei: Se é MEI (SIM/NÃO)
• data_opc_mei: Data de opção pelo MEI
• data_exc_mei: Data de exclusão do MEI
• regime_tributario: Regime tributário declarado (ex: "Lucro Real", "Lucro Presumido", "Simples Nacional")
• ano_regime_tributario: Ano de referência do regime tributário (inteiro, ex: 2024)
• 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 Black, Diamante, Enterprise e Expansão, inclusive os anuais; a chave fica ausente quando o plano não inclui a contagem de funcionários.

Endereço:

• tipo_logradouro: Tipo do logradouro (RUA, AVENIDA, etc.)
• logradouro: Nome do logradouro
• numero: Número do endereço
• complemento: Complemento do endereço
• bairro: Bairro
• cep: CEP (formato: 00000-000)
• 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: Email principal cadastrado
• has_email: Boolean indicando se possui email
• has_website: Boolean indicando se possui website

Exemplo Completo de Dados de Company

"company": {
  "cnpj": "12345678000190",
  "razao_social": "EMPRESA EXEMPLO LTDA",
  "nome_fantasia": "Empresa Exemplo",
  "cnae_fiscal": "6201-5/00",
  "cnaes_secundarios": ["6202-3/00", "6203-1/00"],
  "data_inicio_atividade": "2020-01-15",
  "situacao_cadastral": "ATIVA",
  "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": "SIM",
  "data_opc_simples": "2020-01-15",
  "opc_mei": "NÃO",
  "matriz_filial": "MATRIZ",
  "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": "[email protected]",
  "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: Sócios

Array contendo informações de todos os sócios e administradores da empresa.

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 de Dados de Sócios

"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

Array 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 de Contatos Extras

"contatos_extras": [
  {
    "cnpj": "12345678000190",
    "tipo_contato": "email",
    "tipo_website": null,
    "contato": "[email protected]"
  },
  {
    "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 (até 5 empresas) 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.

Interpretando os Códigos

Códigos de Porte:

• 01: Microempresa
• 03: Empresa de Pequeno Porte
• 05: Demais (Média ou Grande)

Situações Cadastrais Comuns:

• ATIVA: Empresa em funcionamento regular
• SUSPENSA: Atividades temporariamente suspensas
• INAPTA: Empresa inapta perante a Receita Federal
• BAIXADA: Empresa encerrou suas atividades
• NULA: Cadastro anulado

Tipo de Sócio:

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

Processando as Respostas

1. Sempre verifique o código de status HTTP antes de processar o JSON
2. Valide se as seções esperadas estão presentes na resposta
3. Os arrays (socios e contatos_extras) podem estar vazios
4. Campos de texto podem conter valores null
5. Valores numéricos como capital_social são retornados como float
6. Datas seguem o formato ISO (YYYY-MM-DD)
7. cnpj e raiz_cnpj são strings, sem formatação. Guarde como texto: podem ter zeros à esquerda e letras