Usuários & Autenticação

Os usuários do Timesheet são os profissionais da instância — quem bate ponto, aponta horas em projetos, pede ausências e abre chamados. Possuem autenticação própria do módulo, separada da plataforma.

O vínculo com a conta da plataforma (userId) é opcional: um profissional pode existir só para bater ponto num tablet na portaria, sem login. Para isso, basta cadastrá-lo sem email e sem password.

Usuários não são apagados fisicamente: como o histórico de apontamentos referencia o autor, a remoção é lógica. Para tirar alguém de operação sem remover, use status: 'inactive' ou terminated.

Headers obrigatórios

Todas as requisições devem incluir o header X-Timesheet-Id (UUID) com o identificador da instância. Os endpoints autenticados exigem também Authorization: Bearer {token} com o token do profissional (guard timesheetUser). Somente profissionais com status: 'active' autenticam.

Estrutura de Dados Principal

Campo	Tipo	Descrição
`id`	`Number`	Identificador do profissional.
`firstName`	`String`	Nome (máx. 150 caracteres).
`lastName`	`String`	Sobrenome (máx. 150 caracteres, opcional).
`email`	`String`	E-mail de login (máx. 250 caracteres, único por instância, opcional).
`password`	`String`	Senha (8 a 32 caracteres, opcional — sem ela, não há login). Nunca é retornada.
`employeeCode`	`String`	Matrícula interna (máx. 50 caracteres, única por instância, opcional).
`timesheetDepartmentId`	`Number`	Departamento (opcional) — ver Estrutura Organizacional.
`timesheetPositionId`	`Number`	Cargo (opcional).
`timesheetUserId`	`Number`	Gestor direto do profissional (opcional).
`phone`	`String`	Telefone (máx. 30 caracteres, opcional).
`document`	`String`	Documento (CPF/CNPJ, máx. 50 caracteres, opcional).
`avatarUrl`	`String`	URL do avatar (máx. 255 caracteres, opcional).
`timezone`	`String`	Fuso horário individual (opcional) — sobrepõe o da instância no cálculo do dia local.
`employmentType`	`String`	Vínculo: `clt`, `pj`, `intern`, `temporary`, `freelancer` ou `other`.
`status`	`String`	`invited`, `active`, `inactive` ou `terminated`.
`hiredOn` / `terminatedOn`	`Date`	Datas de admissão e desligamento (opcionais).
`isManager`	`Boolean`	Papel de gestor — libera o gerenciamento da instância e a aprovação de dias/períodos.
`metadata`	`Object`	Dados livres (JSONB).

Autenticação

Autentica um profissional e retorna o token de acesso da operação.

http

POST /v1/timesheet/users/login

Payload (Body)

Atributo	Tipo	Obrigatório	Descrição
`email`	`string`	Sim	E-mail do profissional.
`password`	`string`	Sim	Senha (8 a 32 caracteres).

Exemplo de Requisição

bash

curl -X POST "https://api.us.basis.tavares.in/v1/timesheet/users/login" \
  -H "X-Timesheet-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "maria@acme.com",
    "password": "Password@123"
  }'

Respostas

200 OK

Retorna o token Bearer com validade de 30 dias.

json

{
  "type": "bearer",
  "name": "6522b2f2-4101-4748-b7b1-f7716463e878",
  "token": "oat_Mw.Njh2OWRieE90NzF1NE1LaUhTUVFHSUJGNE02T3E3SFNiWUhESnNmeDM1MDAyNzQ2NzY",
  "abilities": ["*"],
  "lastUsedAt": null,
  "expiresAt": "2026-10-10T03:04:39.783Z"
}

422 Unprocessable Entity

Credenciais inválidas, profissional sem senha cadastrada ou não encontrado.

json

{
  "errors": [
    {
      "message": "Email/Senha inválida"
    }
  ]
}

Logout

Invalida o token usado na requisição imediatamente.

http

POST /v1/timesheet/users/logout

Respostas

204 No Content

Token invalidado com sucesso.

Perfil do Profissional Autenticado

Retorna os dados do profissional autenticado.

http

GET /v1/timesheet/users/me

Respostas

200 OK

Retorna o perfil completo (sem a senha).

json

{
  "id": 6,
  "timesheetId": 4,
  "userId": null,
  "timesheetDepartmentId": 3,
  "timesheetPositionId": 3,
  "timesheetUserId": null,
  "employeeCode": "EMP-002",
  "firstName": "Ana",
  "lastName": "Souza",
  "email": "ana.souza@example.com",
  "phone": "11988887777",
  "document": null,
  "avatarUrl": null,
  "timezone": null,
  "employmentType": "clt",
  "status": "active",
  "hiredOn": "2026-01-15",
  "terminatedOn": null,
  "isManager": false,
  "metadata": {},
  "createdAt": "2026-09-25T12:33:50.393-03:00",
  "updatedAt": "2026-09-25T12:33:50.393-03:00",
  "deletedAt": null
}

Atualizar Próprio Perfil

Atualiza os dados pessoais do profissional autenticado (nome, sobrenome, telefone, fuso e avatar). Campos administrativos (status, cargo, isManager) só podem ser alterados por um gestor via PUT /users/:id.

http

PUT /v1/timesheet/users/me

Payload (Body)

Atributo	Tipo	Obrigatório	Descrição
`firstName`	`string`	Não	Nome (máx. 150 caracteres).
`lastName`	`string`	Não	Sobrenome (máx. 150 caracteres, pode ser `null`).
`phone`	`string`	Não	Telefone (máx. 30 caracteres, pode ser `null`).
`timezone`	`string`	Não	Fuso horário (máx. 64 caracteres, pode ser `null`).
`avatarUrl`	`string`	Não	URL do avatar (máx. 255 caracteres, pode ser `null`).

Respostas

204 No Content

Atualização concluída com sucesso.

Trocar Senha

Troca a senha do profissional autenticado.

http

PATCH /v1/timesheet/users/change-password

Payload (Body)

Atributo	Tipo	Obrigatório	Descrição
`password`	`string`	Sim	Nova senha (8 a 32 caracteres).

Respostas

204 No Content

Senha alterada com sucesso.

Gestão da Equipe (somente gestores)

Os endpoints abaixo exigem isManager: true — profissionais recebem 403 FORBIDDEN.

Listar Profissionais

Lista os profissionais da instância, com paginação, busca e filtro por status.

http

GET /v1/timesheet/users

Parâmetros de Query

Nome	Tipo	Obrigatório	Descrição
`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).
`search`	`string`	Não	Busca por termo no nome/e-mail (máx. 150 caracteres).
`status`	`string`	Não	Filtra por `invited`, `active`, `inactive` ou `terminated`.

Respostas

200 OK

Retorna um objeto de paginação com os profissionais.

403 Forbidden

Ocorre quando o autenticado não é gestor.

Retorna os profissionais em formato simplificado (value/label), com search e limit (máx. 100) opcionais.

http

GET /v1/timesheet/users/list

Obter Profissional por ID

http

GET /v1/timesheet/users/:id

Respostas

200 OK

Retorna o profissional.

404 Not Found

Ocorre quando o profissional não existe na instância.

Criar Profissional

Cadastra um novo profissional na instância.

http

POST /v1/timesheet/users

Payload (Body)

Atributo	Tipo	Obrigatório	Descrição
`firstName`	`string`	Sim	Nome (máx. 150 caracteres).
`lastName`	`string`	Não	Sobrenome (máx. 150 caracteres).
`email`	`string`	Não	E-mail de login (único por instância).
`password`	`string`	Não	Senha (8 a 32 caracteres) — sem ela, o profissional não autentica.
`employeeCode`	`string`	Não	Matrícula (única por instância, máx. 50 caracteres).
`timesheetDepartmentId`	`number`	Não	Departamento existente na instância.
`timesheetPositionId`	`number`	Não	Cargo existente na instância.
`timesheetUserId`	`number`	Não	Gestor direto (profissional existente na instância).
`phone`	`string`	Não	Telefone (máx. 30 caracteres).
`document`	`string`	Não	Documento (máx. 50 caracteres).
`avatarUrl`	`string`	Não	URL do avatar (máx. 255 caracteres).
`timezone`	`string`	Não	Fuso horário individual (máx. 64 caracteres).
`employmentType`	`string`	Não	`clt`, `pj`, `intern`, `temporary`, `freelancer` ou `other`.
`status`	`string`	Não	`invited`, `active`, `inactive` ou `terminated`.
`hiredOn`	`date`	Não	Data de admissão (`YYYY-MM-DD`).
`isManager`	`boolean`	Não	Papel de gestor (padrão: `false`).
`metadata`	`object`	Não	Dados livres.

Exemplo de Requisição

bash

curl -X POST "https://api.us.basis.tavares.in/v1/timesheet/users" \
  -H "X-Timesheet-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "João",
    "lastName": "Souza",
    "email": "joao@acme.com",
    "password": "Password@123",
    "employeeCode": "AC-002",
    "timesheetDepartmentId": 1,
    "timesheetPositionId": 2,
    "employmentType": "clt",
    "hiredOn": "2026-09-01"
  }'

Respostas

201 Created

Retorna o ID do profissional criado.

json

{
  "id": 2
}

Atualizar Profissional

Atualiza os dados de um profissional. Mesmo schema da criação, com todos os campos opcionais (mais terminatedOn).

http

PUT /v1/timesheet/users/:id

Respostas

204 No Content

Atualização concluída com sucesso.

Remover Profissional

Remove um profissional via soft delete.

http

DELETE /v1/timesheet/users/:id

Respostas

204 No Content

Remoção concluída com sucesso.

Usuários & Autenticação ​

Estrutura de Dados Principal ​

Autenticação ​

Login ​

Payload (Body) ​

Exemplo de Requisição ​

Respostas ​

Logout ​

Respostas ​

Perfil do Profissional Autenticado ​

Respostas ​

Atualizar Próprio Perfil ​

Payload (Body) ​

Respostas ​

Trocar Senha ​

Payload (Body) ​

Respostas ​

Gestão da Equipe (somente gestores) ​

Listar Profissionais ​

Parâmetros de Query ​

Respostas ​

Listar para Dropdown ​

Obter Profissional por ID ​

Respostas ​

Criar Profissional ​

Payload (Body) ​

Exemplo de Requisição ​

Respostas ​

Atualizar Profissional ​

Respostas ​

Remover Profissional ​

Respostas ​

Usuários & Autenticação

Estrutura de Dados Principal

Autenticação

Login

Payload (Body)

Exemplo de Requisição

Respostas

Logout

Respostas

Perfil do Profissional Autenticado

Respostas

Atualizar Próprio Perfil

Payload (Body)

Respostas

Trocar Senha

Payload (Body)

Respostas

Gestão da Equipe (somente gestores)

Listar Profissionais

Parâmetros de Query

Respostas

Listar para Dropdown

Obter Profissional por ID

Respostas

Criar Profissional

Payload (Body)

Exemplo de Requisição

Respostas

Atualizar Profissional

Respostas

Remover Profissional

Respostas