Jornadas & Ausências

As jornadas definem quanto se espera trabalhar em cada dia; feriados e ausências aprovadas zeram essa expectativa. Juntos, eles alimentam o expectedMinutes de cada dia consolidado e o saldo mensal — sem eles, todo feriado ou dia de férias apareceria como falta no relatório.

Headers obrigatórios

Todas as requisições devem incluir X-Timesheet-Id e Authorization: Bearer {token}. Gerenciar jornadas, dias de jornada, vínculos e feriados exige gestor (isManager); ausências podem ser criadas pelo próprio profissional, mas só gestores aprovam.

Jornadas (Schedules)

Modelos de jornada — "44h comercial", "6x1", "meio período". O detalhe dia a dia fica nos dias da jornada.

Estrutura de Dados

Campo	Tipo	Descrição
`id`	`Number`	Identificador da jornada.
`name`	`String`	Nome (máx. 150 caracteres).
`weeklyMinutes`	`Number`	Total semanal esperado em minutos (informativo).
`isDefault`	`Boolean`	Indica a jornada padrão da instância.

Jornada padrão

Toda instância nasce com a jornada Comercial 44h (segunda a sexta, 09:00–18:00, 480 min/dia, 60 min de intervalo), criada no setup inicial.

Endpoints

http

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

Criar Jornada (gestor)

Atributo	Tipo	Obrigatório	Descrição
`name`	`string`	Sim	Nome (máx. 150 caracteres).
`weeklyMinutes`	`number`	Não	Total semanal em minutos (mín. 0).
`isDefault`	`boolean`	Não	Marca como jornada padrão.

Respostas

201 Created / 204 No Content

Criação retorna { "id": 1 }; atualização e remoção respondem 204. Listagens aceitam page/perPage/search.

Dias da Jornada (Schedule Days)

O detalhe de cada modelo, dia da semana a dia da semana: horário previsto, minutos esperados e intervalo. A escrita é feita em lote (sync), substituindo os dias informados.

Estrutura de Dados

Campo	Tipo	Descrição
`weekday`	`Number`	Dia da semana: `0` = domingo até `6` = sábado.
`startsAt`	`String`	Horário de início (`HH:mm`, `null` em dias sem expediente).
`endsAt`	`String`	Horário de término (`HH:mm`).
`expectedMinutes`	`Number`	Minutos esperados no dia.
`breakMinutes`	`Number`	Minutos de intervalo previstos.

Listar Dias da Jornada

http

GET /v1/timesheet/schedules/:scheduleId/days

Retorna o array de dias ordenado por weekday. Na resposta, startsAt/endsAt vêm no formato do banco (HH:mm:ss, ex.: "08:00:00"); na escrita (sync), envie HH:mm.

Sincronizar Dias (gestor)

Substitui a grade da jornada em uma única chamada. O weekday não pode se repetir no payload — duplicado falha com 422 DUPLICATED_WEEKDAY.

http

PUT /v1/timesheet/schedules/:scheduleId/days

Payload (Body)

Atributo	Tipo	Obrigatório	Descrição
`days`	`array`	Sim	Até 7 itens, um por dia da semana.
`days[].weekday`	`number`	Sim	`0` (domingo) a `6` (sábado).
`days[].startsAt`	`string`	Não	Horário de início `HH:mm` (pode ser `null`).
`days[].endsAt`	`string`	Não	Horário de término `HH:mm` (pode ser `null`).
`days[].expectedMinutes`	`number`	Não	Minutos esperados (mín. 0).
`days[].breakMinutes`	`number`	Não	Minutos de intervalo (mín. 0).

Exemplo de Requisição

bash

curl -X PUT "https://api.us.basis.tavares.in/v1/timesheet/schedules/1/days" \
  -H "X-Timesheet-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "days": [
      { "weekday": 1, "startsAt": "08:00", "endsAt": "17:00", "expectedMinutes": 480, "breakMinutes": 60 },
      { "weekday": 2, "startsAt": "08:00", "endsAt": "17:00", "expectedMinutes": 480, "breakMinutes": 60 }
    ]
  }'

Respostas

204 No Content

Sincronização concluída com sucesso.

Vínculo de Jornada (User Schedules)

Define quem segue qual jornada e desde quando. É um histórico, pelo mesmo motivo das tarifas: mudança de jornada não reescreve o passado. A vigência ativa é usada no cálculo do expectedMinutes de cada dia.

Estrutura de Dados

Campo	Tipo	Descrição
`timesheetUserId`	`Number`	Profissional.
`timesheetScheduleId`	`Number`	Jornada.
`effectiveFrom`	`Date`	Início da vigência (`YYYY-MM-DD`).
`effectiveTo`	`Date`	Fim da vigência (`null` = indefinida).

Regra de Vigências

Vigências do mesmo profissional não podem se sobrepor: a aplicação rejeita com 422 SCHEDULE_OVERLAP qualquer vínculo que colida com um existente (null em effectiveTo conta como 9999-12-31). effectiveTo anterior a effectiveFrom falha com 422 INVALID_EFFECTIVE_RANGE.

Endpoints (somente gestores)

http

GET    /v1/timesheet/user-schedules?timesheetUserId=2
POST   /v1/timesheet/user-schedules
GET    /v1/timesheet/user-schedules/:id
PUT    /v1/timesheet/user-schedules/:id
DELETE /v1/timesheet/user-schedules/:id

Criar Vínculo

Atributo	Tipo	Obrigatório	Descrição
`timesheetUserId`	`number`	Sim	Profissional existente na instância.
`timesheetScheduleId`	`number`	Sim	Jornada existente na instância.
`effectiveFrom`	`date`	Sim	Início da vigência (`YYYY-MM-DD`).
`effectiveTo`	`date`	Não	Fim da vigência (`>= effectiveFrom`).

Respostas

422 Unprocessable Entity

Vigência sobreposta a outro vínculo do mesmo profissional.

json

{
  "message": "Já existe uma vigência que se sobrepõe ao período informado",
  "code": "SCHEDULE_OVERLAP"
}

Feriados (Holidays)

Feriados nacionais, estaduais, municipais ou da empresa. Um feriado com isWorkingDay: false zera os minutos esperados do dia e ativa o multiplicador de feriado no cálculo financeiro.

Estrutura de Dados

Campo	Tipo	Descrição
`date`	`Date`	Data do feriado (`YYYY-MM-DD`).
`name`	`String`	Nome (máx. 150 caracteres).
`scope`	`String`	Abrangência: `national` (padrão), `state`, `city` ou `company`.
`regionCode`	`String`	Código da região (UF/município, máx. 20 caracteres, opcional).
`isWorkingDay`	`Boolean`	`true` = dia útil mesmo sendo feriado (padrão: `false`).

A combinação date + scope + regionCode é única por instância — duplicados falham com 422.

Endpoints

http

GET    /v1/timesheet/holidays?startsOn=2026-01-01&endsOn=2026-12-31
POST   /v1/timesheet/holidays
GET    /v1/timesheet/holidays/:id
PUT    /v1/timesheet/holidays/:id
DELETE /v1/timesheet/holidays/:id

A listagem aceita startsOn/endsOn (YYYY-MM-DD) além de page/perPage. Escrita restrita a gestores.

Ausências (Absences)

Férias, atestados, folgas e licenças. Uma ausência aprovada zera os minutos esperados dos dias cobertos — sem isso, todo dia de férias apareceria como falta no saldo mensal.

Estrutura de Dados

Campo	Tipo	Descrição
`timesheetUserId`	`Number`	Profissional ausente.
`kind`	`String`	Tipo: `vacation`, `sick_leave`, `day_off`, `holiday`, `unpaid` ou `other`.
`status`	`String`	`pending` (padrão na criação), `approved`, `rejected` ou `cancelled`.
`startsOn` / `endsOn`	`Date`	Janela da ausência (`endsOn >= startsOn`).
`isPaid`	`Boolean`	Ausência remunerada (padrão: `true`).
`reason`	`String`	Justificativa (opcional).
`reviewedByTimesheetUserId` / `reviewedAt`	`Number` / `DateTime`	Quem revisou e quando (preenchidos na aprovação/rejeição).

Fluxo de Aprovação

pending ──approve──> approved
   │  └──reject───> rejected
   └──cancel────> cancelled

Todas as transições partem de pending; agir sobre ausência já decidida falha com 422 INVALID_STAGE_MOVE. Somente dias com ausência approved têm a expectativa zerada.

Endpoints

http

GET   /v1/timesheet/absences
POST  /v1/timesheet/absences
GET   /v1/timesheet/absences/:id
PATCH /v1/timesheet/absences/:id/approve
PATCH /v1/timesheet/absences/:id/reject
PATCH /v1/timesheet/absences/:id/cancel

Listar Ausências

Aceita page, perPage, timesheetUserId, status e kind. Profissionais só enxergam as próprias ausências (o filtro timesheetUserId é ignorado); gestores veem todas.

Criar Ausência

O profissional cria a própria ausência; gestores podem criar para qualquer pessoa (422 FORBIDDEN → 403 caso contrário).

Atributo	Tipo	Obrigatório	Descrição
`timesheetUserId`	`number`	Não	Profissional (padrão: o autenticado).
`kind`	`string`	Sim	Tipo da ausência.
`startsOn`	`date`	Sim	Início (`YYYY-MM-DD`).
`endsOn`	`date`	Sim	Fim (`>= startsOn`).
`isPaid`	`boolean`	Não	Remunerada (padrão: `true`).
`reason`	`string`	Não	Justificativa.

Exemplo de Requisição

bash

curl -X POST "https://api.us.basis.tavares.in/v1/timesheet/absences" \
  -H "X-Timesheet-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "vacation",
    "startsOn": "2026-12-21",
    "endsOn": "2027-01-04",
    "reason": "Férias anuais"
  }'

Respostas

201 Created / 204 No Content

Criação retorna { "id": 1 } com status pending. As transições (approve, reject, cancel) respondem 204 e exigem gestor.

Jornadas & Ausências ​

Jornadas (Schedules) ​

Estrutura de Dados ​

Endpoints ​

Criar Jornada (gestor) ​

Respostas ​

Dias da Jornada (Schedule Days) ​

Estrutura de Dados ​

Listar Dias da Jornada ​

Sincronizar Dias (gestor) ​

Payload (Body) ​

Exemplo de Requisição ​

Respostas ​

Vínculo de Jornada (User Schedules) ​

Estrutura de Dados ​

Regra de Vigências ​

Endpoints (somente gestores) ​

Criar Vínculo ​

Respostas ​

Feriados (Holidays) ​

Estrutura de Dados ​

Endpoints ​

Ausências (Absences) ​

Estrutura de Dados ​

Fluxo de Aprovação ​

Endpoints ​

Listar Ausências ​

Criar Ausência ​

Exemplo de Requisição ​

Respostas ​

Jornadas & Ausências

Jornadas (Schedules)

Estrutura de Dados

Endpoints

Criar Jornada (gestor)

Respostas

Dias da Jornada (Schedule Days)

Estrutura de Dados

Listar Dias da Jornada

Sincronizar Dias (gestor)

Payload (Body)

Exemplo de Requisição

Respostas

Vínculo de Jornada (User Schedules)

Estrutura de Dados

Regra de Vigências

Endpoints (somente gestores)

Criar Vínculo

Respostas

Feriados (Holidays)

Estrutura de Dados

Endpoints

Ausências (Absences)

Estrutura de Dados

Fluxo de Aprovação

Endpoints

Listar Ausências

Criar Ausência

Exemplo de Requisição

Respostas