Clientes, Projetos & Tarefas

A camada de faturamento do módulo: clientes (para quem se cobra), projetos (onde se aponta) e tarefas (o nível mais granular de apontamento). A alocação (project_users) define quem pode apontar em qual projeto e permite um valor-hora específico daquela pessoa naquele contrato.

Headers obrigatórios

Todas as requisições devem incluir X-Timesheet-Id e Authorization: Bearer {token}. Listagens são abertas a qualquer profissional autenticado; criar, editar e remover exige gestor (isManager) — demais recebem 403 FORBIDDEN.

---

Clientes (Clients)

Para quem se fatura. Opcional em uso interno, essencial em agência.

Estrutura de Dados

Campo	Tipo	Descrição
name	String	Nome (máx. 150 caracteres; slug único por instância).
document	String	Documento (CNPJ/CPF, máx. 50 caracteres, opcional).
email	String	E-mail (máx. 250 caracteres, opcional).
phone	String	Telefone (máx. 30 caracteres, opcional).
address	Object	Endereço livre (JSONB, opcional).
isActive	Boolean	Cliente ativo.

Endpoints

GET    /v1/timesheet/clients
GET    /v1/timesheet/clients/list
GET    /v1/timesheet/clients/:id
POST   /v1/timesheet/clients
PUT    /v1/timesheet/clients/:id
DELETE /v1/timesheet/clients/:id

A listagem aceita page, perPage, search e isActive. Escrita restrita a gestores.

---

Projetos (Projects)

O projeto apontável: status, tipo de cobrança, valor-hora, orçamento em horas e em dinheiro. O tipo de cobrança afeta diretamente o snapshot financeiro dos apontamentos.

Estrutura de Dados

Campo	Tipo	Descrição
timesheetClientId	Number	Cliente do projeto (opcional).
code	String	Código interno (máx. 50 caracteres, opcional).
name	String	Nome (máx. 150 caracteres; slug único por instância).
description	String	Descrição livre (opcional).
color	String	Cor em hexadecimal (#RRGGBB, opcional).
status	String	draft, active, paused, completed ou archived.
billingType	String	non_billable, hourly ou fixed_price.
hourlyBillingRate	Number	Valor-hora do projeto (opcional).
fixedPrice	Number	Valor fechado do escopo (opcional).
currency	String	Moeda (3 letras maiúsculas, padrão: BRL).
budgetMinutes	Number	Orçamento em minutos (inteiro, opcional).
budgetAmount	Number	Orçamento em dinheiro (opcional).
startsOn / endsOn	Date	Janela do projeto (YYYY-MM-DD, opcional).

Tipos de cobrança

• hourly: apontamentos geram faturamento pelo valor-hora resolvido (alocação → projeto → tarifa).
• fixed_price e non_billable: apontamentos não geram faturamento (o custo continua sendo calculado) — o percentual de orçamento consumido é acompanhado nas métricas.

Endpoints

GET    /v1/timesheet/projects
GET    /v1/timesheet/projects/list
GET    /v1/timesheet/projects/:id
POST   /v1/timesheet/projects
PUT    /v1/timesheet/projects/:id
DELETE /v1/timesheet/projects/:id

A listagem aceita page, perPage, search, status e timesheetClientId. Escrita restrita a gestores.

Exemplo de Requisição (criar)

curl -X POST "https://api.us.basis.tavares.in/v1/timesheet/projects" \
  -H "X-Timesheet-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "timesheetClientId": 1,
    "name": "Site Institucional Acme",
    "billingType": "hourly",
    "hourlyBillingRate": 180,
    "currency": "BRL",
    "budgetMinutes": 12000,
    "startsOn": "2026-09-01"
  }'

---

Alocação (Project Users)

Define quem pode apontar em qual projeto e permite um valor-hora específico daquela pessoa naquele projeto — o caso "esse sênior é cobrado mais caro nesse contrato". O par projeto + profissional é único.

Precedência do Valor-Hora

No cálculo do faturamento de um apontamento, a aplicação resolve o valor-hora nesta ordem:

1. hourlyBillingRate da alocação vigente do profissional no projeto (joinedOn/leftOn cobrindo a data).
2. hourlyBillingRate do projeto.
3. hourlyBillingRate da tarifa vigente do profissional.

Estrutura de Dados

Campo	Tipo	Descrição
timesheetProjectId	Number	Projeto.
timesheetUserId	Number	Profissional alocado.
role	String	Papel no projeto (máx. 100 caracteres, opcional).
hourlyBillingRate	Number	Valor-hora específico neste projeto (opcional).
allocationPercent	Number	Percentual de dedicação, 0–100 (opcional).
joinedOn / leftOn	Date	Janela da alocação (leftOn >= joinedOn, opcional).

Endpoints

GET    /v1/timesheet/project-users
GET    /v1/timesheet/project-users/me/projects
POST   /v1/timesheet/project-users
GET    /v1/timesheet/project-users/:id
PUT    /v1/timesheet/project-users/:id
DELETE /v1/timesheet/project-users/:id

• GET /project-users: lista alocações (exige ao menos um filtro: timesheetProjectId ou timesheetUserId), com paginação.
• GET /project-users/me/projects: os projetos nos quais o profissional autenticado está alocado, já no formato [{ "value", "label" }] — ideal para montar o seletor de projeto na tela de apontamento.

Criar Alocação (gestor)

Atributo	Tipo	Obrigatório	Descrição
timesheetProjectId	number	Sim	Projeto existente na instância.
timesheetUserId	number	Sim	Profissional existente na instância (par único por projeto).
role	string	Não	Papel no projeto.
hourlyBillingRate	number	Não	Valor-hora específico (mín. 0).
allocationPercent	number	Não	Dedicação, 0–100.
joinedOn	date	Não	Início da alocação (YYYY-MM-DD).
leftOn	date	Não	Fim da alocação (>= joinedOn).

Respostas

201 Created / 204 No Content

Criação retorna { "id": 1 }; atualização e remoção respondem 204. Par projeto + profissional duplicado falha com 422.

---

Tarefas (Tasks)

Tarefas dentro do projeto, com subtarefas (parentId), estimativa e responsável. É o nível mais granular de apontamento: um apontamento pode referenciar projeto e tarefa.

Estrutura de Dados

Campo	Tipo	Descrição
timesheetProjectId	Number	Projeto ao qual a tarefa pertence.
parentId	Number	Tarefa pai (opcional) — forma subtarefas.
title	String	Título (máx. 250 caracteres).
description	String	Descrição livre (opcional).
status	String	todo, in_progress, blocked, done ou cancelled.
isBillable	Boolean	Tarefa faturável (padrão: true).
estimateMinutes	Number	Estimativa em minutos (inteiro, opcional).
timesheetUserId	Number	Responsável (opcional).
dueOn	DateTime	Prazo (ISO 8601, opcional).
completedAt	DateTime	Conclusão (ISO 8601, opcional).

Endpoints

GET    /v1/timesheet/tasks?timesheetProjectId=1
GET    /v1/timesheet/tasks/list?timesheetProjectId=1
GET    /v1/timesheet/tasks/:id
POST   /v1/timesheet/tasks
PUT    /v1/timesheet/tasks/:id
DELETE /v1/timesheet/tasks/:id

As listagens exigem timesheetProjectId e aceitam status, timesheetUserId e search. Escrita restrita a gestores.