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

# API de Cadastro de Colaboradores

> Inclua, atualize, consulte e inative a base de pessoas da organização, vinculada aos clusters usados no GPS e nos sensores.

O cadastro de colaboradores é a base a partir da qual a BOOM **dispara pesquisas**, **segmenta o GPS** e **calcula recortes** (liderança vs. liderados, geração, tempo de casa). Esta API replica o [Cadastro de Colaboradores](/core/cadastros/colaboradores) do Core.

<Info>
  Autenticação: JWT com `employee:read` / `employee:manage`. O token `bvt_` **não** acessa estas rotas. Cadastre os [clusters](/api/cadastro-clusters) antes das pessoas.
</Info>

***

## Recurso

Base: `/core/v1/employee`

| Método | Path | Permissão | Status |
| - | - | - | - |
| `POST` | `/core/v1/employee` | `employee:manage` | 201 |
| `POST` | `/core/v1/employee/bulk` | `employee:manage` | 201 |
| `POST` | `/core/v1/employee/read-filter` | `employee:read` | 200 |
| `POST` | `/core/v1/employee/read-filter-short` | `employee:read` | 200 |
| `GET` | `/core/v1/employee/read-all/{company-id}` | `employee:read` | 200 |
| `GET` | `/core/v1/employee/{employee-id}` | `employee:read` | 200 |
| `GET` | `/core/v1/employee/{employee-id}/change-log` | `employee:read` | 200 |
| `PUT` | `/core/v1/employee` | `employee:manage` | 200 |
| `DELETE` | `/core/v1/employee/{employee-id}` | `employee:manage` | 204 |
| `POST` | `/core/v1/employee/bulk-delete` | `employee:manage` | 204 |
| `PATCH` | `/core/v1/employee/tax-identifier/{employee-id}` | `employee_tax_identifier:update` | 204 |
| `PATCH` | `/core/v1/employee/{employee-id}/email` | `org_structure:manage` | 200 |
| `POST` | `/core/v1/employee/resolve-immediate-manager` | `employee:read` | 200 |

***

## Campos

| Campo | Tipo | Obrigatório | Notas |
| - | - | - | - |
| `employeeId` | uuid | no PUT | Gerado na criação |
| `companyId` | uuid | sim | Empresa |
| `name` | string | sim | Nome completo |
| `email` | string | condicional | Obrigatório se o canal incluir `EMAIL` |
| `taxIdentifier` | string | condicional | CPF só dígitos. Gravado com hash; na leitura **não** volta em claro |
| `whatsapp` | string | condicional | Obrigatório se o canal incluir `WHATSAPP` |
| `triggerChannel` | string ou string\[] | recomendado | `EMAIL`, `WHATSAPP`, `SLACK` (um valor ou lista) |
| `admissionDate` | date | **sim** | `YYYY-MM-DD`. Usado em Tempo de Casa |
| `birthDate` | date | não | Usado em Geração |
| `language` | string | não | Ex.: `pt-BR` |
| `employeeClassification` | enum | **sim** | `LIDERANCA` ou `COLABORADOR` |
| `hierarchyLevel` | string | recomendado | Nível hierárquico alinhado com a BOOM (1–5 na operação) |
| `active` | boolean | **sim** | `false` inativa |
| `directorateId` | uuid | conforme estrutura | Cluster já cadastrado |
| `businessUnitId` | uuid | conforme estrutura | |
| `departmentId` | uuid | conforme estrutura | |
| `allocationId` | uuid | conforme estrutura | |
| `whiteLabelAId` … `whiteLabelEId` | uuid | conforme config | Alternativa: `whiteLabelAName` … `EName` |
| `immediateManagerId` | uuid | não | Se omitido, o Core tenta resolver pelo líder do cluster |
| `terminationDate` | date | no desligamento | |
| `terminationType` | enum | no desligamento | ver abaixo |
| `observation` | string | não | |
| `alternativeChannelType` / `alternativeContactValue` | string | não | Canal alternativo (offboarding) |
| `slackUserId` | string | leitura | Preenchido pela integração Slack |

Campos `*Name` (`directorateName`, `departmentName`, …) são **somente leitura** na resposta. Na criação/atualização dos clusters padrão, envie o **ID**. White Labels aceitam ID **ou** nome.

<Warning>
  `employeeClassification` define **qual pesquisa de GPS** a pessoa recebe. Valor inválido → `"Classification is not valid"`. Não use labels de folha (CLT, PJ): use só `LIDERANCA` ou `COLABORADOR`.
</Warning>

### Enums

**Classificação**

| Valor | Significado |
| - | - |
| `LIDERANCA` | Responde o GPS de liderança |
| `COLABORADOR` | Responde o GPS de liderados |

**Canal de disparo (`triggerChannel`)**

`EMAIL` · `WHATSAPP` · `SLACK`

Pode ser string (`"EMAIL"`) ou lista (`["EMAIL","WHATSAPP"]`).

**Tipo de desligamento (`terminationType`)**

| Valor | Rótulo |
| - | - |
| `VOLUNTARY` | Voluntário |
| `INVOLUNTARY` | Involuntário |
| `END_OF_CONTRACT` | Fim de contrato |
| `RETIREMENT` | Aposentadoria |

**Nível hierárquico (convenção operacional)**

| Valor | Descrição |
| - | - |
| `1` | Presidência |
| `2` | Diretoria |
| `3` | Gerência |
| `4` | Supervisão |
| `5` | Operacional |

Alinhe a escala com o time BOOM antes da primeira carga.

**Status na leitura (`status`, calculado)**

| Valor | Quando |
| - | - |
| `ACTIVE` | Ativo |
| `ONBOARDING` | Admissão nos últimos 3 meses |
| `INACTIVE` | `active: false` ou `terminationDate` no passado |

O CPF, se enviado, precisa ser **válido e só números**. Na resposta ele aparece criptografado.

***

## Criar um colaborador

```bash theme={null}
curl -s -X POST "https://api.deumboom.com/core/v1/employee" \
  -H "Authorization: Bearer ${JWT}" \
  -H "Content-Type: application/json" \
  -d '{
    "companyId": "019e0253-377f-7b31-8500-c7c061778fa9",
    "name": "Mariana Costa",
    "email": "mariana.costa@empresa.com",
    "taxIdentifier": "65749415040",
    "whatsapp": "+5521998452378",
    "triggerChannel": "EMAIL",
    "birthDate": "1994-02-09",
    "admissionDate": "2024-03-15",
    "language": "pt-BR",
    "directorateId": "019e9c85-c8b1-7a82-a594-ac6d88fa9f9f",
    "departmentId": "019e9c85-e6b7-7638-b475-7b5fb36f1785",
    "allocationId": "019e9c86-1b03-7594-9770-dd4679fb09be",
    "hierarchyLevel": "3",
    "employeeClassification": "COLABORADOR",
    "active": true
  }'
```

Validações frequentes:

| Mensagem | Causa |
| - | - |
| `AdmissionDate is null, verify!` | Faltou `admissionDate` |
| `Active is null, verify!` | Faltou `active` |
| `Classification is not valid` | Valor fora de `LIDERANCA` / `COLABORADOR` |
| `Invalid CPF: …, verify!` | CPF inválido ou com máscara |
| `TriggerChannel is not valid: …` | Canal diferente de `EMAIL` / `WHATSAPP` / `SLACK` |
| `Department not found, verify!` | ID de cluster inexistente |
| `WhiteLabel A not found, verify!` | White Label inexistente (ID ou nome) |
| `Employee cannot be its own immediate manager, verify!` | Gestor = a própria pessoa |
| `Immediate manager must belong to the same company, verify!` | Gestor de outra empresa |

***

## Carga em lote

```http theme={null}
POST /core/v1/employee/bulk
Content-Type: application/json

[
  { "companyId": "…", "name": "…", "admissionDate": "2024-03-15", "employeeClassification": "COLABORADOR", "active": true },
  { "companyId": "…", "name": "…", "admissionDate": "2022-09-10", "employeeClassification": "LIDERANCA", "active": true }
]
```

A lista não pode ser vazia (`Employee list is empty. Verify input.`). Todos os itens passam pelo mesmo validador da criação unitária. Falha em **qualquer** linha aborta o lote.

<Tip>
  Para atualizar só o White Label de muita gente de uma vez, use `POST /core/v1/white-label-{a-e}/employee/bulk-update` na [API de Clusters](/api/cadastro-clusters).
</Tip>

***

## Consultar

### Por ID

```http theme={null}
GET /core/v1/employee/{employee-id}
```

### Lista curta da empresa

```http theme={null}
GET /core/v1/employee/read-all/{company-id}
```

### Filtro paginado

```http theme={null}
POST /core/v1/employee/read-filter
Content-Type: application/json

{
  "companyId": "019e0253-377f-7b31-8500-c7c061778fa9",
  "name": "Mariana",
  "departmentIdList": ["019e9c85-e6b7-7638-b475-7b5fb36f1785"],
  "employeeClassificationList": ["COLABORADOR"],
  "active": true,
  "page": 0,
  "size": 50
}
```

| Campo do filtro | Tipo |
| - | - |
| `companyId` | uuid |
| `name` | string (busca) |
| `directorateIdList`, `businessUnitIdList`, `departmentIdList`, `allocationIdList` | uuid\[] |
| `whiteLabelAIdList` … `whiteLabelEIdList` | uuid\[] |
| `hierarchyList` | string\[] |
| `employeeClassificationList` | string\[] |
| `immediateManagerIdList` | uuid\[] |
| `active` | boolean |
| `page` | int (0-based) |
| `size` | int (≥ 1) |

`read-filter-short` devolve a mesma página em formato reduzido e respeita o escopo do usuário logado (liderança vê só a árvore acessível).

`size` \< 1 → `"Size is less than 1, verify!"`.

***

## Atualizar

O `PUT` exige `employeeId` e os campos obrigatórios de novo (`admissionDate`, `active`, `employeeClassification`).

### Inativar / desligar

```json theme={null}
{
  "employeeId": "019e9cbd-19ba-79f1-b9de-17c5658f3600",
  "companyId": "019e0253-377f-7b31-8500-c7c061778fa9",
  "name": "Lucas Andrade",
  "admissionDate": "2021-02-01",
  "employeeClassification": "COLABORADOR",
  "active": false,
  "terminationDate": "2026-06-30",
  "terminationType": "INVOLUNTARY",
  "observation": "Desligamento"
}
```

### Corrigir CPF

O CPF não é editável no `PUT` (fica hasheado). Use:

```http theme={null}
PATCH /core/v1/employee/tax-identifier/{employee-id}
Content-Type: application/json

{ "taxIdentifier": "65749415040" }
```

Permissão: `employee_tax_identifier:update`.

### Corrigir e-mail

```http theme={null}
PATCH /core/v1/employee/{employee-id}/email
Content-Type: application/json

{ "email": "novo.email@empresa.com" }
```

Permissão: `org_structure:manage`. Atualiza o cadastro e o usuário vinculado, quando existir.

***

## Excluir

```http theme={null}
DELETE /core/v1/employee/{employee-id}

POST /core/v1/employee/bulk-delete
Content-Type: application/json

{ "employeeIds": ["…", "…"] }
```

<Warning>
  A recomendação operacional é **inativar** (`active: false`) para preservar o histórico do GPS. Exclusão definitiva apaga arquivos associados e só deve ocorrer quando não houver ciclo vinculado — em dúvida, fale com a BOOM.
</Warning>

***

## Gestor imediato

Prévia da resolução automática (líder do cluster mais específico, segundo a [hierarquia da empresa](/api/cadastro-clusters)):

```http theme={null}
POST /core/v1/employee/resolve-immediate-manager
Content-Type: application/json

{
  "companyId": "…",
  "directorateId": "…",
  "departmentId": "…",
  "excludeEmployeeId": "…"
}
```

Resposta: `{ "immediateManagerId", "immediateManagerName" }` (ambos nulos se não houver líder).

No `POST`/`PUT` do colaborador, envie `immediateManagerId` para **fixar** o gestor (`immediateManagerManuallySet: true` na leitura). Sem o campo, o Core tenta resolver sozinho.

***

## Login do colaborador (coleta)

Não faz parte do cadastro RH. Existe para o ambiente de pesquisa (`*.nossacultura.app`):

```http theme={null}
POST /core/v1/employee/login
POST /core/v2/employee/login
```

Rotas públicas (sem JWT de backoffice). Não use na integração de HRIS.

***

## Perguntas frequentes

<AccordionGroup>
  <Accordion title="Todo colaborador precisa de usuário no Core?">
    Não. Quem só responde pesquisa acessa o ambiente de coleta. Conta no Core é para RH, liderança e admins. Ver [Usuários](/core/cadastros/usuarios).
  </Accordion>

  <Accordion title="O nome do cluster na planilha precisa ser igual ao cadastrado?">
    Sim na importação pela UI. Na API, clusters padrão entram por **ID**; White Labels aceitam ID ou nome idêntico.
  </Accordion>

  <Accordion title="Por que o CPF volta irreconhecível na GET?">
    Ele é armazenado com hash. Para corrigir, use o `PATCH` de `tax-identifier` com o CPF em claro (só dígitos).
  </Accordion>

  <Accordion title="Dá para sincronizar com o HRIS de forma contínua?">
    Sim: crie/atualize pelos endpoints desta página e mantenha os IDs do lado do RH. Para desenho da sincronização, [ops@deumboom.com](mailto:ops@deumboom.com).
  </Accordion>
</AccordionGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.