APIs BOOM

As APIs da BOOM permitem que a organização mantenha a estrutura cadastral sincronizada com o sistema de RH, leia os indicadores do GPS de Cultura e registre conversas de gestão sem depender da interface do Core. Use esta documentação se você está:

Integrando um HRIS / ERP à base de clusters e colaboradores
Consumindo scores, módulos e indicadores do GPS em um BI, data warehouse ou agente
Automatizando a carga inicial de uma empresa
Lendo ou gravando o sensor Conversas (1:1, feedback, review de cultura) a partir de um agente ou integração

Esta é a documentação técnica (HTTP). Para o uso da plataforma no dia a dia, veja Clusters e Colaboradores no Core, o GPS de Cultura e Conversas.

GPS API V2

Leitura dos indicadores do GPS: Index de Cultura, Gap da Liderança, engajamento, módulos, valores e comparativo de ciclos.

Conversas API V2

Contrato estável do sensor Conversas: listagem com recorte, detalhe com comentários, criação e edição.

Conversas API V1

CRUD da plataforma: conversa, participantes e comentários com anexo em /core/v1/conversation*.

Cadastro de Clusters

Criação e manutenção de Unidades de Negócio, Diretorias, Departamentos, Alocações e White Labels.

Cadastro de Colaboradores

Inclusão, atualização, inativação e consulta da base de pessoas vinculada aos clusters.

Ambiente


Base URL	`https://api.deumboom.com`
Formato	JSON (`Content-Type: application/json`)
IDs	UUID (ex.: `019e0253-377f-7b31-8500-c7c061778fa9`)
Datas	`YYYY-MM-DD` (datas) e ISO-8601 (timestamps)
Timezone do GPS V2	`America/Sao_Paulo`

Autenticação

Todas as rotas exigem o header:

Authorization: Bearer <token>

Há dois tipos de token, com escopos diferentes:

Token	Prefixo	Uso
API V2	`bvt_…`	Somente leitura do GPS V2 (`GET /v2/gps/**`) e listagem de ciclos da empresa do token
JWT de usuário	`eyJ…`	Cadastros, Conversas (V1 e V2) e demais rotas do Core

O token bvt_ não autentica as APIs de cadastro nem o Conversas. Clusters, colaboradores e /v2/conversas exigem JWT (ou OAuth mct_… no conector) de um usuário com as permissões correspondentes.

Token de API V2 (GPS)

Gerado no backoffice, por empresa. O valor completo aparece somente na criação.

POST /core/v1/api-v2/tokens
Authorization: Bearer <jwt-admin>
Content-Type: application/json

{
  "companyId": "019e0253-377f-7b31-8500-c7c061778fa9",
  "name": "Integração BI",
  "permissions": ["gps:read", "cycle:read"]
}

Permissões disponíveis para o token V2:

Chave	Descrição
`gps:read`	Leitura dos endpoints `/v2/gps/**`
`cycle:read`	Listagem de ciclos da empresa
`dashboard:engajamento_read`	Leitura complementar de engajamento

Padrão na criação: gps:read + cycle:read. Listar: GET /core/v1/api-v2/tokens/company/{companyId}
Revogar: DELETE /core/v1/api-v2/tokens/{tokenId}
Catálogo de permissões: GET /core/v1/api-v2/tokens/permissions O token fica amarrado à empresa. Pedidos com companyId de outra organização são recusados.

JWT (cadastros e Conversas)

O JWT é o mesmo da sessão do Core. Permissões relevantes:

Chave	Uso
`org_structure:read`	Consultar clusters
`org_structure:manage`	Criar, editar e inativar clusters
`cluster_hierarchy:manage`	Definir a ordem hierárquica dos tipos de cluster
`employee:read`	Consultar colaboradores
`employee:manage`	Criar, editar, inativar e excluir colaboradores
`employee_tax_identifier:update`	Atualizar CPF
`conversation:read`	Consultar conversas (V1 e V2)
`conversation:manage`	Criar, editar e excluir conversas; comentar
`conversation_participant:read`	Consultar participantes (V1)
`conversation_participant:manage`	Vincular e remover participantes (V1)

Convenções de resposta

GPS V2

Todo endpoint V2 devolve o mesmo envelope:

{
  "meta": {
    "requestId": "uuid",
    "generatedAt": "2026-06-15T14:32:01-03:00",
    "timezone": "America/Sao_Paulo",
    "filters": { "companyId": "…", "cycleId": "…", "from": "…", "to": "…" }
  },
  "data": { },
  "errors": []
}

Cadastros (Core v1)

201 Created — recurso criado (corpo com o objeto)
200 OK — leitura ou atualização
204 No Content — exclusão / inativação sem corpo
Erros de validação e regras de negócio voltam como texto no corpo ("Company not found, verify!", "Classification is not valid", etc.)

Conversas

V1 (/core/v1/conversation*) — mesmo estilo dos cadastros (objeto ou página { page, size, totalElements, totalPages, data }; erros em texto)
V2 (/v2/conversas) — listagem paginada no mesmo envelope; detalhe com conversation + comments; recorte de perfil igual ao GPS V2 (403 explícito para GPS Admin Cliente)

Ordem recomendada de integração

Cadastrar os clusters

Crie Unidades de Negócio, Diretorias, Departamentos, Alocações e, se a empresa usar, White Labels A–E. Os nomes precisam ser estáveis: o cadastro de pessoas referencia esses IDs.

Cadastrar os colaboradores

Envie a base de pessoas já vinculada aos clusters. Classificação (LIDERANCA / COLABORADOR) e data de admissão são obrigatórias para o GPS.

Atualizar líderes e hierarquia

Com as pessoas na base, preencha líderes, business partners e o campo reportToClusterId de cada cluster.

Ler o GPS

Liste os ciclos e consulte os widgets V2 com o token bvt_.

Dúvidas de integração: ops@deumboom.com.

Visão geral

GPS

Sensores

Cadastros

O que você encontra neste menu

GPS API V2

Conversas API V2

Conversas API V1

Cadastro de Clusters

Cadastro de Colaboradores

Ambiente

Autenticação

Token de API V2 (GPS)

JWT (cadastros e Conversas)

Convenções de resposta

GPS V2

Cadastros (Core v1)

Conversas

Ordem recomendada de integração

​O que você encontra neste menu

GPS API V2

Conversas API V2

Conversas API V1

Cadastro de Clusters

Cadastro de Colaboradores

​Ambiente

​Autenticação

​Token de API V2 (GPS)

​JWT (cadastros e Conversas)

​Convenções de resposta

​GPS V2

​Cadastros (Core v1)

​Conversas

​Ordem recomendada de integração

O que você encontra neste menu

Ambiente

Autenticação

Token de API V2 (GPS)

JWT (cadastros e Conversas)

Convenções de resposta

GPS V2

Cadastros (Core v1)

Conversas

Ordem recomendada de integração