Instâncias & Setup

Uma instância de Timesheet é o controle de horas da sua empresa dentro da plataforma: profissionais, jornadas, apontamentos, projetos e períodos vivem dentro dela. Antes de usar qualquer endpoint da operação (/v1/timesheet/...), você precisa provisionar uma instância — e é isso que estes endpoints fazem.

A criação é mais do que um simples INSERT: em uma única transação, a plataforma cria a jornada padrão Comercial 44h (com os 7 dias da semana detalhados) e o primeiro profissional com papel de gestor (isManager: true), devolvendo as credenciais de acesso e o tokenHeader que identifica a instância em todas as chamadas seguintes.

Headers obrigatórios

Estes endpoints pertencem à área do dono da conta na plataforma. Todas as requisições exigem Authorization: Bearer {token} (autenticação da plataforma, guard user) e o parâmetro de query workspaceId com o ID do projeto. O header X-Timesheet-Id não é usado aqui — ele é o tokenHeader gerado na criação da instância. Limite de 100 requisições por minuto (429 ao exceder).

Estrutura de Dados Principal

Uma instância de Timesheet contém as seguintes informações principais:

Campo	Tipo	Descrição
`name`	`String`	Nome da instância (máx. 150 caracteres).
`slug`	`String`	Slug gerado automaticamente a partir do nome.
`tokenHeader`	`String`	UUID que identifica a instância — usado como `X-Timesheet-Id` nas APIs `/v1/timesheet/**`.
`timezone`	`String`	Fuso horário padrão (padrão: `America/Sao_Paulo`) — define o dia local de cada batida de ponto.
`currency`	`String`	Moeda padrão (3 letras, padrão: `BRL`) — usada nos snapshots financeiros e períodos.
`weekStartsOn`	`Number`	Primeiro dia da semana (`0` = domingo a `6` = sábado, padrão: `1`).
`maxIntervalsPerDay`	`Number`	Máximo de intervalos de trabalho por dia (1 a 12, padrão: `2`) — estourar gera `MAX_INTERVALS_REACHED`.
`roundingMinutes`	`Number`	Arredondamento de apontamentos em minutos (padrão: `0`, sem arredondamento).
`toleranceMinutes`	`Number`	Tolerância de atraso/adiantamento em minutos (padrão: `0`).
`isRequiresGeolocation`	`Boolean`	Exige coordenadas válidas dentro de uma geofence para bater ponto (padrão: `false`).
`isAllowsManualEntry`	`Boolean`	Permite apontamentos manuais (padrão: `true`) — `false` gera `MANUAL_ENTRY_NOT_ALLOWED`.
`isRequiresApproval`	`Boolean`	Indica que dias seguem fluxo de aprovação (padrão: `true`).
`periodClosingDay`	`Number`	Dia de virada do período de apuração (1 a 28, padrão: `1` = mês civil) — ver Períodos & Fechamento.
`settings`	`Object`	Configurações livres da instância (JSONB).
`workspaceMailId`	`Number`	Configuração de e-mail do workspace usada para notificações (opcional) — deve pertencer ao workspace e estar ativa.
`workspaceStorageId`	`Number`	Storage do workspace usado para upload de arquivos (opcional) — deve pertencer ao workspace e estar ativo.
`hash`	`String`	UUID interno da instância (retornado no detalhe).
`isActive`	`Boolean`	Indica se a instância está ativa — inativas respondem `503` nas APIs da operação.

Setup Inicial

O POST /user/timesheets executa todo o provisionamento em uma única transação — se qualquer etapa falhar, nada é persistido:

Jornada padrão: chamada Comercial 44h (weeklyMinutes: 2640, isDefault: true), com os dias da semana detalhados:
Dia Horário Minutos esperados Intervalo
Segunda a sexta 09:00 – 18:00 480 60 min
Sábado e domingo — 0 0
Primeiro gestor: criado com o nome e e-mail do usuário autenticado na plataforma, isManager: true e status active, já vinculado à conta da plataforma.
Resposta 201: inclui email, password (senha temporária, exibida uma única vez) e tokenHeader.

Dia	Horário	Minutos esperados	Intervalo
Segunda a sexta	09:00 – 18:00	480	60 min
Sábado e domingo	—	0	0

Guarde a senha temporária e o tokenHeader imediatamente — eles não podem ser recuperados depois (o token pode ser regerado, a senha não).

Endpoints

Listar Instâncias

Lista as instâncias de Timesheet do projeto, com paginação e busca por nome.

http

GET /user/timesheets

Parâmetros de Query

Nome	Tipo	Obrigatório	Descrição
`workspaceId`	`number`	Sim	ID do projeto (workspace) ao qual a instância pertence.
`page`	`number`	Não	O número da página (mínimo: 1).
`perPage`	`number`	Não	Itens por página (entre 1 e 100, padrão: 25).
`search`	`string`	Não	Busca por termo no nome da instância (máx. 150 caracteres).

Exemplo de Requisição

bash

curl -X GET "https://api.us.basis.tavares.in/user/timesheets?workspaceId=1&page=1&perPage=25" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"

Respostas

200 OK

Retorna um objeto de paginação contendo a lista de instâncias.

json

{
  "meta": {
    "total": 2,
    "perPage": 25,
    "currentPage": 1,
    "lastPage": 1,
    "firstPage": 1,
    "firstPageUrl": "/?page=1",
    "lastPageUrl": "/?page=1",
    "nextPageUrl": null,
    "previousPageUrl": null
  },
  "data": [
    {
      "id": 4,
      "name": "Timesheet Acme",
      "slug": "timesheet-acme",
      "tokenHeader": "a8a70c31-1c39-41b3-abc3-77a85c536e72",
      "isActive": true,
      "createdAt": "2026-09-25T12:33:49.276-03:00",
      "updatedAt": "2026-09-25T12:33:49.276-03:00"
    }
  ]
}

Formato da paginação

Diferente dos endpoints /v1/timesheet/** (que retornam apenas currentPage e perPage no meta), esta área usa o paginador completo da plataforma.

403 Forbidden

Ocorre quando o workspaceId não é informado ou o projeto pertence a outro usuário.

Criar Instância

Provisiona uma nova instância de Timesheet, executando o setup inicial completo em transação.

http

POST /user/timesheets

Payload (Body)

Atributo	Tipo	Obrigatório	Descrição
`timesheet.name`	`string`	Sim	Nome da instância (máx. 150 caracteres).
`timesheet.timezone`	`string`	Não	Fuso horário (máx. 64 caracteres, padrão: `America/Sao_Paulo`).
`timesheet.currency`	`string`	Não	Moeda (exatamente 3 letras, padrão: `BRL`).
`timesheet.weekStartsOn`	`number`	Não	Primeiro dia da semana, `0`–`6` (padrão: `1`).
`timesheet.maxIntervalsPerDay`	`number`	Não	Máximo de intervalos por dia, 1–12 (padrão: `2`).
`timesheet.roundingMinutes`	`number`	Não	Arredondamento em minutos, 0–60 (padrão: `0`).
`timesheet.toleranceMinutes`	`number`	Não	Tolerância em minutos (padrão: `0`).
`timesheet.isRequiresGeolocation`	`boolean`	Não	Exige geolocalização na batida (padrão: `false`).
`timesheet.isAllowsManualEntry`	`boolean`	Não	Permite apontamentos manuais (padrão: `true`).
`timesheet.isRequiresApproval`	`boolean`	Não	Exige aprovação de dias (padrão: `true`).
`timesheet.periodClosingDay`	`number`	Não	Dia de virada do período, 1–28 (padrão: `1`).
`timesheet.isActive`	`boolean`	Não	Indica se a instância já nasce ativa (padrão: `true`).
`timesheet.workspaceMailId`	`number`	Não	Configuração de e-mail do workspace para notificações (nullable).
`timesheet.workspaceStorageId`	`number`	Não	Storage do workspace para upload de arquivos (nullable).
`workspaceDomains`	`number[]`	Sim	IDs dos domínios do projeto vinculados à instância (pode ser um array vazio).

Exemplo de Requisição

bash

curl -X POST "https://api.us.basis.tavares.in/user/timesheets?workspaceId=1" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "timesheet": {
      "name": "Ponto Acme",
      "timezone": "America/Sao_Paulo",
      "currency": "BRL",
      "isRequiresGeolocation": true,
      "periodClosingDay": 25
    },
    "workspaceDomains": [3]
  }'

Respostas

201 Created

Retorna as credenciais do primeiro gestor e o token da instância. A senha temporária é exibida uma única vez.

json

{
  "email": "maria@acme.com",
  "password": "a1b2c3d4",
  "tokenHeader": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

422 Unprocessable Entity

Erro de validação nos campos enviados.

json

{
  "errors": [
    {
      "message": "Nome é obrigatório",
      "rule": "required",
      "field": "timesheet.name"
    }
  ]
}

Obter Instância por ID

Recupera os detalhes de uma instância, incluindo os domínios vinculados.

http

GET /user/timesheets/:id

Parâmetros de Rota

Nome	Tipo	Obrigatório	Descrição
`id`	`number`	Sim	O ID da instância.

Exemplo de Requisição

bash

curl -X GET "https://api.us.basis.tavares.in/user/timesheets/1?workspaceId=1" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"

Respostas

200 OK

Retorna a instância com workspaceDomains.

json

{
  "id": 4,
  "workspaceId": 17,
  "name": "Timesheet Acme",
  "slug": "timesheet-acme",
  "timezone": "America/Sao_Paulo",
  "currency": "BRL",
  "weekStartsOn": 1,
  "maxIntervalsPerDay": 2,
  "roundingMinutes": 0,
  "toleranceMinutes": 10,
  "isRequiresGeolocation": false,
  "isAllowsManualEntry": true,
  "isRequiresApproval": true,
  "periodClosingDay": 1,
  "settings": {},
  "hash": "ccb72fa8-b2ef-42ca-bce0-1815e99bd05e",
  "tokenHeader": "a8a70c31-1c39-41b3-abc3-77a85c536e72",
  "isActive": true,
  "createdAt": "2026-09-25T12:33:49.276-03:00",
  "updatedAt": "2026-09-25T12:33:49.276-03:00",
  "deletedAt": null,
  "workspaceDomains": [
    {
      "id": 15,
      "uri": "ponto.acme.com"
    }
  ]
}

404 Not Found

Ocorre quando a instância não existe no projeto informado.

Atualizar Instância

Atualiza as configurações de uma instância e sincroniza os domínios vinculados. Usa o mesmo schema da criação: o objeto timesheet (com name obrigatório) e o array workspaceDomains (que substitui os vínculos atuais).

http

PUT /user/timesheets/:id

Exemplo de Requisição

bash

curl -X PUT "https://api.us.basis.tavares.in/user/timesheets/1?workspaceId=1" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "timesheet": {
      "name": "Ponto Acme",
      "maxIntervalsPerDay": 4,
      "isRequiresGeolocation": false
    },
    "workspaceDomains": [3]
  }'

Respostas

204 No Content

Atualização concluída com sucesso.

404 Not Found

Ocorre quando a instância não existe no projeto informado.

Remover Instância

Remove uma instância via soft delete — o registro deixa de aparecer em qualquer consulta, mas não é apagado fisicamente.

http

DELETE /user/timesheets/:id

Exemplo de Requisição

bash

curl -X DELETE "https://api.us.basis.tavares.in/user/timesheets/1?workspaceId=1" \
  -H "Authorization: Bearer {token}"

Respostas

204 No Content

Remoção concluída com sucesso.

Retorna as instâncias em formato simplificado (value/label), ideal para selects no frontend.

http

GET /user/timesheets/list

Parâmetros de Query

Nome	Tipo	Obrigatório	Descrição
`workspaceId`	`number`	Sim	ID do projeto (workspace).
`search`	`string`	Não	Busca por termo no nome da instância (máx. 150 caracteres).

Respostas

200 OK

Retorna um array com as instâncias.

json

[
  {
    "value": 1,
    "label": "Ponto Acme"
  }
]

Regerar Token da Instância

Gera um novo tokenHeader (UUID) para a instância. O token anterior deixa de ser válido imediatamente — todas as integrações que usam o header X-Timesheet-Id precisam ser atualizadas.

http

PATCH /user/timesheets/:id/change-token

Exemplo de Requisição

bash

curl -X PATCH "https://api.us.basis.tavares.in/user/timesheets/1/change-token?workspaceId=1" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"

Respostas

200 OK

Retorna o novo token da instância.

json

{
  "tokenHeader": "9b2f7c1e-4d3a-4e5f-8a6b-1c2d3e4f5a6b"
}

404 Not Found

Ocorre quando a instância não existe no projeto informado.

Instâncias & Setup ​

Estrutura de Dados Principal ​

Setup Inicial ​

Endpoints ​

Listar Instâncias ​

Parâmetros de Query ​

Exemplo de Requisição ​

Respostas ​

Criar Instância ​

Payload (Body) ​

Exemplo de Requisição ​

Respostas ​

Obter Instância por ID ​

Parâmetros de Rota ​

Exemplo de Requisição ​

Respostas ​

Atualizar Instância ​

Exemplo de Requisição ​

Respostas ​

Remover Instância ​

Exemplo de Requisição ​

Respostas ​

Listar para Dropdown ​

Parâmetros de Query ​

Respostas ​

Regerar Token da Instância ​

Exemplo de Requisição ​

Respostas ​

Instâncias & Setup

Estrutura de Dados Principal

Setup Inicial

Endpoints

Listar Instâncias

Parâmetros de Query

Exemplo de Requisição

Respostas

Criar Instância

Payload (Body)

Exemplo de Requisição

Respostas

Obter Instância por ID

Parâmetros de Rota

Exemplo de Requisição

Respostas

Atualizar Instância

Exemplo de Requisição

Respostas

Remover Instância

Exemplo de Requisição

Respostas

Listar para Dropdown

Parâmetros de Query

Respostas

Regerar Token da Instância

Exemplo de Requisição

Respostas