> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sherlocker.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Empresa

> Entidade de pessoa jurídica com dados cadastrais, sócios e contatos

Uma **Empresa** é identificada pelo CNPJ e representa uma pessoa jurídica registrada na Receita Federal.

## Tipagem

```json theme={null}
{
  "documento": "33.000.167/0001-01",
  "tipo_documento": "CNPJ",
  "cnpj_basico": "33000167",
  "razao_social": "Petroleo Brasileiro S A Petrobras",
  "nome_fantasia": "Petrobras - Edise",
  "situacao": "Ativa",
  "data_situacao": "2005-11-03",
  "motivo_situacao": "Sem Motivo",
  "data_abertura": "1966-09-28",
  "capital_social": 205431960490.52,
  "porte": "Média ou Grande Porte",
  "matriz_filial": "Matriz",
  "natureza_juridica": {
    "codigo": "2038",
    "descricao": "Sociedade de Economia Mista"
  },
  "atividade_principal": {
    "codigo": "0600001",
    "descricao": "Extração de petróleo e gás natural"
  },
  "atividades_secundarias": [
    { "codigo": "1921700", "descricao": "Fabricação de produtos do refino de petróleo" }
  ],
  "endereco": {
    "logradouro": "Avenida Republica do Chile",
    "numero": "65",
    "complemento": null,
    "bairro": "Centro",
    "cidade": "Rio de Janeiro",
    "uf": "RJ",
    "cep": "20031170"
  },
  "telefones": [
    {
      "ddi": "55",
      "ddd": "21",
      "numero": "21660000",
      "numero_completo": "552121660000",
      "estado": "RJ",
      "operadora": "Fixo"
    }
  ],
  "emails": [
    {
      "email": "contato@petrobras.com.br",
      "dominio": "petrobras.com.br",
      "corporativo": true
    }
  ],
  "socios": [
    {
      "nome": "Claudio Romeo Schlosser",
      "documento": "406.077.120-15",
      "tipo_documento": "CPF",
      "tipo": "Pessoa Física",
      "qualificacao": "Diretor",
      "data_entrada": "2023-04-17",
      "data_nascimento": "1964-04-15",
      "sexo": "Masculino",
      "idade": 61,
      "faixa_etaria": "Mais de 60 anos"
    }
  ],
  "situacao_especial": null,
  "data_situacao_especial": null
}
```

## Campos

| Campo                    | Tipo           | Descrição                                                                                                                                    |
| ------------------------ | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `documento`              | string         | CNPJ formatado (XX.XXX.XXX/XXXX-XX)                                                                                                          |
| `tipo_documento`         | string         | Sempre `"CNPJ"`                                                                                                                              |
| `cnpj_basico`            | string         | CNPJ raiz (8 dígitos)                                                                                                                        |
| `razao_social`           | string         | Razão social (Title Case)                                                                                                                    |
| `nome_fantasia`          | string \| null | Nome fantasia                                                                                                                                |
| `situacao`               | string         | `Ativa`, `Baixada`, `Suspensa`, `Inapta`, `Nula`                                                                                             |
| `data_situacao`          | string         | Data ISO da situação (YYYY-MM-DD)                                                                                                            |
| `motivo_situacao`        | string \| null | Motivo da situação cadastral (Title Case)                                                                                                    |
| `data_abertura`          | string         | Data ISO de início das atividades                                                                                                            |
| `capital_social`         | number         | Capital social em R\$                                                                                                                        |
| `porte`                  | string \| null | `Não Informado`, `Microempresa`, `Empresa de Pequeno Porte`, `Média ou Grande Porte`. Códigos não mapeados retornam o valor bruto da Receita |
| `matriz_filial`          | string \| null | `Matriz` ou `Filial`                                                                                                                         |
| `natureza_juridica`      | object         | `{ codigo: string, descricao: string }`                                                                                                      |
| `atividade_principal`    | object \| null | `{ codigo: string, descricao: string }` (CNAE)                                                                                               |
| `atividades_secundarias` | array          | CNAEs secundários `[{ codigo, descricao }]`                                                                                                  |
| `endereco`               | object         | Endereço completo                                                                                                                            |
| `telefones`              | array          | Telefones com DDD, operadora e estado                                                                                                        |
| `emails`                 | array          | Emails com domínio e flag corporativo                                                                                                        |
| `socios`                 | array          | Quadro societário                                                                                                                            |
| `situacao_especial`      | string \| null | Situação especial (se houver)                                                                                                                |
| `data_situacao_especial` | string \| null | Data da situação especial                                                                                                                    |

## Sócio

| Campo             | Tipo           | Descrição                                         |
| ----------------- | -------------- | ------------------------------------------------- |
| `nome`            | string         | Nome do sócio (Title Case)                        |
| `documento`       | string         | CPF ou CNPJ formatado                             |
| `tipo_documento`  | string         | `"CPF"` ou `"CNPJ"`                               |
| `tipo`            | string         | `"Pessoa Física"` ou `"Pessoa Jurídica"`          |
| `qualificacao`    | string         | Qualificação (Sócio-Administrador, Diretor, etc.) |
| `data_entrada`    | string         | Data ISO de entrada na sociedade                  |
| `data_nascimento` | string \| null | Data ISO de nascimento (só PF)                    |
| `sexo`            | string \| null | `"Masculino"` ou `"Feminino"` (só PF)             |
| `idade`           | number \| null | Idade calculada (só PF)                           |
| `faixa_etaria`    | string \| null | Faixa etária (só PF)                              |

## Pontos de entrada

| Dado disponível | Endpoint                            | Resultado                      |
| --------------- | ----------------------------------- | ------------------------------ |
| CNPJ            | `GET /empresas/cnpj/{cnpj}`         | Informações básicas + sócios   |
| CPF do sócio    | `GET /empresas/cpf/{cpf}`           | Empresas onde a pessoa é sócia |
| Email           | `GET /empresas/email/{email}`       | Empresas com esse email        |
| Telefone        | `GET /empresas/telefone/{telefone}` | Empresas com esse telefone     |

### Paginação

Os endpoints que retornam listas (`/cpf/{cpf}`, `/email/{email}`, `/telefone/{telefone}`, `/cnpj/{cnpj}/funcionarios`) suportam paginação via query params:

| Parâmetro | Tipo    | Padrão | Descrição                                |
| --------- | ------- | ------ | ---------------------------------------- |
| `limit`   | integer | 50     | Máximo de registros retornados (max 200) |
| `offset`  | integer | 0      | Número de registros a pular              |

```bash theme={null}
# Primeiros 10 funcionários
curl "https://221b-api.sherlocker.com.br/api/v1/empresas/cnpj/12345678000199/funcionarios?limit=10&token=SEU_TOKEN"

# Próximos 10
curl "https://221b-api.sherlocker.com.br/api/v1/empresas/cnpj/12345678000199/funcionarios?limit=10&offset=10&token=SEU_TOKEN"
```

## Consulte os códigos

Use `GET /empresas/codigos` para listar todos os valores possíveis de naturezas jurídicas, CNAEs, qualificações de sócios, situações e portes.

```bash theme={null}
# Todas as naturezas jurídicas
curl "https://221b-api.sherlocker.com.br/api/v1/empresas/codigos?tipo=naturezas&token=SEU_TOKEN"

# Todas as situações
curl "https://221b-api.sherlocker.com.br/api/v1/empresas/codigos?tipo=situacoes&token=SEU_TOKEN"
```