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

# Conector BOOM: Signals

> Tools do conector BOOM para listar, consultar, criar e editar Signals, com perguntas, grupos, lógica condicional (goTo) e os 10 tipos de pergunta.

O conector BOOM expõe o Sensor **Signals** por quatro tools. Elas seguem as mesmas regras da tela em **Sensores > Signals**: o que a tela recusa, o conector também recusa.

> [!NOTE]
>
> O conector aceita JWT (`eyJ…`) e token OAuth (`mct_…`). Com OAuth, o `companyId` é opcional. Um `companyId` de outra empresa retorna `401`.

Cancelar e excluir Signals **não estão disponíveis** no conector. Seguem pelo suporte.

***

## Tools

| Tool | Método e caminho | O que faz |
| - | - | - |
| `core_signals_list` | `GET /v2/signals` | Lista os Signals, com status, ciclo, datas, campos editáveis e conversão |
| `core_signals_get` | `GET /v2/signals/{signalId}` | Detalhe completo: perguntas, conversão por cluster, relatório e análises da IA |
| `core_signals_create` | `POST /v2/signals` | Cria um Signal (Rascunho por padrão ou já Programado) |
| `core_signals_update` | `PUT /v2/signals/{signalId}` | Edita um Signal conforme o status |

### `core_signals_list`

| Parâmetro | Descrição |
| - | - |
| `companyId` | UUID da empresa (opcional com OAuth) |
| `status` | `RASCUNHO`, `PROGRAMADO`, `ENVIADO` ou `ENCERRADO` |
| `cycleId` | Filtra por ciclo (UUID) |
| `page` | Página, começando em `0` |
| `size` | Itens por página (padrão `20`, máximo `100`) |

A resposta traz `statusCounts` com o total por status. Esse total **ignora** o filtro de `status`.

### `core_signals_get`

| Parâmetro | Descrição |
| - | - |
| `signalId` | UUID do Signal (obrigatório) |
| `companyId` | UUID da empresa (opcional com OAuth) |
| `includeReport` | Inclui o Relatório e Análises da IA (padrão `true`) |

O relatório só aparece **depois do encerramento**, com no mínimo **5 respostas**, e só com as análises já **publicadas**. Rascunhos de análise nunca são retornados. Quando não há relatório, `report.available` vem `false` e `report.reason` explica o motivo. Respostas individuais e dados pessoais da audiência nunca são expostos.

`editableFields` indica o que pode ser alterado no status atual.

***

## O que cada perfil faz

| Perfil | Listar e consultar | Criar e editar |
| - | - | - |
| Admin Cliente | Todos os Signals | Sim |
| RH Estratégico | Todos os Signals | Sim |
| RH Business Partner | Somente os que criou | Sim, só com colaboradores e clusters da própria área |
| GPS Admin Cliente | Erro de permissão | Não |
| Liderança | Erro de permissão | Não |

***

## Criar e editar

`core_signals_create` e `core_signals_update` seguem as quatro etapas da tela.

| Etapa | Campos |
| - | - |
| Pesquisa | `name` (até 100 caracteres), `description`, `cycleId` |
| Perguntas | `questions`, `questionGroups`, `welcomeScreen`, `thankYouScreen` |
| Disparo | `sendDate`, `endDate` |
| Audiência | `employeeIds`, `clusters`, `audienceMode` |

Na criação, `name` e `cycleId` são obrigatórios. O parâmetro `draft` controla o resultado:

* `draft=true` (padrão): salva como **Rascunho**, em qualquer etapa, sem exigir os demais campos e sem disparar envio.
* `draft=false`: finaliza e o Signal vira **Programado**. O time BOOM é notificado, como na tela.

Para finalizar, o servidor exige:

* ao menos **1 pergunta**;
* ao menos **1 colaborador** na audiência;
* `sendDate` com **24 horas úteis** de antecedência (sábado e domingo não contam, feriados não são considerados, horário de Brasília);
* `endDate` depois do envio.

### Datas

Use ISO 8601. Sem fuso (`2026-11-10T09:00:00`) vale o horário de Brasília. Com fuso (`Z` ou `+hh:mm`), o servidor converte para Brasília.

### O que cada status permite editar

| Status | Edição |
| - | - |
| `RASCUNHO` | Tudo: perguntas, grupos, telas, datas e audiência. Passe `draft=false` para finalizar |
| `PROGRAMADO` | `name`, `description`, `cycleId`, `endDate` e audiência. `sendDate` só com mais de 24 horas úteis até o envio |
| `ENVIADO` | Os mesmos de Programado, sem `sendDate`. Não pode mudar para um ciclo encerrado |
| `ENCERRADO` | Não edita |

Enviar `questions` ou telas fora do Rascunho é recusado. Não é possível voltar para Rascunho. Programado e Enviado não podem ficar com audiência vazia. Em `core_signals_update`, campos omitidos são preservados.

### Audiência

Envie `employeeIds` (UUIDs de colaboradores) e/ou `clusters` (`clusterType` e `clusterId`). Os clusters são expandidos para os colaboradores **Ativos** e **Afastados** do cluster. Desligados não entram.

| `audienceMode` | Efeito |
| - | - |
| `REPLACE` (padrão) | Substitui a audiência atual |
| `ADD` | Acrescenta aos membros atuais |

Se `employeeIds` e `clusters` forem omitidos, a audiência não muda.

Tipos de cluster: `BUSINESS_UNIT`, `DIRECTORATE`, `DEPARTMENT`, `ALLOCATION` e `WHITE_LABEL_A` a `WHITE_LABEL_E`.

***

## Perguntas

Cada item de `questions` aceita estes campos.

| Campo | Descrição |
| - | - |
| `text` | Texto da pergunta (obrigatório) |
| `description` | Texto de apoio |
| `questionType` | Um dos 10 tipos (obrigatório). Veja a tabela abaixo |
| `required` | Resposta obrigatória |
| `questionOrder` | Posição (1, 2, …). Sem ela, vale a ordem da lista. Não pode repetir |
| `questionKey` | Chave estável, usada pela lógica condicional. Omitida em pergunta nova, é gerada |
| `surveyQuestionId` | UUID de uma pergunta existente. Ao editar um Rascunho, mantém a identidade da pergunta |
| `questionGroupKey` | `key` de um grupo de `questionGroups` ao qual a pergunta pertence |
| `showOnlyByCondition` | A pergunta só aparece quando alguma opção a aponta via `goTo` |
| `questionOptions` | Opções (escolhas) ou colunas (matrizes) |
| `questionOptionsOrder` | `FIXED` (padrão) ou `RANDOM` |

### Os 10 tipos de pergunta

| `questionType` | Tela | Campos específicos |
| - | - | - |
| `TEXT_SHORT` | Texto curto | |
| `TEXT_LONG` | Texto longo | |
| `SINGLE_CHOICE` | Escolha única | `questionOptions` (mínimo 2), `goTo` por opção |
| `MULTIPLE_CHOICE` | Múltipla escolha | `questionOptions` (mínimo 2), `goTo` por opção, `minSelectableOptions`, `maxSelectableOptions` |
| `NUMERIC_RATING` | Avaliação numérica | `ratingMin` (obrigatório), `ratingMax`, `ratingLabelMin`, `ratingLabelMax` |
| `SLIDER` | Controle deslizante | `ratingMin` (padrão 0), `ratingMax` (padrão 10), `sliderStep`, `sliderStartPosition`, `sliderShowValue` |
| `ENPS` | eNPS | Faixa de 0 a 10 e rótulos fixos |
| `NUMBER` | Número | |
| `MATRIX_SINGLE` | Matriz única | `matrixRows`, `questionOptions` como colunas. Uma coluna por linha |
| `MATRIX_MULTIPLE` | Matriz múltipla | `matrixRows`, `questionOptions` como colunas. Várias colunas por linha, com `minSelectableOptions` e `maxSelectableOptions` por linha |

#### Avaliação numérica e slider

* `ratingMax` precisa ser **maior** que `ratingMin`.
* `sliderStep` (padrão `1`) precisa dividir `ratingMax - ratingMin`.
* `sliderStartPosition` é `MIDDLE` (padrão) ou `START`. `sliderShowValue` é `true` por padrão.

#### Escolhas

* `SINGLE_CHOICE` e `MULTIPLE_CHOICE` exigem **no mínimo 2 opções**.
* Cada opção tem `text` e, opcionalmente, `id` (gerado se omitido) e `goTo`.

#### Matrizes

| Item | Limite |
| - | - |
| Linhas (`matrixRows`) | 2 a 20, cada uma com `text` e `id` opcional |
| Colunas (`questionOptions`) | 2 a 10, com `id` gerado se omitido |
| `matrixRowsOrder` | `FIXED` (padrão) ou `RANDOM` |

#### Mínimo e máximo de respostas

`minSelectableOptions` e `maxSelectableOptions` valem só em `MULTIPLE_CHOICE` e, **por linha**, em `MATRIX_MULTIPLE`. Os outros tipos recusam os campos.

| Regra | Valor |
| - | - |
| Mínimo | `0` ou mais. Não passa do total de opções (ou colunas) nem do máximo |
| Máximo | `1` ou mais. Não passa do total de opções (ou colunas) |
| Mínimo e máximo juntos | O máximo não pode ser menor que o mínimo |
| Matriz múltipla obrigatória | O mínimo por linha precisa ser pelo menos `1` |

***

## Grupos de perguntas

`questionGroups` agrupa perguntas em blocos. Cada pergunta entra num grupo pelo `questionGroupKey`, que é o `key` do grupo.

| Campo | Descrição |
| - | - |
| `key` | Chave do grupo (obrigatório) |
| `title` | Título do grupo |
| `message` | Texto do grupo |
| `buttonText` | Texto do botão do grupo |
| `questionsOrder` | `FIXED` ou `RANDOM`: ordem das perguntas dentro do grupo |

Em `core_signals_update`, `questionGroups` só é aceito em Rascunho e **substitui** os grupos. Omitido, preserva os atuais.

***

## Lógica condicional (`goTo`)

Em `SINGLE_CHOICE` e `MULTIPLE_CHOICE`, cada opção pode ter um `goTo` que decide para onde o respondente vai ao escolher aquela opção.

| Valor de `goTo` | Destino |
| - | - |
| `questionKey` de uma pergunta | Pula para aquela pergunta |
| `group:<key do grupo>` (ou só a `key` do grupo) | Segue para o grupo inteiro |
| `END` | Encerra a pesquisa |
| Omitido ou `NEXT` | Segue a ordem normal |

Regras:

* A lógica **só avança**. Um `goTo` que aponta para pergunta ou grupo anterior (ou para o próprio grupo da pergunta) é recusado.
* `goTo` em outros tipos de pergunta é recusado.
* Não vale dentro de um grupo com ordem `RANDOM`, nem apontando para uma pergunta dentro dele. Um grupo `RANDOM` inteiro pode ser destino, com `group:<key>`.
* `showOnlyByCondition` exige que alguma opção leve até a pergunta, e a primeira pergunta não pode ser condicional.
* Em edição de Rascunho, inclua `surveyQuestionId` das perguntas mantidas: elas preservam `questionKey`, grupo, condição e `goTo`. Um `goTo` omitido preserva o valor salvo.

### Exemplo

```json theme={null}
{
  "name": "Clima da equipe",
  "cycleId": "00000000-0000-7000-8000-000000000001",
  "draft": true,
  "questionGroups": [
    { "key": "detalhes", "title": "Conte mais", "questionsOrder": "FIXED" }
  ],
  "questions": [
    {
      "questionKey": "satisfeito",
      "text": "Você está satisfeito com o time?",
      "questionType": "SINGLE_CHOICE",
      "required": true,
      "questionOptions": [
        { "text": "Sim", "goTo": "END" },
        { "text": "Não", "goTo": "group:detalhes" }
      ]
    },
    {
      "questionKey": "motivos",
      "questionGroupKey": "detalhes",
      "showOnlyByCondition": true,
      "text": "O que mais pesa?",
      "questionType": "MULTIPLE_CHOICE",
      "minSelectableOptions": 1,
      "maxSelectableOptions": 2,
      "questionOptions": [
        { "text": "Carga de trabalho" },
        { "text": "Comunicação" },
        { "text": "Liderança" }
      ]
    }
  ]
}
```

***

## Telas de boas-vindas e agradecimento

| Objeto | Campos |
| - | - |
| `welcomeScreen` | `title`, `message`, `buttonText`, `confirmationText` |
| `thankYouScreen` | `title`, `message` |

***

## Pergunte ao Claude

* "Quais Signals estão em rascunho?"
* "Crie um rascunho de Signal com uma pergunta de escolha única que encerra a pesquisa se a resposta for Sim."
* "Quantos colaboradores já responderam o Signal de clima?"


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