Métricas

As métricas são consultas analíticas calculadas sob demanda pela aplicação a partir dos dias consolidados e dos apontamentos — não há views no banco. Todas retornam arrays de linhas (sem paginação) e respeitam o papel do autenticado.

Headers obrigatórios

Todas as requisições devem incluir X-Timesheet-Id e Authorization: Bearer {token}.

---

Escopo por Papel

Endpoint	Profissional	Gestor
GET /metrics/daily-sheet	Apenas os próprios dias	Qualquer profissional via timesheetUserId
GET /metrics/monthly-totals	Apenas o próprio mês	Qualquer profissional via timesheetUserId
GET /metrics/project-billing	Não acessa (403 FORBIDDEN)	Todos os projetos

---

Espelho de Ponto (Daily Sheet)

Uma linha por dia, já com nome do profissional, status do fluxo e primeira entrada/última saída — o espelho de ponto pronto para exibição.

GET /v1/timesheet/metrics/daily-sheet

Parâmetros de Query

Nome	Tipo	Obrigatório	Descrição
timesheetUserId	number	Não (gestor)	Filtra por profissional. Ignorado para não-gestores.
startsOn	date	Não	Início do intervalo (YYYY-MM-DD).
endsOn	date	Não	Fim do intervalo (>= startsOn).

Respostas

200 OK

[
  {
    "dayId": 6,
    "timesheetUserId": 5,
    "userName": "Gerson Tavares",
    "workDate": "2026-09-23",
    "status": "rejected",
    "expectedMinutes": 0,
    "workedMinutes": 540,
    "breakMinutes": 0,
    "balanceMinutes": 540,
    "overtimeMinutes": 540,
    "deficitMinutes": 0,
    "firstInAt": "2026-09-23T12:00:00.000Z",
    "lastOutAt": "2026-09-23T21:00:00.000Z"
  }
]

Fuso dos instantes

firstInAt e lastOutAt são retornados em UTC (sufixo Z), independentemente do fuso do dia.

---

Totais Mensais (Monthly Totals)

O "total mensal dinâmico": horas, saldo, extras, custo e faturamento por profissional por mês.

GET /v1/timesheet/metrics/monthly-totals

Parâmetros de Query

Nome	Tipo	Obrigatório	Descrição
month	string	Sim	Mês de referência no formato YYYY-MM.
timesheetUserId	number	Não (gestor)	Filtra por profissional. Ignorado para não-gestores.

Respostas

200 OK

[
  {
    "timesheetUserId": 5,
    "userName": "Gerson Tavares",
    "workedDays": 2,
    "expectedMinutes": 0,
    "workedMinutes": 690,
    "breakMinutes": 0,
    "overtimeMinutes": 690,
    "deficitMinutes": 0,
    "workedHours": 11.5,
    "totalCost": 0,
    "totalBillable": 1840
  }
]

---

Faturamento por Projeto (Project Billing)

Base de fatura: horas e valores por projeto, incluindo o que ainda não foi faturado e o percentual de orçamento consumido. Somente gestores.

GET /v1/timesheet/metrics/project-billing

Parâmetros de Query

Nome	Tipo	Obrigatório	Descrição
timesheetProjectId	number	Não	Filtra por projeto.
startsOn	date	Não	Início do intervalo (YYYY-MM-DD).
endsOn	date	Não	Fim do intervalo (>= startsOn).

Respostas

200 OK

[
  {
    "timesheetProjectId": 3,
    "projectName": "Portal Acme",
    "timesheetClientId": 3,
    "totalMinutes": 690,
    "totalHours": 11.5,
    "billableMinutes": 690,
    "totalCost": 0,
    "totalBillable": 1840,
    "pendingInvoice": 1840,
    "budgetMinutes": 8000,
    "budgetConsumedPercent": 8.63
  }
]

Campo	Descrição
billableMinutes	Minutos efetivamente faturáveis (exclui non_billable/fixed_price e isBillable: false).
pendingInvoice	Valor faturável ainda não faturado (apontamentos sem invoicedAt).
budgetConsumedPercent	Percentual do budgetMinutes consumido (null sem orçamento).

403 Forbidden

Profissionais (não-gestores) não têm acesso a este endpoint.

---

Relação com as Exportações

Os mesmos dados podem ser gerados em arquivo CSV assíncrono — ver Exportações.