API de Cadastro de Colaboradores

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 do Core.

Autenticação: JWT com employee:read / employee:manage. O token bvt_ não acessa estas rotas. Cadastre os clusters antes das pessoas.

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.

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.

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

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

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.

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.

Consultar

Por ID

GET /core/v1/employee/{employee-id}

Lista curta da empresa

GET /core/v1/employee/read-all/{company-id}

Filtro paginado

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

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

PATCH /core/v1/employee/tax-identifier/{employee-id}
Content-Type: application/json

{ "taxIdentifier": "65749415040" }

Permissão: employee_tax_identifier:update.

Corrigir e-mail

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

DELETE /core/v1/employee/{employee-id}

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

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

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.

Gestor imediato

Prévia da resolução automática (líder do cluster mais específico, segundo a hierarquia da empresa):

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.

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

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

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.

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.

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

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.

Visão geral

GPS

Sensores

Cadastros

Recurso

Campos

Enums

Criar um colaborador

Carga em lote

Consultar

Por ID

Lista curta da empresa

Filtro paginado

Atualizar

Inativar / desligar

Corrigir CPF

Corrigir e-mail

Excluir

Gestor imediato

Perguntas frequentes

​Recurso

​Campos

​Enums

​Criar um colaborador

​Carga em lote

​Consultar

​Por ID

​Lista curta da empresa

​Filtro paginado

​Atualizar

​Inativar / desligar

​Corrigir CPF

​Corrigir e-mail

​Excluir

​Gestor imediato

​Login do colaborador (coleta)

​Perguntas frequentes

Recurso

Campos

Enums

Criar um colaborador

Carga em lote

Consultar

Por ID

Lista curta da empresa

Filtro paginado

Atualizar

Inativar / desligar

Corrigir CPF

Corrigir e-mail

Excluir

Gestor imediato

Login do colaborador (coleta)

Perguntas frequentes