Conversas API V1

A Conversas API V1 é o contrato HTTP usado pela plataforma Core para criar, listar, editar e excluir registros de conversas de gestão. Replica o módulo Conversas. É a API da interface: payloads do cadastro, filtro paginado, participantes em recurso separado e comentários com anexo.

Autenticação: JWT de usuário (Authorization: Bearer eyJ…) com conversation:read / conversation:manage. O token bvt_ não acessa estas rotas. Para integrações e o conector MCP, use a Conversas API V2.

https://api.deumboom.com/core/v1/conversation

Recursos

Conversa

Base: /core/v1/conversation

Método	Path	Permissão	Status
`POST`	`/core/v1/conversation`	`conversation:manage`	201
`GET`	`/core/v1/conversation/read-all`	`conversation:read`	200
`GET`	`/core/v1/conversation/read-all/company/{company-id}`	`conversation:read`	200
`GET`	`/core/v1/conversation/{conversation-id}`	`conversation:read`	200
`POST`	`/core/v1/conversation/read-filter`	`conversation:read`	200
`PUT`	`/core/v1/conversation`	`conversation:manage`	200
`DELETE`	`/core/v1/conversation/{conversation-id}`	`conversation:manage`	204

DELETE é soft delete (deletedAt). A listagem ignora registros excluídos.

Participantes

Base: /core/v1/conversation-participant

Método	Path	Permissão	Status
`POST`	`/core/v1/conversation-participant`	`conversation_participant:manage`	201
`POST`	`/core/v1/conversation-participant/bulk`	`conversation_participant:manage`	201
`GET`	`/core/v1/conversation-participant/{conversation-participant-id}`	`conversation_participant:read`	200
`DELETE`	`/core/v1/conversation-participant/{conversation-participant-id}`	`conversation_participant:manage`	204

Na V1 a conversa não grava participantes no POST do registro. Crie a conversa e em seguida vincule as pessoas.

Comentários

Base: /core/v1/conversation-comment Create e update usam multipart/form-data (JSON no part data + arquivos opcionais).

Método	Path	Permissão	Status
`POST`	`/core/v1/conversation-comment`	`conversation:manage`	201
`GET`	`/core/v1/conversation-comment/read-all/conversation/{conversation-id}`	`conversation:read`	200
`GET`	`/core/v1/conversation-comment/{conversation-comment-id}`	`conversation:read`	200
`PUT`	`/core/v1/conversation-comment`	`conversation:manage`	200
`DELETE`	`/core/v1/conversation-comment/{conversation-comment-id}`	`conversation:manage`	204

Tipos e status

`type`

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

`status`

Único valor aceito hoje: NO_ACTION. Obrigatório no create e no update.

Campos da conversa

Campo	Tipo	Obrigatório	Notas
`conversationId`	uuid	no PUT	Gerado na criação
`companyId`	uuid	sim	Empresa
`type`	enum	sim	ver tabela acima
`title`	string	sim	Máximo 255 caracteres
`status`	enum	sim	`NO_ACTION`
`description`	string	sim	Pode ser string vazia; `null` é recusado
`conversationDate`	datetime	sim	ISO-8601 (`2026-09-18T14:00:00`)
`reviewDate`	datetime	não	Se enviada, não pode ser anterior a `conversationDate`
`createdById` / `createdByName`	uuid / string	leitura	Preenchidos pelo token na criação
`conversationParticipants`	array	leitura	Presente no GET; não substitui o recurso de participantes
`createdAt`	datetime	leitura

Criar uma conversa

O POST exige identificar o usuário criador (claim do JWT). Sem isso: "User identification is required, verify!".

curl -s -X POST "https://api.deumboom.com/core/v1/conversation" \
  -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",
    "status": "NO_ACTION",
    "description": "Acompanhamento de metas e acordos da quinzena.",
    "conversationDate": "2026-09-18T14:00:00",
    "reviewDate": "2026-10-18T14:00:00"
  }'

{
  "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": [],
  "createdAt": "2026-09-18T14:32:01.123456"
}

Validações frequentes:

Mensagem	Causa
`Conversation type is required, verify!`	Faltou `type`
`Invalid conversation type, verify!`	Valor fora do enum
`Conversation status is required, verify!`	Faltou `status`
`Invalid Conversation Status, verify!`	Valor diferente de `NO_ACTION`
`Conversation title is required, verify!`	Faltou `title`
`Conversation title exceeds maximum length of 255 characters, verify!`	Título longo demais
`Conversation description is required, verify!`	`description` nulo
`Conversation date is required, verify!`	Faltou `conversationDate`
`Review date cannot be before conversation date, verify!`	`reviewDate` anterior à data da conversa
`User not found, verify!`	Usuário do token inexistente
`Company not found, verify!`	`companyId` inválido

Em seguida vincule os participantes:

POST /core/v1/conversation-participant/bulk
Content-Type: application/json

[
  {
    "conversationId": "019e9cbd-19ba-79f1-b9de-17c5658f3600",
    "employeeId": "019e9c85-e6b7-7638-b475-7b5fb36f1785"
  }
]

Lista vazia → "Conversation Participant list is empty. Verify input."
Conversa ou colaborador inexistente → "Conversation not found, verify!" / "Employee not found, verify!". Resposta de um participante:

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

Consultar

Por ID

GET /core/v1/conversation/{conversation-id}

Liderança / RH BP fora do recorte → 403 "Access denied: conversation outside of your scope".
Empresa diferente da do usuário → 403 "Access denied: conversation belongs to a different company".
ID inválido → "Conversation ID is invalid, verify!".
Inexistente → "Conversation not found, verify!".

Por empresa

GET /core/v1/conversation/read-all/company/{company-id}

Admin Cliente e RH Estratégico recebem todas as conversas da empresa. Liderança e RH BP recebem só as da árvore de clusters acessível (Unidade, Diretoria, Departamento, Alocação e White Labels). Sem cluster acessível, a lista vem vazia. GET /core/v1/conversation/read-all lista registros ativos sem filtro de empresa — uso interno, não use em integração de cliente.

Filtro paginado

POST /core/v1/conversation/read-filter
Content-Type: application/json

{
  "companyId": "019e0253-377f-7b31-8500-c7c061778fa9",
  "title": "1:1",
  "typeList": ["ONE_ON_ONE", "FEEDBACK"],
  "createdByUserIds": ["019e0253-1111-7b31-8500-c7c061778fa9"],
  "participantEmployeeIds": ["019e9c85-e6b7-7638-b475-7b5fb36f1785"],
  "conversationDateStart": "2026-09-01T00:00:00",
  "conversationDateEnd": "2026-09-30T23:59:59",
  "reviewDateStart": null,
  "reviewDateEnd": null,
  "page": 0,
  "size": 50
}

Campo	Tipo
`title`	string (contém, case-insensitive no SQL)
`companyId`	uuid
`typeList`	string[]
`createdByUserIds`	uuid[]
`participantEmployeeIds`	uuid[]
`conversationDateStart` / `conversationDateEnd`	datetime
`reviewDateStart` / `reviewDateEnd`	datetime
`page`	int (0-based)
`size`	int (≥ 1)

size < 1 → "Size is less than 1, verify!".
page < 0 → "Page is less than 0, verify!".
Tipo inválido no filtro → "Conversation type is invalid, verify!". Envelope:

{
  "page": 0,
  "size": 1,
  "totalElements": 1,
  "totalPages": 1,
  "data": [ { } ]
}

O mesmo recorte de liderança do read-all/company vale neste filtro.

Atualizar e excluir

O PUT exige conversationId e os mesmos campos obrigatórios da criação. createdBy e createdAt são preservados.

PUT /core/v1/conversation
Content-Type: application/json

{
  "conversationId": "019e9cbd-19ba-79f1-b9de-17c5658f3600",
  "companyId": "019e0253-377f-7b31-8500-c7c061778fa9",
  "type": "ONE_ON_ONE",
  "title": "1:1 de setembro — Mariana Costa (revisado)",
  "status": "NO_ACTION",
  "description": "Acordos atualizados após a revisão.",
  "conversationDate": "2026-09-18T14:00:00",
  "reviewDate": "2026-10-25T14:00:00"
}

DELETE /core/v1/conversation/{conversation-id}
DELETE /core/v1/conversation-participant/{conversation-participant-id}

Comentários e anexos

Create e update: Content-Type: multipart/form-data.

Part	Conteúdo
`data`	JSON do comentário
`file`, `file_0`, `file_1`, …	Anexos

O comentário precisa de texto ou pelo menos um anexo. Sem os dois: "Comment must contain text or at least one attachment!". Formatos aceitos: jpg, jpeg, png, webp, pdf, docx, xlsx, pptx, csv, txt, md. Tamanho máximo: 25 MB por arquivo.

curl -s -X POST "https://api.deumboom.com/core/v1/conversation-comment" \
  -H "Authorization: Bearer ${JWT}" \
  -F 'data={"conversationId":"019e9cbd-19ba-79f1-b9de-17c5658f3600","comment":"Follow-up da quinzena."};type=application/json' \
  -F "file=@anexo.pdf"

Resposta (campos principais):

{
  "conversationCommentId": "019e9d10-0000-7000-8000-000000000002",
  "conversationId": "019e9cbd-19ba-79f1-b9de-17c5658f3600",
  "userId": "019e0253-1111-7b31-8500-c7c061778fa9",
  "userName": "ana.lider",
  "comment": "Follow-up da quinzena.",
  "createdAt": "2026-09-18T15:00:00",
  "updatedAt": "2026-09-18T15:00:00",
  "attachments": [
    {
      "conversationCommentAttachmentId": "…",
      "fileName": "stored-name.pdf",
      "originalName": "anexo.pdf",
      "fileUrl": "https://…",
      "contentType": "application/pdf",
      "size": 120411
    }
  ]
}

No PUT, envie conversationCommentId, conversationId e, se for o caso, removeAttachmentIds (uuids dos anexos a remover). Só o autor edita o próprio comentário (403 "Access denied: you can only edit your own comments"). Exclusão: autor, ou Admin Cliente / RH Estratégico da empresa.

Permissões e isolamento

Perfil	Cria / edita	Visualiza
Admin Cliente, RH Estratégico	sim (empresa)	todas as conversas da empresa
RH Business Partner, Liderança	sim, no recorte de clusters	só a árvore de atuação
GPS Admin Cliente	não	não (`conversation:*` ausente da policy)
Colaborador (participante)	não	não — o registro é ferramenta de gestão

O colaborador em employeeId não recebe convite e não acessa o registro. Detalhe do produto: Conversas no Core.

Perguntas frequentes

Qual a diferença entre a V1 e a V2?

A V1 é o CRUD da plataforma (três recursos, multipart nos comentários). A V2 é o contrato estável para integração e MCP: um recurso /v2/conversas, participantes no mesmo POST e recorte explícito de perfil.

Posso criar conversa e participantes no mesmo POST?

Não nesta versão. Use POST /core/v1/conversation e depois POST /core/v1/conversation-participant (ou /bulk). Na V2 os participantes entram no body da criação.

O token bvt_ funciona aqui?

Não. Estas rotas exigem JWT de um usuário com conversation:read / conversation:manage.

Visão geral

GPS

Sensores

Cadastros

Recursos

Conversa

Participantes

Comentários

Tipos e status

`type`

`status`

Campos da conversa

Criar uma conversa

Consultar

Por ID

Por empresa

Filtro paginado

Atualizar e excluir

Comentários e anexos

Permissões e isolamento

Perguntas frequentes

​Recursos

​Conversa

​Participantes

​Comentários

​Tipos e status

​type

​status

​Campos da conversa

​Criar uma conversa

​Consultar

​Por ID

​Por empresa

​Filtro paginado

​Atualizar e excluir

​Comentários e anexos

​Permissões e isolamento

​Perguntas frequentes

Recursos

Conversa

Participantes

Comentários

Tipos e status

`type`

`status`

Campos da conversa

Criar uma conversa

Consultar

Por ID

Por empresa

Filtro paginado

Atualizar e excluir

Comentários e anexos

Permissões e isolamento

Perguntas frequentes