Conversas API V2

A Conversas API V2 expõe o sensor 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.

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.

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.

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

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

uuid

required

Empresa do token / do usuário. Pedido com outra organização é recusado.

date

Início do recorte da data da conversa (YYYY-MM-DD).

date

Fim do recorte da data da conversa (YYYY-MM-DD).

enum

ONE_ON_ONE · CHECK_IN · FEEDBACK · REVERSAL_PLAN · CULTURE_REVIEW

uuid

Filtra conversas em que este colaborador é participante.

int

Página 0-based. Padrão: 0.

int

Tamanho da página. Padrão: 20.

Filtros de área (opcionais; UUID do cluster). Mesmos nomes da GPS API V2:

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

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:

{
  "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

GET /v2/conversas/{id}?companyId={companyId}

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

{
  "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).

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

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

POST /v2/conversas/{id}/comments
Content-Type: application/json

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

Somente texto nesta versão. Anexos continuam na 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

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_).

Review de cultura tem recorte diferente?

Não. CULTURE_REVIEW passa pelo mesmo GpsV2AccessScopeService dos outros tipos.

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

Onde está o cadastro visual?

Conversas no Core. CRUD legado da UI: Conversas API V1.

Visão geral

GPS

Sensores

Cadastros

Catálogo

Tipos

Listar

Detalhe

Criar

Editar

Comentar

Permissões e isolamento

Perguntas frequentes

​Catálogo

​Tipos

​Listar

​Detalhe

​Criar

​Editar

​Comentar

​Permissões e isolamento

​Perguntas frequentes

Catálogo

Tipos

Listar

Detalhe

Criar

Editar

Comentar

Permissões e isolamento

Perguntas frequentes