> ## 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.
# APIs BOOM
> Documentação técnica para integrar sistemas de RH, BI e automações às APIs de cadastro, ao GPS de Cultura e ao sensor Conversas.
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](/core/cadastros/clusters) e [Colaboradores](/core/cadastros/colaboradores) no Core, o [GPS de Cultura](/gps/visao-geral) e [Conversas](/core/sensores/conversas).
## O que você encontra neste menu
Leitura dos indicadores do GPS: Index de Cultura, Gap da Liderança, engajamento, módulos, valores e comparativo de ciclos.
Contrato estável do sensor Conversas: listagem com recorte, detalhe com comentários, criação e edição.
CRUD da plataforma: conversa, participantes e comentários com anexo em `/core/v1/conversation*`.
Criação e manutenção de Unidades de Negócio, Diretorias, Departamentos, Alocações e White Labels.
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:
```http theme={null}
Authorization: Bearer
```
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**.
```http theme={null}
POST /core/v1/api-v2/tokens
Authorization: Bearer
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:
```json theme={null}
{
"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
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.
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.
Com as pessoas na base, preencha líderes, business partners e o campo `reportToClusterId` de cada cluster.
Liste os ciclos e consulte os widgets V2 com o token `bvt_`.
Dúvidas de integração: [ops@deumboom.com](mailto:ops@deumboom.com).
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.