Chamados Internos

Os chamados do Timesheet são o canal do profissional com a gestão — tipicamente "esqueci de bater a saída dia 12". O chamado guarda o vínculo direto com o dia ou o apontamento em questão, o que transforma a correção num fluxo rastreável em vez de um ajuste silencioso.

Headers obrigatórios

Todas as requisições devem incluir X-Timesheet-Id e Authorization: Bearer {token}. O profissional abre e acompanha os próprios chamados; atribuir e mudar status exige gestor.

---

Tickets

Estrutura de Dados

Campo	Tipo	Descrição
code	String	Código sequencial por instância, no formato TS-{ano}-{sequencial} — ex.: TS-2026-0012.
timesheetUserId	Number	Solicitante (o autor da abertura).
assigneeTimesheetUserId	Number	Gestor responsável (opcional).
category	String	punch_correction, absence, payroll, project, access ou other (padrão).
status	String	open, in_progress, waiting_user, resolved ou closed.
priority	String	low, normal (padrão), high ou urgent.
subject	String	Assunto (máx. 250 caracteres).
body	String	Descrição (opcional).
timesheetDayId / timesheetEntryId	Number	Dia ou apontamento relacionado (opcionais).
resolution	String	Texto da resolução (preenchido ao resolver).
firstReplyAt	DateTime	Primeira resposta de um gestor.
resolvedAt / closedAt	DateTime	Marcos do fluxo.

Máquina de Estados

open ──> in_progress ⇄ waiting_user
  │          │
  ├──> resolved ──> closed
  └──> closed

De	Para
open	in_progress, waiting_user, resolved, closed
in_progress	waiting_user
waiting_user	in_progress
resolved	closed
closed	— (final; reabertura só de resolved via reopen)

Transição fora da tabela falha com 422 INVALID_STAGE_MOVE.

Efeitos automáticos nas mensagens: a primeira resposta de um gestor move o chamado open para in_progress e grava firstReplyAt; resposta do solicitante em waiting_user devolve o chamado para in_progress.

Endpoints

GET   /v1/timesheet/tickets
POST  /v1/timesheet/tickets
GET   /v1/timesheet/tickets/:id
PATCH /v1/timesheet/tickets/:id/assign
PATCH /v1/timesheet/tickets/:id/status
PATCH /v1/timesheet/tickets/:id/reopen

Listar Chamados

Aceita page, perPage, timesheetUserId, status, priority e category. Profissionais só enxergam os próprios chamados (o filtro timesheetUserId é ignorado); gestores veem todos. A listagem é resumida — omite body, resolution e firstReplyAt, presentes apenas no detalhe.

Obter Chamado

GET /tickets/:id retorna o chamado completo, incluindo as mensagens (timesheetTicketMessages). Para não-gestores, as mensagens internas (isInternal) são omitidas e chamados de terceiros retornam 404.

Abrir Chamado

Qualquer profissional autenticado; o solicitante é sempre o autor da requisição.

Atributo	Tipo	Obrigatório	Descrição
subject	string	Sim	Assunto (máx. 250 caracteres).
category	string	Não	Categoria (padrão: other).
priority	string	Não	Prioridade (padrão: normal).
body	string	Não	Descrição.
timesheetDayId	number	Não	Dia relacionado.
timesheetEntryId	number	Não	Apontamento relacionado.

Exemplo de Requisição

curl -X POST "https://api.us.basis.tavares.in/v1/timesheet/tickets" \
  -H "X-Timesheet-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "category": "punch_correction",
    "subject": "Esqueci de bater a saída dia 12",
    "body": "Saí às 18:10, mas não registrei a saída.",
    "timesheetDayId": 42
  }'

Respostas

201 Created

Retorna o ID e o código do chamado.

{
  "id": 12,
  "code": "TS-2026-0012"
}

Atribuir (gestor)

PATCH /v1/timesheet/tickets/:id/assign

Atributo	Tipo	Obrigatório	Descrição
assigneeTimesheetUserId	number	Sim	Gestor responsável (null remove a atribuição).

Mudar Status (gestor)

PATCH /v1/timesheet/tickets/:id/status

Atributo	Tipo	Obrigatório	Descrição
status	string	Sim	Status de destino (conforme a máquina de estados).
resolution	string	Não	Texto da resolução (relevante ao mover para resolved).

Mover para resolved grava resolvedAt (e resolution, se informada); mover para closed grava closedAt.

Reabrir

PATCH /tickets/:id/reopen devolve um chamado resolved para open. O solicitante pode reabrir o próprio chamado; gestores, qualquer um. Chamados closed não reabrem (422 INVALID_STAGE_MOVE).

---

Mensagens (Ticket Messages)

A conversa do chamado, com flag de nota interna que o solicitante não vê.

Estrutura de Dados

Campo	Tipo	Descrição
body	String	Texto da mensagem.
isInternal	Boolean	Nota interna da gestão — somente gestores podem criar e ler.
attachments	Array	Anexos livres (JSONB, opcional).
timesheetUserId	Number	Autor da mensagem.

Endpoints

GET  /v1/timesheet/tickets/:ticketId/messages
POST /v1/timesheet/tickets/:ticketId/messages

O acesso segue o chamado: o solicitante e gestores podem ler e responder. Na listagem, mensagens isInternal só aparecem para gestores.

Enviar Mensagem

Atributo	Tipo	Obrigatório	Descrição
body	string	Sim	Texto da mensagem (mín. 1 caractere).
isInternal	boolean	Não	Nota interna (padrão: false) — exige gestor, demais recebem 403 FORBIDDEN.
attachments	array	Não	Anexos livres.

Respostas

201 Created / 200 OK

Envio retorna o ID da mensagem; a listagem é paginada (page/perPage).