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

# Sensor de Jornada API

> Referência HTTP somente leitura do Sensor de Jornada: visão geral, triggers, disparos e respostas do colaborador.

A **Sensor de Jornada API** expõe, em JSON, o que a plataforma mostra no Sensor de Jornada: colaboradores, regras de jornada (triggers) e disparos com o score de cada um. É a mesma API usada pelo [conector BOOM](https://suporte.deumboom.com/api/conector-jornada.md).

É **somente leitura**. Criar, editar, duplicar ou excluir triggers, disparo manual, reenvio e envio de notificações pendentes não fazem parte deste contrato.

> [!NOTE]
>
> A especificação OpenAPI está em [`jornada.openapi.yaml`](https://suporte.deumboom.com/api/jornada.openapi.yaml). Valide cada chamada no ambiente de **homologação** antes de usar em produção.

***

## Servidores

| Ambiente | Base URL | Uso |
| - | - | - |
| Produção | `https://api.deumboom.com` | Dados reais |
| Homologação (HML) | `https://apihomolog.deumboom.com` | Testes e validação de integração |

## Autenticação

```http theme={null}
Authorization: Bearer <token>
```

| Token | Prefixo | Aceito |
| - | - | - |
| JWT de usuário | `eyJ…` | Sim |
| OAuth do conector | `mct_…` | Sim |
| Token de API V2 | `bvt_…` | **Não** |

Permissões exigidas: `employee:read` (visão geral) e `survey_template:read` (triggers, disparos e respostas). A empresa do `companyId` precisa ser a do usuário autenticado.

***

## Endpoints

| Grupo | Método e path | Tool do conector | Paginado |
| - | - | - | - |
| Visão geral | `POST /core/v1/employee/read-filter/journey-sensor` | `core_jornada_overview` | Sim |
| Triggers | `GET /core/v1/journey-trigger/{companyId}` | `core_jornada_triggers_list` | Não |
| Disparos | `GET /core/v1/journey-dispatch/{companyId}` | `core_jornada_disparos_list` | Não |
| Perfil do colaborador | `POST /core/v1/journey-trigger-audience/answers` | Ainda sem tool | Não |

Os dois `POST` usam esse método apenas porque recebem filtros ou IDs no corpo. Nenhum deles altera dados.

### Filtros por endpoint

**Visão geral** (corpo JSON, `companyId` obrigatório):

| Filtro | Situação |
| - | - |
| `name`, `active`, `employeeClassificationList`, `departmentIdList`, `directorateIdList`, `businessUnitIdList`, `page`, `size` | Aceito e enviado pelo conector |
| `allocationIdList`, `whiteLabelAIdList` a `whiteLabelEIdList`, `hierarchyList`, `immediateManagerIdList` | Aceito pela API, **não enviado** pelo conector |
| `employmentStatusList`, `language` | **Ignorado**: aceito sem erro, mas sem efeito |

**Triggers** e **Disparos**: não têm filtros. Query string é ignorada e a lista completa da empresa é devolvida.

**Respostas** (corpo JSON): `journeyTriggerAudienceIds`, lista de IDs de disparo (os `journeyTriggerAudienceId` devolvidos em Disparos).

***

## Perfis de acesso

| Perfil | Visão geral | Triggers | Disparos |
| - | - | - | - |
| Admin Cliente | Organização inteira | Todos da empresa | Toda a empresa |
| RH Estratégico | Organização inteira | Todos da empresa | Toda a empresa |
| RH Business Partner | Árvore de "reporta a" do Colaborador vinculado | Todos da empresa (configuração, sem dado individual) | Somente disparos do recorte |
| Liderança | Árvore de "reporta a" do Colaborador vinculado | Todos da empresa (configuração, sem dado individual) | Somente disparos do recorte |
| GPS Admin Cliente | Sem acesso | `403` | `403` |

* Os dados são **individuais** (nome, e-mail, score por disparo). Não há endpoint agregado nem regra de anonimato mínimo.
* Perfil sem acesso recebe **`403`**, nunca lista vazia.
* Triggers descrevem a configuração da empresa e não trazem dado de pessoa.

***

## Papel: colaborador e líder

Um disparo é do **líder** quando `onBehalfOfEmployeeId` está preenchido: o líder responde *em nome* daquele colaborador. Com `onBehalfOfEmployeeId = null`, o disparo é do próprio colaborador.

### "Líder não precisa responder" × "líder não respondeu"

| Situação | Como aparece | Score |
| - | - | - |
| **Não precisa responder** | **Não existe** linha de disparo do líder para aquele colaborador e trigger | Conta só o score do colaborador |
| **Não respondeu** | **Existe** linha com `onBehalfOfEmployeeId` preenchido e `status` diferente de `ANSWERED` | `score = null` |

O líder **não precisa** responder quando o trigger tem `sendToManager = false` (em triggers de ciclo é sempre `true`), quando o colaborador não tem gestor imediato ativo ou quando o template não tem perguntas para a Liderança. Ausência de linha **não** é falta de resposta.

***

## Score, faixas e fases

* `score` é inteiro de **0 a 1000** e só existe em disparos `ANSWERED` com perguntas pontuáveis.
* `countedForScore = false` indica que o trigger não conta para o score do colaborador.
* **O score por pergunta dos templates não é retornado.** A API devolve o score final do disparo e, em Respostas, só o texto da resposta.

| Faixa | Intervalo |
| - | - |
| `CRITICO` | 0 a 200 |
| `FRAGIL` | 201 a 400 |
| `ATENCAO` | 401 a 600 |
| `SAUDAVEL` | 601 a 800 |
| `FORTE` | 801 a 1000 |

A faixa é uma interpretação da plataforma: a API devolve só o número.

### Fases da jornada

`ENTRY` (Entrada), `DEVELOPMENT` (Desenvolvimento) e `EXIT` (Saída) pertencem ao **tipo** do trigger. Os endpoints devolvem apenas `journeyTriggerTypeId`, **sem a fase** e sem o slug do tipo. Os IDs de tipo mudam por ambiente, então não use-os fixos no código.

| Tipo padrão | Fase |
| - | - |
| Preboarding, Onboarding 30 dias, Onboarding 75 dias | Entrada |
| Check-in periódico, Aniversário de admissão, Ciclos da empresa, Promoção ou mudança de cargo, Mudança de setor, Troca de gestor, Após ciclo de feedback, Queda de engajamento detectada | Desenvolvimento |
| Offboarding Voluntário, Offboarding Involuntário, Pós-desligamento (alumni) | Saída |

Empresas também podem ter tipos próprios, que não aparecem nesta tabela.

***

## Enums

| Campo | Valores |
| - | - |
| `status` do disparo | `PENDING`, `SENT`, `ANSWERED`, `EXPIRED`, `FAILED`, `SKIPPED` |
| `skipReason` (só em `SKIPPED`) | `OUTSIDE_WINDOW`, `BEFORE_EFFECTIVE_DATE`, `TRIGGER_INACTIVE`, `HR_DECISION` |
| `employeeClassification` | `LIDERANCA`, `COLABORADOR` |
| `status` do colaborador | `ONBOARDING`, `ACTIVE`, `AFASTADO`, `DESLIGADO`, `INATIVO_LEGADO` |
| `terminationType` | `VOLUNTARY`, `INVOLUNTARY`, `END_OF_CONTRACT`, `RETIREMENT` |
| `channel` | `EMAIL`, `WHATSAPP`, `SLACK`, `TEAMS` |
| `leaderDeadlineMode` | `DAYS`, `CYCLE_END` |

O trigger só tem o booleano `active`. Não existe enum de status de trigger.

***

## Paginação e limite de uso

* Só a **visão geral** pagina: `page` começa em `0`; o conector usa `size = 20` por padrão. A resposta traz `page`, `size`, `totalElements`, `totalPages` e `data`.
* Triggers e disparos devolvem a lista completa da empresa.
* A aplicação não impõe limite por requisição para JWT e `mct_` nestas rotas e não devolve `429`. O limite de 120 requisições por 60 segundos vale só para `bvt_`, que não é aceito aqui. A infraestrutura pode aplicar um limite próprio. Boa prática: no máximo 1 requisição por segundo por token.

***

## Erros

Não existe código interno de erro. Identifique cada erro por **HTTP + `message`**.

```json theme={null}
{
  "timestamp": "2026-10-16T14:55:00-03:00",
  "status": 403,
  "error": "Forbidden",
  "message": "Access denied: No policy match",
  "path": "/core/v1/journey-trigger/00000000-0000-7000-8000-00000000c001"
}
```

| HTTP | `message` | Causa | Como resolver |
| - | - | - | - |
| `400` | `Request body is invalid, verify!` | Corpo ausente, ilegível ou fora do formato | Envie JSON válido, com `companyId` na visão geral |
| `401` | `Token inválido ou ausente, verifique!` | Sem `Authorization`, token expirado ou inválido. O `timestamp` pode não vir | Gere um novo token. Não use `bvt_` |
| `403` | `Access denied: No policy match` | Perfil sem permissão (como GPS Admin Cliente), `companyId` de outra organização ou token sem usuário | Use um perfil da tabela de acesso e a empresa do usuário |
| `404` | `Resource not found, verify!` | Rota inexistente, como `companyId` omitido no path | Confira o path |
| `415` | Variável | `Content-Type` diferente de `application/json` nos `POST` | Envie `Content-Type: application/json` |
| `500` | Texto simples, como `Company ID is not valid, verify!` | Validação do controller (`companyId` que não é UUID, `size` menor que 1) | Corrija o parâmetro. O corpo é **texto simples**, não JSON |
| `500` | Sem mensagem padronizada | Falha interna | Tente de novo e, se persistir, fale com [ops@deumboom.com](mailto:ops@deumboom.com) |

***

## Exemplos completos

Todos os dados abaixo são fictícios.

### Disparo respondido pelo colaborador, e líder que ainda não respondeu

`GET /core/v1/journey-dispatch/{companyId}` (trecho):

```json theme={null}
[
  {
    "journeyTriggerAudienceId": "00000000-0000-7000-8000-000000000a01",
    "employeeId": "00000000-0000-7000-8000-00000000e001",
    "onBehalfOfEmployeeId": null,
    "triggerName": "Onboarding 30 dias · 30 dias",
    "channel": "EMAIL",
    "status": "ANSWERED",
    "score": 720,
    "countedForScore": true,
    "skipReason": null
  },
  {
    "journeyTriggerAudienceId": "00000000-0000-7000-8000-000000000a02",
    "employeeId": "00000000-0000-7000-8000-00000000e002",
    "onBehalfOfEmployeeId": "00000000-0000-7000-8000-00000000e001",
    "triggerName": "Onboarding 30 dias · 30 dias",
    "channel": "EMAIL",
    "status": "SENT",
    "score": null,
    "countedForScore": null,
    "skipReason": null
  }
]
```

A segunda linha é "líder não respondeu". Se ela não existisse, o líder simplesmente não precisaria responder.

Os exemplos completos de cada endpoint estão na [especificação OpenAPI](https://suporte.deumboom.com/api/jornada.openapi.yaml).

### cURL

```bash theme={null}
curl -s "https://apihomolog.deumboom.com/core/v1/journey-dispatch/${COMPANY_ID}" \
  -H "Authorization: Bearer ${BOOM_TOKEN}"
```

### Python

```python theme={null}
import os
import requests

base = "https://apihomolog.deumboom.com"
resp = requests.get(
    f"{base}/core/v1/journey-dispatch/{os.environ['COMPANY_ID']}",
    headers={"Authorization": f"Bearer {os.environ['BOOM_TOKEN']}"},
    timeout=30,
)
resp.raise_for_status()
answered = [d for d in resp.json() if d["status"] == "ANSWERED"]
print(len(answered), "disparos respondidos")
```

### JavaScript

```javascript theme={null}
const base = "https://apihomolog.deumboom.com";
const res = await fetch(`${base}/core/v1/journey-trigger/${process.env.COMPANY_ID}`, {
  headers: { Authorization: `Bearer ${process.env.BOOM_TOKEN}` },
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
const triggers = await res.json();
console.log(triggers.filter((t) => t.active).length, "triggers ativos");
```

***

## Versionamento

A versão está no path (`/core/v1`). Campos novos opcionais podem aparecer sem aviso: **ignore campos desconhecidos**. Remover um campo ou mudar seu tipo só ocorre em uma nova versão de path. O `info.version` da especificação acompanha este contrato.


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