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

# Conversas API V2

> Contrato estável de leitura e escrita do sensor Conversas: listagem com recorte, detalhe com comentários e criação em /v2/conversas.

A **Conversas API V2** expõe o sensor [Conversas](/core/sensores/conversas) em um recurso único, pronto para BI, automações e o conector MCP.

É o contrato **estável** de integração: participantes no mesmo payload, filtros de período e área, e o **mesmo recorte de perfil** da GPS API V2 (`GpsV2AccessScopeService`). A V1 (`/core/v1/conversation`) continua sendo o CRUD da interface.

<Info>
  Autenticação: JWT do usuário Core (`Authorization: Bearer eyJ…`) ou token OAuth do conector (`mct_…`). Permissões `conversation:read` (GET) e `conversation:manage` (POST/PUT). O token `bvt_` **não** autentica `/v2/conversas`.
</Info>

```http theme={null}
https://api.deumboom.com/v2/conversas
```

Confira o acesso do usuário autenticado em `GET /v2/gps/whoami?companyId={companyId}`: os campos `conversasAccess` e `conversasAccessMessage` dizem se o perfil pode usar este módulo.

***

## Catálogo

| Método | Path | O que faz |
| - | - | - |
| `GET` | `/v2/conversas` | Lista paginada com tipo, período, participante e área |
| `GET` | `/v2/conversas/{id}` | Detalhe com participantes e comentários |
| `POST` | `/v2/conversas` | Cria (tipo, participantes, título, descrição, datas) |
| `PUT` | `/v2/conversas/{id}` | Edita o registro |
| `POST` | `/v2/conversas/{id}/comments` | Inclui um comentário de texto |

Não há `DELETE` neste catálogo. Exclusão continua na [V1](/api/conversas-v1).

***

## Tipos

| Valor | Na interface |
| - | - |
| `ONE_ON_ONE` | 1:1 |
| `CHECK_IN` | Check-in |
| `FEEDBACK` | Feedback |
| `REVERSAL_PLAN` | Plano de reversão |
| `CULTURE_REVIEW` | Review de cultura |

`CULTURE_REVIEW` usa **o mesmo recorte** dos outros quatro tipos (não é um bypass para o RH). As perguntas de cada tipo são pré-setadas no produto; a API grava o registro, não o questionário.

***

## Listar

```http theme={null}
GET /v2/conversas?companyId={companyId}&from=2026-09-01&to=2026-09-30&type=ONE_ON_ONE
```

<ParamField query="companyId" type="uuid" required>
  Empresa do token / do usuário. Pedido com outra organização é recusado.
</ParamField>

<ParamField query="from" type="date">
  Início do recorte da **data da conversa** (`YYYY-MM-DD`).
</ParamField>

<ParamField query="to" type="date">
  Fim do recorte da **data da conversa** (`YYYY-MM-DD`).
</ParamField>

<ParamField query="type" type="enum">
  `ONE_ON_ONE` · `CHECK_IN` · `FEEDBACK` · `REVERSAL_PLAN` · `CULTURE_REVIEW`
</ParamField>

<ParamField query="participantEmployeeId" type="uuid">
  Filtra conversas em que este colaborador é participante.
</ParamField>

<ParamField query="page" type="int">
  Página 0-based. Padrão: `0`.
</ParamField>

<ParamField query="size" type="int">
  Tamanho da página. Padrão: `20`.
</ParamField>

Filtros de **área** (opcionais; UUID do cluster). Mesmos nomes da [GPS API V2](/api/gps-v2):

| Query | Recorte |
| - | - |
| `allocations` | Alocações |
| `directorates` | Diretorias |
| `departments` | Departamentos |
| `businessUnits` | Unidades de negócio |
| `whiteLabelA` … `whiteLabelE` | White Labels |

```bash theme={null}
curl -s "https://api.deumboom.com/v2/conversas" \
  -H "Authorization: Bearer ${JWT}" \
  --get \
  --data-urlencode "companyId=${COMPANY_ID}" \
  --data-urlencode "from=2026-09-01" \
  --data-urlencode "to=2026-09-30" \
  --data-urlencode "type=ONE_ON_ONE" \
  --data-urlencode "departments=${DEPT_ID}" \
  --data-urlencode "page=0" \
  --data-urlencode "size=20"
```

Envelope da página:

```json theme={null}
{
  "page": 0,
  "size": 20,
  "totalElements": 1,
  "totalPages": 1,
  "data": [
    {
      "conversationId": "019e9cbd-19ba-79f1-b9de-17c5658f3600",
      "companyId": "019e0253-377f-7b31-8500-c7c061778fa9",
      "type": "ONE_ON_ONE",
      "title": "1:1 de setembro — Mariana Costa",
      "status": "NO_ACTION",
      "createdById": "019e0253-1111-7b31-8500-c7c061778fa9",
      "createdByName": "ana.lider",
      "description": "Acompanhamento de metas e acordos da quinzena.",
      "conversationDate": "2026-09-18T14:00:00",
      "reviewDate": "2026-10-18T14:00:00",
      "conversationParticipants": [
        {
          "conversationParticipantId": "019e9d01-0000-7000-8000-000000000001",
          "conversationId": "019e9cbd-19ba-79f1-b9de-17c5658f3600",
          "conversationName": "1:1 de setembro — Mariana Costa",
          "employeeId": "019e9c85-e6b7-7638-b475-7b5fb36f1785",
          "employeeName": "Mariana Costa",
          "createdAt": "2026-09-18T14:33:00"
        }
      ],
      "createdAt": "2026-09-18T14:32:01"
    }
  ]
}
```

GPS Admin Cliente **não** recebe lista vazia: a API responde `403` com `"Acesso negado: o perfil GPS Admin Cliente não tem acesso ao módulo Conversas."`. Perfil sem policy de Conversas: `"Acesso negado: seu perfil não tem permissão para o módulo Conversas."`.

***

## Detalhe

```http theme={null}
GET /v2/conversas/{id}?companyId={companyId}
```

Devolve o registro completo (participantes) **e** os comentários.

```json theme={null}
{
  "conversation": {
    "conversationId": "019e9cbd-19ba-79f1-b9de-17c5658f3600",
    "type": "ONE_ON_ONE",
    "title": "1:1 de setembro — Mariana Costa",
    "description": "Acompanhamento de metas e acordos da quinzena.",
    "conversationDate": "2026-09-18T14:00:00",
    "reviewDate": "2026-10-18T14:00:00",
    "conversationParticipants": [ { "employeeId": "…", "employeeName": "Mariana Costa" } ]
  },
  "comments": [
    {
      "conversationCommentId": "019e9d10-0000-7000-8000-000000000002",
      "userName": "ana.lider",
      "comment": "Follow-up da quinzena.",
      "createdAt": "2026-09-18T15:00:00",
      "attachments": []
    }
  ]
}
```

Fora do recorte → `403` `"Access denied: conversation outside of your scope"`.

***

## Criar

Participantes entram no mesmo body. Status é gravado como `NO_ACTION` (não precisa enviar).

```bash theme={null}
curl -s -X POST "https://api.deumboom.com/v2/conversas" \
  -H "Authorization: Bearer ${JWT}" \
  -H "Content-Type: application/json" \
  -d '{
    "companyId": "019e0253-377f-7b31-8500-c7c061778fa9",
    "type": "ONE_ON_ONE",
    "title": "1:1 de setembro — Mariana Costa",
    "description": "Acompanhamento de metas e acordos da quinzena.",
    "conversationDate": "2026-09-18T14:00:00",
    "reviewDate": "2026-10-18T14:00:00",
    "participantEmployeeIds": [
      "019e9c85-e6b7-7638-b475-7b5fb36f1785"
    ]
  }'
```

| Campo | Tipo | Obrigatório |
| - | - | - |
| `companyId` | uuid | sim |
| `type` | enum | sim |
| `title` | string | sim (máx. 255) |
| `description` | string | sim |
| `conversationDate` | datetime | sim |
| `reviewDate` | datetime | não |
| `participantEmployeeIds` | uuid\[] | sim (um ou mais) |

Cada `employeeId` precisa estar **dentro do recorte** do usuário. Participante fora da árvore de “reporta a” (RH BP / Liderança) → `403` `"Acesso negado: há participante fora do escopo de dados do seu perfil."`.

***

## Editar

```http theme={null}
PUT /v2/conversas/{id}
Content-Type: application/json
```

Mesmos campos do create. Quem pode editar:

| Perfil | Pode editar |
| - | - |
| Admin Cliente, RH Estratégico | qualquer conversa da empresa |
| Criador do registro | a própria conversa |
| Gestor acima do criador na hierarquia | a conversa do liderado |
| Demais | `403` `"Acesso negado: apenas o criador da conversa e os gestores acima dele podem editar."` |

Reenviar `participantEmployeeIds` substitui o conjunto de participantes (sempre validado contra o escopo).

***

## Comentar

```http theme={null}
POST /v2/conversas/{id}/comments
Content-Type: application/json

{ "comment": "Follow-up da quinzena." }
```

Somente texto nesta versão. Anexos continuam na [V1](/api/conversas-v1) (`multipart/form-data`).

***

## Permissões e isolamento

| Perfil | Leitura / escrita | Recorte |
| - | - | - |
| Admin Cliente, RH Estratégico | sim | toda a organização |
| RH Business Partner, Liderança | sim | árvore de “reporta a” do Colaborador vinculado |
| GPS Admin Cliente | **não** | `403` explícito — nunca lista vazia |
| Sem Colaborador vinculado (BP / Liderança) | **não** | mesma mensagem de configuração incompleta do GPS V2 |

O colaborador que aparece como participante **não** acessa a API nem o registro. Isolamento é por **usuário autenticado**, não por token de empresa (`bvt_`).

No conector MCP as tools `core_conversas_list`, `core_conversas_get`, `core_conversas_create`, `core_conversas_update` e `core_conversas_comment` chamam exatamente estes endpoints e **não** reimplementam a regra de escopo.

***

## Perguntas frequentes

<AccordionGroup>
  <Accordion title="Por que não usar o token bvt_ como no GPS V2?">
    O GPS V2 é só leitura da fotografia de um ciclo, amarrado à empresa. Conversas é escrita de gestão e recorte por perfil: precisa da identidade do usuário (JWT ou OAuth `mct_`).
  </Accordion>

  <Accordion title="Review de cultura tem recorte diferente?">
    Não. `CULTURE_REVIEW` passa pelo mesmo `GpsV2AccessScopeService` dos outros tipos.
  </Accordion>

  <Accordion title="O GPS Admin vê lista vazia?">
    Não. O módulo é bloqueado com 403 e mensagem explícita, para não parecer “empresa sem conversas”.
  </Accordion>

  <Accordion title="Onde está o cadastro visual?">
    [Conversas no Core](/core/sensores/conversas). CRUD legado da UI: [Conversas API V1](/api/conversas-v1).
  </Accordion>
</AccordionGroup>


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