API de Cadastro de Clusters

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.

Autenticação: JWT de usuário com org_structure:read / org_structure:manage. O token bvt_ não acessa estas rotas. Veja APIs BOOM.

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

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

Corpo de criação / atualização

Campos comuns:

{
  "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

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
  }'

{
  "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

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)

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

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).

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.

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.

{
  "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:

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:

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:

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.

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.

[
  { "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

Criar os clusters padrão

POST de Unidade → Diretoria → Departamento → Alocação, só com name e active: true.

Criar White Labels, se a empresa usar

POST (ou /bulk) em cada eixo A–E ativado na organização.

Importar colaboradores

Siga a API de Cadastro de Colaboradores, referenciando os IDs retornados.

Atualizar reporta-a, líderes e BPs

PUT em cada cluster com reportToClusterId e cadastro de líderes.

Perguntas frequentes

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).

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.

Como inativar sem perder histórico?

PUT com "active": false. Evite DELETE em bases que já tiveram ciclo GPS.

Onde está o cadastro visual?

Clusters no Core.

Visão geral

GPS

Sensores

Cadastros

Tipos

Padrão (todas as empresas)

White Label (A–E)

Hierarquia entre tipos

Contrato comum (padrão)

Corpo de criação / atualização

Exemplo — criar departamento

Exemplo — listar

Exemplo — atualizar (vínculo hierárquico)

Change log

White Label

Recurso genérico

Alias tipado (recomendado em integrações)

Hierarquia dos tipos na empresa

Líderes (opcional)

Sequência de carga

Perguntas frequentes

​Tipos

​Padrão (todas as empresas)

​White Label (A–E)

​Hierarquia entre tipos

​Contrato comum (padrão)

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

​Exemplo — criar departamento

​Exemplo — listar

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

​Change log

​White Label

​Recurso genérico

​Alias tipado (recomendado em integrações)

​Hierarquia dos tipos na empresa

​Líderes (opcional)

​Sequência de carga

​Perguntas frequentes

Tipos

Padrão (todas as empresas)

White Label (A–E)

Hierarquia entre tipos

Contrato comum (padrão)

Corpo de criação / atualização

Exemplo — criar departamento

Exemplo — listar

Exemplo — atualizar (vínculo hierárquico)

Change log

White Label

Recurso genérico

Alias tipado (recomendado em integrações)

Hierarquia dos tipos na empresa

Líderes (opcional)

Sequência de carga

Perguntas frequentes