> ## 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 Clusters

> Crie e mantenha a estrutura organizacional: Unidades de Negócio, Diretorias, Departamentos, Alocações e White Labels.

Clusters são os agrupamentos usados para **segmentar o GPS**, disparar pesquisas e aplicar permissões. Esta API replica o cadastro de [Clusters no Core](/core/cadastros/clusters).

<Info>
  Autenticação: JWT de usuário com `org_structure:read` / `org_structure:manage`. O token `bvt_` **não** acessa estas rotas. Veja [APIs BOOM](/api/visao-geral).
</Info>

Cadastre os clusters **antes** dos colaboradores. Os nomes precisam coincidir exatamente com o que o RH usa nas planilhas e no HRIS.

***

## Tipos

### Padrão (todas as empresas)

| Tipo | Recurso HTTP | ID no colaborador |
| - | - | - |
| Unidade de Negócio | `/core/v1/business-unit` | `businessUnitId` |
| Diretoria | `/core/v1/directorate` | `directorateId` |
| Departamento | `/core/v1/department` | `departmentId` |
| Alocação | `/core/v1/allocation` | `allocationId` |

### White Label (A–E)

Cinco eixos configuráveis (regional, cliente, centro de custo, etc.).

| Tipo | Recurso genérico | Alias tipado |
| - | - | - |
| A–E | `/core/v1/whitelabel-cluster` | `/core/v1/white-label-{a\|b\|c\|d\|e}` |

No colaborador: `whiteLabelAId` … `whiteLabelEId`.

### Hierarquia entre tipos

`/core/v1/company-cluster-hierarchy` define a **ordem** dos tipos na empresa (qual cluster "reporta a" qual tipo).

***

## Contrato comum (padrão)

Unidade, Diretoria, Departamento e Alocação seguem o mesmo CRUD. Substitua `{recurso}` e `{id}`.

| Método | Path | Permissão | Status |
| - | - | - | - |
| `POST` | `/core/v1/{recurso}` | `org_structure:manage` | 201 |
| `GET` | `/core/v1/{recurso}/read-all/{company-id}` | `org_structure:read` | 200 |
| `GET` | `/core/v1/{recurso}/{id}` | `org_structure:read` | 200 |
| `GET` | `/core/v1/{recurso}/{id}/change-log` | `org_structure:read` | 200 |
| `PUT` | `/core/v1/{recurso}` | `org_structure:manage` | 200 |
| `DELETE` | `/core/v1/{recurso}/{id}` | `org_structure:manage` | 204 |

`{recurso}` = `business-unit` · `directorate` · `department` · `allocation`

<Note>
  Em Diretoria, o `read-all` usa `{entity-id}` no path (`GET /core/v1/directorate/read-all/{entity-id}`), em geral o `companyId`.
</Note>

### Corpo de criação / atualização

Campos comuns:

```json theme={null}
{
  "companyId": "019e0253-377f-7b31-8500-c7c061778fa9",
  "name": "Comercial",
  "active": true,
  "reportToClusterId": null,
  "reportToClusterType": null
}
```

| Campo | Tipo | Obrigatório | Notas |
| - | - | - | - |
| `{recurso}Id` | uuid | no PUT | Identificador do registro |
| `companyId` | uuid | sim | Empresa |
| `name` | string | sim | Nome único e estável |
| `active` | boolean | sim | `false` inativa (preserva histórico) |
| `reportToClusterId` | uuid | não | Cluster ao qual este se subordina |
| `reportToClusterType` | string | não | Tipo do cluster pai (veja abaixo) |

`reportToClusterType` aceita (entre outros aliases): `BUSINESS_UNIT`, `DIRECTORATE`, `DEPARTMENT`, `ALLOCATION`, `WHITE_LABEL_A` … `WHITE_LABEL_E`.

Campos extras por tipo:

| Tipo | Campos adicionais |
| - | - |
| Diretoria | `parentId` (diretoria pai), `businessUnitId` |
| Departamento | `directorateDtos` (vínculos, na leitura) |
| Alocação | vínculos com diretorias e departamentos na leitura |

Na **criação**, envie só o essencial (`companyId`, `name`, `active`). Líderes, BPs e `reportTo*` entram depois que os colaboradores existirem.

### Exemplo — criar departamento

```bash theme={null}
curl -s -X POST "https://api.deumboom.com/core/v1/department" \
  -H "Authorization: Bearer ${JWT}" \
  -H "Content-Type: application/json" \
  -d '{
    "companyId": "019e0253-377f-7b31-8500-c7c061778fa9",
    "name": "Comercial",
    "active": true
  }'
```

```json theme={null}
{
  "departmentId": "019e9c85-e6b7-7638-b475-7b5fb36f1785",
  "companyId": "019e0253-377f-7b31-8500-c7c061778fa9",
  "name": "Comercial",
  "active": true,
  "createdAt": "2026-06-10T12:30:29.969913"
}
```

### Exemplo — listar

```http theme={null}
GET /core/v1/department/read-all/019e0253-377f-7b31-8500-c7c061778fa9
Authorization: Bearer ${JWT}
```

Usuários de liderança com recorte de escopo recebem **apenas** os departamentos acessíveis (o Core aplica o mesmo filtro na UI).

### Exemplo — atualizar (vínculo hierárquico)

```http theme={null}
PUT /core/v1/department
Content-Type: application/json

{
  "departmentId": "019e9c85-e6b7-7638-b475-7b5fb36f1785",
  "companyId": "019e0253-377f-7b31-8500-c7c061778fa9",
  "name": "Comercial",
  "active": true,
  "reportToClusterId": "019e9c85-c8b1-7a82-a594-ac6d88fa9f9f",
  "reportToClusterType": "DIRECTORATE"
}
```

### Change log

```http theme={null}
GET /core/v1/department/{department-id}/change-log?limit=50&offset=0
```

O mesmo padrão vale para os outros recursos (`business-unit`, `directorate`, `allocation`, `whitelabel-cluster`).

<Warning>
  A exclusão (`DELETE`) remove o registro. Na operação do Core a orientação é **inativar** (`active: false`) para preservar o histórico do GPS. Só exclua quando não houver ciclo vinculado — em dúvida, fale com a BOOM.
</Warning>

***

## White Label

### Recurso genérico

`/core/v1/whitelabel-cluster`

| Método | Path |
| - | - |
| `POST` | `/core/v1/whitelabel-cluster` |
| `GET` | `/core/v1/whitelabel-cluster/{whitelabel-cluster-id}` |
| `GET` | `/core/v1/whitelabel-cluster/read-all/{company-id}/{type}` |
| `PUT` | `/core/v1/whitelabel-cluster` |
| `DELETE` | `/core/v1/whitelabel-cluster/{whitelabel-cluster-id}` |

`{type}` no `read-all`: `A`, `B`, `C`, `D` ou `E`.

```json theme={null}
{
  "companyId": "019e0253-377f-7b31-8500-c7c061778fa9",
  "type": "A",
  "name": "Sul",
  "active": true
}
```

| Campo | Tipo | Notas |
| - | - | - |
| `whiteLabelClusterId` | uuid | Aliases aceitos no PUT: `whitelabelAId` … `whitelabelEId`, `id` |
| `type` | `A`–`E` | Eixo White Label |
| `name` | string | Nome do valor (ex.: "Sul") |
| `businessUnitId`, `directorateId`, `departmentId`, `allocationId` | uuid | Vínculos opcionais com clusters padrão |
| `reportToClusterId` / `reportToClusterType` | uuid / string | Hierarquia |

### Alias tipado (recomendado em integrações)

O path já fixa o eixo. Útil para o HRIS enviar um recurso por tipo:

```http theme={null}
POST   /core/v1/white-label-a
POST   /core/v1/white-label-a/bulk
GET    /core/v1/white-label-a/read-all/{company-id}
GET    /core/v1/white-label-a/{id}
PUT    /core/v1/white-label-a
DELETE /core/v1/white-label-a/{id}
```

O mesmo para `b`, `c`, `d`, `e` (case-insensitive; o servidor normaliza para `A`–`E`).

Carga em lote:

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

[
  { "companyId": "…", "name": "Sul", "active": true },
  { "companyId": "…", "name": "Sudeste", "active": true }
]
```

Atualização em lote do White Label **já vinculado a colaboradores**:

```http theme={null}
POST /core/v1/white-label-a/employee/bulk-update?companyId={companyId}
Content-Type: application/json

[
  { "employeeId": "…", "companyId": "…", "whiteLabelClusterId": "…" },
  { "employeeId": "…", "companyId": "…", "whiteLabelName": "Sul" }
]
```

Permissão desta rota: `employee:manage`.

***

## Hierarquia dos tipos na empresa

Define a ordem dos eixos (qual tipo é mais específico). Usada no cálculo de time e gestor imediato.

```http theme={null}
GET /core/v1/company-cluster-hierarchy/{company-id}
PUT /core/v1/company-cluster-hierarchy/{company-id}
```

`GET` exige `org_structure:read`. `PUT` exige `cluster_hierarchy:manage`.

```json theme={null}
[
  { "clusterType": "BUSINESS_UNIT", "position": 1, "excluded": false },
  { "clusterType": "DIRECTORATE", "position": 2, "excluded": false },
  { "clusterType": "DEPARTMENT", "position": 3, "excluded": false },
  { "clusterType": "ALLOCATION", "position": 4, "excluded": false },
  { "clusterType": "WHITE_LABEL_A", "position": 5, "excluded": true }
]
```

`excluded: true` tira o tipo das resoluções automáticas (o cadastro do cluster continua existindo).

***

## Líderes (opcional)

Depois dos colaboradores, associe líderes aos White Labels:

| Método | Path |
| - | - |
| `POST` | `/core/v1/whitelabel-cluster-leader` |
| `GET` | `/core/v1/whitelabel-cluster-leader/{id}` |
| `DELETE` | `/core/v1/whitelabel-cluster-leader/{id}` |

Há recursos equivalentes para líderes de Unidade, Diretoria, Departamento e Alocação (`/core/v1/business-unit-leader`, `directorate-leader`, `department-leader`, `allocation-leader`).

***

## Sequência de carga

<Steps>
  <Step title="Criar os clusters padrão">
    POST de Unidade → Diretoria → Departamento → Alocação, só com `name` e `active: true`.
  </Step>

  <Step title="Criar White Labels, se a empresa usar">
    POST (ou `/bulk`) em cada eixo A–E ativado na organização.
  </Step>

  <Step title="Importar colaboradores">
    Siga a [API de Cadastro de Colaboradores](/api/cadastro-colaboradores), referenciando os IDs retornados.
  </Step>

  <Step title="Atualizar reporta-a, líderes e BPs">
    PUT em cada cluster com `reportToClusterId` e cadastro de líderes.
  </Step>
</Steps>

***

## Perguntas frequentes

<AccordionGroup>
  <Accordion title="Posso criar cluster pelo nome na hora de cadastrar o colaborador?">
    Não para os tipos padrão: o colaborador exige `directorateId`, `departmentId`, etc. White Labels aceitam ID **ou** nome (`whiteLabelAName`).
  </Accordion>

  <Accordion title="Os campos White Label não aparecem no cadastro de pessoas.">
    O eixo precisa estar ativado nas configurações da organização. Sem isso, o Core não exibe o campo — a API ainda recusa um tipo inexistente.
  </Accordion>

  <Accordion title="Como inativar sem perder histórico?">
    `PUT` com `"active": false`. Evite `DELETE` em bases que já tiveram ciclo GPS.
  </Accordion>

  <Accordion title="Onde está o cadastro visual?">
    [Clusters no Core](/core/cadastros/clusters).
  </Accordion>
</AccordionGroup>


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