<!-- Documentacao da API de colaboradores da Pro Ocupacional (versao texto para leitura por IA).
     Pagina formatada: https://central.proocupacional.com.br/docs/api-colaboradores.html -->

# API de Colaboradores — dados do eSocial

**Base:** `https://central.proocupacional.com.br/api`
**Versão:** 11/11/2026 · Nova Central do Cliente (beta)

A API mostra os colaboradores de cada cliente com os dados do contrato (**matrícula, cargo, CBO, admissão e demissão**) já no valor mais confiável disponível. Ela também permite atualizar esses dados sem depender do SOC ou do SGG, de duas formas:

1. **Corrigir ou completar um colaborador** (`PUT`). O dado entra como fonte **CLIENTE**.
2. **Enviar o relatório oficial do eSocial** (`POST /colaboradores/esocial`). É o CSV "Relação de Trabalhadores" que o próprio cliente baixa no portal do eSocial com o certificado da empresa. O dado entra como fonte **ESOCIAL**, a de maior prioridade.

---

## 1. Autenticação

A API usa a mesma sessão da Central, um cookie `ncp.auth` válido por 12 horas e renovado com o uso.

```http
POST /api/login
Content-Type: application/json

{ "Email": "usuario@empresa.com.br", "Senha": "••••••" }
```

| Resposta | Significado |
|---|---|
| `200` | Logado. O cookie `ncp.auth` vem no `Set-Cookie` e deve ser enviado nas próximas chamadas. |
| `401` | E-mail ou senha inválidos. |

Para sair: `POST /api/logout`.

Sem o cookie, toda rota abaixo responde **`401`**.

### 1.1 Token de integração (para sistemas)

Um sistema de fora (folha, contabilidade, robô do cliente) usa um **token** em vez do login de tela. O token vai em todas as chamadas, no cabeçalho:

```http
Authorization: Bearer pro_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
```

- **Quem cria o token é a equipe Pró.** Cada token tem um nome (para quem é), um **escopo** e uma de duas permissões: **somente leitura** ou **leitura e atualização**. O escopo pode ser todas as empresas ou as empresas de um usuário da Central. O token também pode ter validade em dias.
- **O token aparece uma única vez**, na criação. A Pró guarda só uma impressão digital dele (hash SHA-256) e não consegue mostrar de novo. Se perder, é preciso criar outro e revogar o antigo.
- **O token só vale nas rotas `/api/empresas…` e `/api/colaboradores…`.** Qualquer outra rota da Central recusa o token com `401`.
- **Token somente leitura** em rota de atualização recebe `403` "Este token e somente leitura."
- **Token revogado, vencido ou de usuário desativado** recebe `401`.

**Na Central:** menu **Gestão › Tokens de API**, visível só para a equipe Pró. A tela cria o token (nome, escopo, permissão e validade), mostra o token uma vez com botão de copiar, lista os tokens com o último uso e a quantidade de usos, e revoga.

As mesmas ações pela API (só a equipe Pró, logada na tela):

| Ação | Rota |
|---|---|
| Criar | `POST /api/tokens` com `{ "Nome": "Folha da Empresa X", "UsuarioClienteId": 0, "PodeEscrever": true, "DiasValidade": 365 }` (`UsuarioClienteId` 0 = todas as empresas) |
| Listar | `GET /api/tokens` (mostra o prefixo, o escopo, o último uso e a quantidade de usos, nunca o token) |
| Revogar | `DELETE /api/tokens/{id}` |

**Escopo:** cada usuário vê e altera **somente os clientes e unidades liberados no cadastro de acesso dele**. Um colaborador fora do escopo responde como se não existisse (`404` ou `400` "fora do seu acesso"). A equipe Pró vê todos os clientes.

---

## 2. De onde vem cada dado (fontes e prioridade)

Cada campo guarda a sua **fonte**, devolvida pela API nos campos `*Fonte`:

| Fonte | O que é | Prioridade |
|---|---|---|
| `ESOCIAL` | O que a empresa declarou ao governo (relatório "Relação de Trabalhadores") | 1 (maior) |
| `CLIENTE` | Informado pelo cliente na Central ou por esta API | 2 |
| `ATENDIMENTO` | Veio da guia ou da ficha do exame | 3 |
| `SOC`, `SGG`, `PRO`, `GUIA`… | Cadastro do sistema de origem. Só aparece quando nenhuma fonte acima informou o campo | — |

**Regras de atualização:**

- **Matrícula, admissão e demissão** são fatos do contrato. Uma fonte de prioridade **igual ou maior** substitui o valor. Uma fonte menor **só preenche se o campo estiver vazio**. Exemplo: o cliente não consegue trocar uma matrícula que veio do eSocial. A resposta explica isso em `NaoAplicado`.
- **Cargo e CBO** mudam com o tempo. Vale o de **vigência mais recente**:
  - no eSocial, a vigência é a data da última alteração contratual (ou a admissão, se não houver alteração);
  - numa alteração feita pelo cliente, é a data em que ele alterou.

  Se o cliente muda o cargo hoje, o novo cargo vale até chegar um relatório do eSocial com alteração posterior. Em caso de empate na data, vale a fonte de maior prioridade.
- **Toda alteração fica no histórico**, com o valor anterior, o novo, a fonte e a referência (quem alterou ou qual arquivo trouxe).
- Quando o eSocial confirma o mesmo valor que o cliente informou, **a fonte passa a ser `ESOCIAL`** e o valor não muda.

---

## 3. Endpoints

### 3.0 Empresas

Uma **empresa** é um cliente da Pró, identificado pela raiz do CNPJ (8 dígitos). As unidades são os estabelecimentos dela (CNPJ completo).

```http
GET /api/empresas?busca=&comTotais=false&comEstabelecimentos=false&todas=false&pagina=1&tamanho=100
```

**Por padrão, vêm só as empresas com pelo menos um colaborador ativo** (ativo, afastado ou em férias). São cerca de 14 mil das 19 mil cadastradas; as demais são clientes antigos ou avulsos sem ninguém ativo. Use `todas=true` para trazer todas. A base junta os clientes do **SOC**, os do cadastro da Pró (que também vêm do SOC) e os do **SGG**.

Cada empresa traz `CnpjRaiz` (8 dígitos) e `CnpjMatriz` (14 dígitos: o estabelecimento ativo de menor CNPJ, o `0001` quando existe). Com `comEstabelecimentos=true`, traz também `Estabelecimentos`: a lista dos CNPJs completos de todos os estabelecimentos ativos que o token enxerga. O `CnpjMatriz` vem vazio para empregador pessoa física, cadastrado por CPF.

**Fluxo para um sistema de eSocial:**

1. `GET /api/empresas?comEstabelecimentos=true&tamanho=500`, página a página, para pegar todas as empresas do token com os CNPJs.
2. Para cada empresa, chamar `GET /api/empresas/cnpj/{CnpjRaiz}/colaboradores?tamanho=1000` para trazer a empresa inteira. Para um estabelecimento só, use o CNPJ de 14 dígitos dele. Cada colaborador traz `UnidadeCnpj`, o estabelecimento onde trabalha.
3. Nas rodadas seguintes, use `alteradosDesde` (ver "Sincronização").

| Parâmetro | Descrição |
|---|---|
| `busca` | Nome, nome fantasia, raiz do CNPJ ou CNPJ completo de uma unidade |
| `comTotais` | `true` traz, por empresa, os colaboradores ativos e quantos estão sem matrícula, cargo, CBO ou admissão. Deixa a consulta mais lenta quando o escopo tem muitas empresas |
| `todas` | `true` traz também as empresas sem nenhum colaborador ativo |
| `comEstabelecimentos` | `true` traz a lista dos CNPJs completos dos estabelecimentos |
| `pagina`, `tamanho` | O tamanho vai de 1 a 500, padrão 100. Cada página de 500 leva alguns segundos para a equipe Pró, que enxerga todas as empresas |

Os nomes saem sem os espaços sobrando que existem no cadastro de origem.

```json
{ "Total": 14102,
  "Itens": [ { "ClienteId": 10, "CnpjRaiz": "11222333", "CnpjMatriz": "11222333000101", "Nome": "EMPRESA EXEMPLO LTDA", "NomeFantasia": "Exemplo",
               "Estabelecimentos": ["11222333000101", "11222333000202"],
               "Ativo": true, "Unidades": 7, "UltimoArquivoEsocial": "2026-11-11T10:58:03",
               "Ativos": 224, "SemMatricula": 1, "SemCargo": 0, "SemCbo": 219, "SemAdmissao": 0 } ],
  "Pagina": 1, "Tamanho": 100 }
```

Os campos `Ativos` a `SemAdmissao` só vêm com `comTotais=true`.

```http
GET /api/empresas/{clienteId}
```

Devolve `Empresa` (os dados acima, mais CNAE e grau de risco) e `Unidades`. Cada unidade traz `UnidadeId`, `Tipo` (`J` para CNPJ ou `F` para CPF), `Inscricao` (o CNPJ completo), `RazaoSocial`, `NomeUnidade`, `Cidade`, `Uf` e `Ativo`. O `UnidadeId` é o que se usa para cadastrar colaborador novo.

```http
GET /api/empresas/{clienteId}/colaboradores?unidadeId=&situacao=&pendencia=&busca=&pagina=1&tamanho=500
```

Lista **todos os colaboradores da empresa**, com até 1000 por página. A resposta e os filtros são os mesmos da lista geral (3.1). Cada item traz também `ClienteId` e `UnidadeCnpj`.

**Para percorrer tudo:** chame `GET /api/empresas` para pegar as empresas. Depois, para cada empresa, chame `GET /api/empresas/{id}/colaboradores?pagina=1,2,3…` até somar o `Total`.

#### Pelo CNPJ (recomendado para sistemas de eSocial)

Se o sistema conhece a empresa pelo CNPJ, use estas rotas e não precisa do `ClienteId`:

```http
GET /api/empresas/cnpj/{cnpj}
GET /api/empresas/cnpj/{cnpj}/colaboradores?alteradosDesde=&situacao=&pendencia=&pagina=1&tamanho=1000
```

- `{cnpj}` vai **só com números**. A barra de `0001/…` quebra o endereço; pontos funcionam, mas é melhor evitar.
  - **8 dígitos** (raiz) traz a **empresa inteira**, com todos os estabelecimentos.
  - **14 dígitos** traz **só aquele estabelecimento**. Na resposta de `/empresas/cnpj/{cnpj}` vem `SoEsteEstabelecimento: true`.
- CNPJ fora do escopo do token ou inexistente devolve `404`.

#### Sincronização: só o que mudou (`alteradosDesde`)

Cada colaborador traz `AlteradoEm`, a última vez que mudou o contrato, o cadastro próprio, o eSocial ou a pessoa. A resposta traz `ConsultadoEm`, a hora do servidor no começo da consulta.

Rotina recomendada:

1. **Primeira carga:** chame sem `alteradosDesde`, percorra as páginas e guarde o `ConsultadoEm` da primeira página.
2. **Próximas rodadas:** chame com `alteradosDesde=<ConsultadoEm guardado>`. Vêm só as admissões, demissões e alterações desde então, ordenadas por `AlteradoEm`. Guarde o novo `ConsultadoEm`.
3. Uma rodada por dia costuma bastar. A carga interna do SOC/SGG roda a cada 30 minutos.

Se houver uma recarga completa do cadastro de origem, muitos colaboradores podem aparecer como alterados de uma vez, mesmo sem mudança real. Trate a sincronização como "atualizar se diferente", não como "evento novo".

#### Campos para montar os eventos do eSocial

Além dos campos da lista (3.1), cada colaborador traz:

| Campo | Conteúdo |
|---|---|
| `DataNascimento`, `Sexo` | Do cadastro da pessoa |
| `Categoria`, `CategoriaFonte` | Código da categoria do trabalhador (Tabela 01 do eSocial, ex.: `101`). Prioriza o eSocial e, sem ele, usa o SGG. Os vínculos vindos só do SOC costumam vir sem categoria |
| `Funcao`, `Regime` | Função e regime, quando o cadastro de origem informa |
| `UnidadeCnpj` | CNPJ do estabelecimento (local de trabalho) |
| `AlteradoEm` | Última alteração (ver acima) |

### 3.1 Listar colaboradores

```http
GET /api/colaboradores?clienteId=&cnpj=&unidadeId=&busca=&situacao=&pendencia=&alteradosDesde=&pagina=1&tamanho=25
```

| Parâmetro | Tipo | Descrição |
|---|---|---|
| `clienteId` | int | Uma empresa, pelo id da lista de empresas |
| `cnpj` | texto | Uma empresa pelo CNPJ, **só números**: raiz (8 dígitos) para a empresa inteira, completo (14 dígitos) para só aquele estabelecimento. CNPJ fora do acesso devolve `404` |
| `unidadeId` | int | Uma unidade (estabelecimento), pelo id de `/api/empresas/{id}` |
| `alteradosDesde` | data/hora | Só quem mudou a partir daqui (ver "Sincronização") |
| `busca` | texto | Nome, CPF (com ou sem pontuação), matrícula exata ou parte do cargo |
| `situacao` | int | `1` ativo · `2` afastado · `3` desligado · `4` candidato · `5` férias |
| `pendencia` | texto | `SemMatricula` · `SemCargo` · `SemCbo` · `SemAdmissao` · `Divergente` (eSocial diferente do cadastro) · `DesligadoNoEsocial` (ativo no cadastro, desligado no eSocial) · `Completo` |
| `pagina`, `tamanho` | int | Paginação. O tamanho vai de 1 a 1000, padrão 25 |

Sem `clienteId`, `cnpj` ou `unidadeId`, a lista traz todos os colaboradores do acesso. Para um usuário de uma empresa é a empresa dele; para a equipe Pró ou um token "todas as empresas" é a base inteira, que é mais lenta. Para integração, filtre sempre por empresa.

**Resposta `200`:**

```json
{
  "Kpis": {
    "Total": 1240, "Ativos": 1102,
    "SemMatricula": 37, "SemCargo": 0, "SemCbo": 214, "SemAdmissao": 12,
    "ConferidosNoEsocial": 1180, "Divergentes": 41, "DesligadosNoEsocial": 6,
    "Completos": 1015, "UltimoArquivoEsocial": "2026-11-11T10:58:03"
  },
  "Total": 41,
  "Itens": [
    {
      "VinculoId": 1844, "VinculoCadastroId": 26, "PessoaId": 2066,
      "Nome": "Fulana de Tal", "Cpf": 12345678909,
      "UnidadeId": 54, "Unidade": "EMPRESA EXEMPLO - FILIAL BH", "Setor": "Operação",
      "Matricula": "004587", "MatriculaFonte": "ESOCIAL",
      "Cargo": "Operadora de caixa", "Cbo": "421125", "CargoFonte": "ESOCIAL",
      "DataAdmissao": "2021-03-14T00:00:00", "AdmissaoFonte": "ESOCIAL",
      "DataDemissao": null, "DemissaoFonte": null,
      "Situacao": 1,
      "NoEsocial": true, "Divergencias": 2, "DesligadoNoEsocial": false, "Completo": true
    }
  ],
  "Pagina": 1, "Tamanho": 25
}
```

- Os `Kpis` contam o escopo inteiro, **antes** do filtro `pendencia`, para mostrar o tamanho do problema. O `Total` conta o resultado já filtrado.
- `VinculoId` é o vínculo no cadastro de origem. Quando vem `null`, o colaborador **só existe no cadastro próprio** (cadastrado pela API ou vindo do eSocial antes do SOC/SGG). Nesse caso use as rotas `/cadastro/{VinculoCadastroId}`.
- `Divergencias` é a quantidade de campos em que o eSocial difere do cadastro de origem (matrícula, cargo, CBO, admissão e desligamento). Vem `null` quando o colaborador ainda não apareceu em nenhum relatório do eSocial.

### 3.2 Detalhe de um colaborador

```http
GET /api/colaboradores/{vinculoId}
GET /api/colaboradores/cadastro/{vinculoCadastroId}
```

**Resposta `200`:**

```json
{
  "Colaborador": { "...": "mesmos campos da lista + Cliente, DataNascimento, Sexo, Funcao, MotivoDemissao, OrigemVinculo" },
  "Esocial": [
    { "EsocialVinculoId": 1, "Matricula": "004587", "DataAdmissao": "2021-03-14T00:00:00", "DataDesligamento": null,
      "CodCategoria": "101", "Categoria": "Empregado - Geral", "Cargo": "Operadora de caixa", "CboCargo": "421125",
      "EstabelecimentoInscricao": 11222333000505, "DataUltAlteracao": "2024-02-01T00:00:00",
      "Arquivo": "relacao_trabalhadores.csv", "ImportadoEm": "2026-11-11T10:58:03", "EsteContrato": true }
  ],
  "Divergencias": [ { "Esocial_Matricula": "004587", "Cadastro_Matricula": "4587", "MatriculaDifere": true, "...": "..." } ],
  "Historico": [
    { "Campo": "Cargo", "ValorAntes": "Auxiliar de loja | CBO 521110", "ValorDepois": "Operadora de caixa | CBO 421125",
      "FonteAntes": "CLIENTE", "Fonte": "ESOCIAL", "Referencia": "ESOCIAL:arquivo 12", "Em": "2026-11-11T10:58:03" }
  ]
}
```

- `Esocial` traz o que o governo tem para esse CPF nesse empregador. Pode ter mais de um contrato. `EsteContrato` marca o que corresponde a este vínculo.
- `Divergencias` compara o eSocial com o cadastro de origem (SOC/SGG).

**`404`** quando o colaborador não existe ou está fora do escopo.

### 3.3 Corrigir ou completar

```http
PUT /api/colaboradores/{vinculoId}
PUT /api/colaboradores/cadastro/{vinculoCadastroId}
Content-Type: application/json

{
  "Matricula": "004587",
  "Cargo": "Operadora de caixa",
  "Cbo": "4211-25",
  "DataAdmissao": "2021-03-14",
  "DataDemissao": null,
  "MotivoDemissao": null
}
```

Todos os campos são opcionais: envie só o que quer alterar. O CBO aceita `4211-25` ou `421125`.

**Resposta `200`:**

```json
{ "Ok": 1, "VinculoCadastroId": 26, "VinculoId": 1844, "Alteracoes": 1,
  "NaoAplicado": "Matricula mantida em 004587 (informada pelo ESOCIAL). " }
```

- `Alteracoes` é a quantidade de campos que mudaram de fato.
- `NaoAplicado` lista o que foi pedido e **não entrou** porque uma fonte mais forte vale mais. Vem `null` quando tudo foi aplicado.

**Erros `400`** (`{ "erro": "..." }`):

| Mensagem | Quando |
|---|---|
| `CBO deve ter 6 digitos (ex.: 4110-05).` | CBO fora do formato |
| `Data de admissao fora do esperado.` / `Data de demissao fora do esperado.` | Data antes de 1940 ou mais de 90 dias no futuro |
| `A demissao nao pode ser antes da admissao.` | Demissão anterior à admissão |
| `Nada para salvar.` | Corpo sem nenhum campo |
| `Colaborador fora do seu acesso.` | Vínculo de outro cliente |

### 3.3.1 Atualizar em lote (integração)

```http
PUT /api/colaboradores/lote
Authorization: Bearer pro_...
Content-Type: application/json

{
  "Itens": [
    { "Cpf": "390.533.447-05", "Cnpj": "11.222.333/0001-01", "Cargo": "Assistente administrativo", "Cbo": "4110-05" },
    { "Cpf": "12345678909", "ClienteId": 10, "MatriculaAtual": "004587", "DataDemissao": "2026-11-05", "MotivoDemissao": "02 - Rescisao sem justa causa" },
    { "VinculoId": 1585, "Matricula": "M1807" },
    { "Cpf": "11144477735", "ClienteId": 10, "CriarSeNaoExistir": true, "Nome": "Novo Colaborador", "UnidadeId": 54,
      "DataAdmissao": "2026-11-02", "Matricula": "L-9", "Cargo": "Auxiliar", "Cbo": "514320" }
  ]
}
```

São **até 500 itens por chamada**. Cada item indica **quem** é o colaborador por uma destas formas:

| Como identificar | Campos |
|---|---|
| Pelo id da lista | `VinculoId` ou `VinculoCadastroId` |
| Pelo CPF na empresa | `Cpf` + `ClienteId` **ou** `Cnpj` (raiz de 8 dígitos ou CNPJ completo de 14). Se o CPF tiver mais de um contrato na empresa (matrículas diferentes), informe também `MatriculaAtual` |

E diz **o que** atualizar, com os mesmos campos do `PUT` (3.3): `Matricula`, `Cargo`, `Cbo`, `DataAdmissao`, `DataDemissao` e `MotivoDemissao`. As mesmas regras de prioridade valem.

Com `CriarSeNaoExistir: true`, um CPF que não existe na empresa é cadastrado como colaborador novo. Para isso o item precisa de `Nome`, `UnidadeId` e `DataAdmissao`.

**Resposta `200`**, item a item, na mesma ordem do envio:

```json
{ "Total": 4, "Ok": 3, "Erros": 1,
  "Itens": [
    { "Indice": 0, "Ok": true, "Acao": "atualizado", "VinculoId": 1843, "VinculoCadastroId": 31, "Alteracoes": 2, "NaoAplicado": null,
      "MesmoContrato": 2, "VinculosMesmoContrato": "1907,2210", "Erro": null },
    { "Indice": 1, "Ok": false, "Erro": "Mais de um contrato para esse CPF: informe a matricula." },
    { "Indice": 2, "Ok": true, "Acao": "atualizado", "VinculoId": 1585, "Alteracoes": 0, "NaoAplicado": "Matricula mantida em M1807 (informada pelo ESOCIAL). " },
    { "Indice": 3, "Ok": true, "Acao": "criado", "VinculoId": null, "VinculoCadastroId": 54, "Alteracoes": 3 }
  ] }
```

Um item com erro **não impede os outros**. Corrija e reenvie só os itens que falharam.

| Erro do item | Quando |
|---|---|
| `Informe VinculoId, VinculoCadastroId ou Cpf + empresa.` | Faltou a identificação |
| `Empresa nao encontrada no seu acesso.` | `ClienteId` ou `Cnpj` fora do escopo do token |
| `Colaborador nao encontrado nessa empresa.` | CPF sem contrato na empresa. Use `CriarSeNaoExistir` para cadastrar |
| `Mais de um contrato para esse CPF: informe a matricula.` | O CPF tem contratos com matrículas diferentes (ou sem matrícula) na empresa. Informe `MatriculaAtual` ou mande pelo `VinculoId` |
| Mensagens do `PUT` (CBO, datas, acesso) | Validação do dado |

#### O mesmo contrato em mais de um vínculo

Na lista, a mesma pessoa pode aparecer mais de uma vez na mesma empresa com a **mesma matrícula**, cada vez numa unidade, com o mesmo `PessoaId` e `VinculoId` diferentes. Não são contratos diferentes: é o mesmo contrato que chegou à Pró por mais de um sistema de origem, ou que ficou na loja antiga depois de uma transferência. Para o eSocial, matrícula é única por empregador.

Por isso:

- **Mande um item só por contrato**, usando qualquer um dos `VinculoId` com aquela matrícula. A API aplica a mesma atualização em **todos** os vínculos da pessoa com a mesma matrícula na mesma empresa (raiz do CNPJ).
- A resposta diz quantos e quais vínculos também foram atualizados: `MesmoContrato` (quantidade) e `VinculosMesmoContrato` (ids separados por vírgula).
- No envio por CPF, se todos os vínculos do CPF na empresa têm a mesma matrícula, a API **não** pede `MatriculaAtual`: é um contrato só.
- Matrículas **diferentes** para o mesmo CPF continuam sendo contratos separados: um item por `VinculoId` (ou por CPF + `MatriculaAtual`).

Exemplo: a pessoa tem os vínculos 231003, 235280 e 253612, todos com matrícula 67682. Um item com `"VinculoId": 231003` e a admissão do eSocial corrige os três. A resposta traz `"MesmoContrato": 2, "VinculosMesmoContrato": "235280,253612"`.

### 3.4 Cadastrar colaborador novo

```http
POST /api/colaboradores
Content-Type: application/json

{
  "Cpf": "529.982.247-25",
  "Nome": "Novo Colaborador",
  "UnidadeId": 54,
  "Matricula": "N-001",
  "Cargo": "Auxiliar de serviços gerais",
  "Cbo": "514320",
  "DataAdmissao": "2026-11-01"
}
```

`Cpf` (válido), `Nome`, `UnidadeId` (do seu escopo) e `DataAdmissao` são obrigatórios. A resposta é igual à do `PUT`, com `VinculoId: null`. O colaborador passa a aparecer na lista na hora, mesmo antes de existir no SOC ou no SGG.

O cadastro é recusado quando o mesmo CPF já está **ativo** no cliente com a mesma admissão ou a mesma matrícula. Nesse caso, a mensagem orienta a abrir o cadastro existente.

### 3.5 Enviar o relatório do eSocial (CSV)

O cliente baixa o relatório no portal do eSocial, com o certificado da própria empresa:

1. Acesse **login.esocial.gov.br** e entre com o certificado digital.
2. Abra o card **Emissão de Relatórios Gerenciais**.
3. Clique em **Solicitar Novo Relatório**, escolha **"Relação de Trabalhadores – eSocial"** e marque **"Todos os vínculos"**.
4. O relatório fica pronto em alguns minutos ou horas. Quando a situação for **Processado**, baixe em **CSV**.

Depois envie o arquivo:

```http
POST /api/colaboradores/esocial
Content-Type: multipart/form-data

arquivo=<relacao_trabalhadores.csv>
```

**Resposta `200`:**

```json
{
  "Resultado": { "Ok": 1, "EsocialArquivoId": 10, "Cliente": "EMPRESA EXEMPLO LTDA",
                 "Linhas": 1240, "Inseridas": 12, "Atualizadas": 1228, "Vinculadas": 1180, "Rejeitadas": 3,
                 "AlteracoesNoCadastro": 57 },
  "ColunasNaoEncontradas": []
}
```

| Campo | Significado |
|---|---|
| `Linhas` | Linhas de trabalhador lidas no arquivo |
| `Inseridas` / `Atualizadas` | Contratos novos e contratos já conhecidos |
| `Vinculadas` | Contratos ligados a um vínculo do cadastro de origem |
| `Rejeitadas` | Linhas recusadas (CPF inválido, linha repetida, sem matrícula e sem data de início) |
| `AlteracoesNoCadastro` | Campos que mudaram no cadastro por causa deste arquivo |
| `ColunasNaoEncontradas` | Colunas esperadas que o arquivo não trouxe (os campos ficam vazios) |

**Regras do envio:**

- Aceita **apenas CSV**, de até **200 MB** (o portal gera até 500 mil linhas em CSV). O separador pode ser `;`, `,` ou TAB, e a codificação UTF-8 ou Windows-1252. Linhas de título antes do cabeçalho são ignoradas.
- As colunas obrigatórias são **Número de Inscrição do Empregador**, **CPF do Trabalhador**, **Matrícula** e **Data de Admissão**.
- O **empregador do arquivo precisa ser um cliente do escopo** de quem envia. Caso contrário, nada é importado: `400` "O arquivo e de uma empresa que nao esta no seu acesso." Linhas de outro empregador dentro do mesmo arquivo são descartadas.
- **O mesmo arquivo não entra duas vezes** (a comparação é pelo conteúdo): `400` "Esse arquivo ja foi importado em dd/mm/aaaa." Um relatório novo, mesmo com o mesmo nome, é aceito normalmente.
- Os vínculos que existem no eSocial e ainda não estão no cadastro entram como **colaboradores novos**.

### 3.6 Arquivos enviados

```http
GET /api/colaboradores/esocial/arquivos
```

Devolve os últimos 50 envios do escopo, com `EsocialArquivoId`, `NomeArquivo`, `Cliente`, `Linhas`, `Inseridas`, `Atualizadas`, `Vinculadas`, `Rejeitadas`, `Situacao` (`Importado` · `Erro` · `Carregando`), `Erro` e `ImportadoEm`.

---

## 4. Exemplos com `curl`

```bash
# login (guarda o cookie em cookies.txt)
curl -c cookies.txt -H "Content-Type: application/json" \
     -d '{"Email":"usuario@empresa.com.br","Senha":"SUA_SENHA"}' \
     https://central.proocupacional.com.br/api/login

# ativos sem CBO
curl -b cookies.txt "https://central.proocupacional.com.br/api/colaboradores?situacao=1&pendencia=SemCbo&tamanho=100"

# corrigir cargo e CBO
curl -b cookies.txt -X PUT -H "Content-Type: application/json" \
     -d '{"Cargo":"Operadora de caixa","Cbo":"4211-25"}' \
     https://central.proocupacional.com.br/api/colaboradores/1844

# enviar o relatório do eSocial
curl -b cookies.txt -F "arquivo=@relacao_trabalhadores.csv" \
     https://central.proocupacional.com.br/api/colaboradores/esocial
```

Com token de integração (sem login):

```bash
TOKEN="pro_..."

# empresas do escopo do token
curl -H "Authorization: Bearer $TOKEN" "https://central.proocupacional.com.br/api/empresas?tamanho=500"

# colaboradores de uma empresa (página 1, 1000 por página)
curl -H "Authorization: Bearer $TOKEN" "https://central.proocupacional.com.br/api/empresas/10/colaboradores?tamanho=1000&pagina=1"

# pelo CNPJ: empresa inteira (raiz) e só o que mudou desde a última rodada
curl -H "Authorization: Bearer $TOKEN" "https://central.proocupacional.com.br/api/empresas/cnpj/11222333/colaboradores?tamanho=1000&alteradosDesde=2026-11-10T08:00:00"

# só um estabelecimento (CNPJ completo, só números)
curl -H "Authorization: Bearer $TOKEN" "https://central.proocupacional.com.br/api/empresas/cnpj/11222333000505/colaboradores?tamanho=1000"

# atualização em lote
curl -X PUT -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
     -d '{"Itens":[{"Cpf":"39053344705","Cnpj":"11222333","Cargo":"Assistente administrativo","Cbo":"411005"}]}' \
     https://central.proocupacional.com.br/api/colaboradores/lote
```

---

## 5. Códigos de resposta

| Código | Quando |
|---|---|
| `200` | Sucesso |
| `400` | Validação recusada. O corpo traz `{ "erro": "mensagem" }` |
| `401` | Sem sessão (faça o login), token inválido, vencido ou revogado, ou token usado numa rota que não é de integração |
| `403` | Token somente leitura numa rota de atualização, ou rota só da equipe Pró |
| `404` | Colaborador não encontrado no seu acesso |
| `500` | Erro inesperado no servidor. Tente de novo e, se repetir, avise a equipe Pró |