Basis

Appearance

Usuários & Autenticação (Staff) ​

Os usuários staff são quem opera a agenda: dono, gerente, recepcionista e o profissional que entra para ver a própria agenda. Cada instância Booking tem sua própria base de usuários — o mesmo e-mail pode existir em duas unidades diferentes sem conflito.

O primeiro usuário (owner) nasce no setup da instância com o e-mail do dono da conta. Os demais são cadastrados aqui.

Headers obrigatórios

Todas as requisições devem incluir o header X-Booking-Id (UUID) com o identificador da instância. Endpoints privados exigem também Authorization: Bearer {token} com o token de um usuário staff (guard bookingUser). O único endpoint público desta página é o login.

Endpoints ​

Login ​

Autentica um usuário staff e retorna o token de acesso (30 dias).

http
POST /v1/booking/user/users/login

Payload (Body) ​

AtributoTipoObrigatórioDescrição
emailstringSimE-mail do usuário na instância.
passwordstringSimSenha do usuário.

Exemplo de Requisição ​

bash
curl -X POST "https://api.us.basis.tavares.in/v1/booking/user/users/login" \
  -H "X-Booking-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "ana.souza@studio.com",
    "password": "password123"
  }'

Respostas ​

200 OK

Retorna o token Bearer da sessão.

json
{
  "type": "bearer",
  "name": "a2e5fa09-51b0-40b2-af3e-d6c5530cb112",
  "token": "oat_MQ.aXJjMFNEbFc1V3AxTzVydFctQi0xQXU5NXVKNkhuYzZaaDA5bks2bTYzNjg1MDMwNA",
  "abilities": ["*"],
  "lastUsedAt": null,
  "expiresAt": "2026-10-13T01:16:25.436Z"
}

422 Unprocessable Entity

Ocorre quando as credenciais estão erradas, o e-mail não existe na instância ou o usuário está inativo.

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

Listar Usuários ​

Lista os usuários staff da instância, com paginação, busca e filtros.

http
GET /v1/booking/user/users

Parâmetros de Query ​

NomeTipoObrigatórioDescrição
pagenumberNãoO número da página (mínimo: 1).
perPagenumberNãoItens por página (entre 1 e 100, padrão: 25).
searchstringNãoBusca por nome, sobrenome ou e-mail.
roleenumNãoFiltra por papel: owner, manager, receptionist, professional ou staff.
isActivebooleanNãoFiltra por usuários ativos/inativos.
orderByenumNãoid, firstName, lastName, email ou createdAt (padrão: id).
orderDirectionenumNãoasc ou desc (padrão: desc).

Exemplo de Requisição ​

bash
curl -X GET "https://api.us.basis.tavares.in/v1/booking/user/users?search=ana&role=receptionist" \
  -H "X-Booking-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"

Respostas ​

200 OK

Retorna a página de usuários no formato meta/data.

json
{
  "meta": {
    "currentPage": 1,
    "perPage": 25
  },
  "data": [
    {
      "id": 2,
      "bookingId": 1,
      "firstName": "Ana",
      "lastName": "Souza",
      "email": "ana.souza@studio.com",
      "role": "receptionist",
      "phone": "11999990000",
      "avatarUrl": null,
      "lastLoginAt": null,
      "isActive": true,
      "createdAt": "2026-09-10T14:22:10.000+00:00",
      "updatedAt": "2026-09-10T14:22:10.000+00:00"
    }
  ]
}

Criar Usuário ​

Cadastra um novo membro da equipe. Exige papel owner ou manager.

http
POST /v1/booking/user/users

Payload (Body) ​

AtributoTipoObrigatórioDescrição
firstNamestringSimNome (máx. 100 caracteres).
lastNamestringSimSobrenome (máx. 100 caracteres).
emailstringSimE-mail único na instância (máx. 250 caracteres).
passwordstringSimSenha inicial (8 a 32 caracteres).
roleenumSimowner, manager, receptionist, professional ou staff.
phonestringNãoTelefone (máx. 50 caracteres).
avatarUrlstringNãoURL do avatar (máx. 255 caracteres).
isActivebooleanNãoIndica se já nasce ativo (padrão: true).

Exemplo de Requisição ​

bash
curl -X POST "https://api.us.basis.tavares.in/v1/booking/user/users" \
  -H "X-Booking-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Ana",
    "lastName": "Souza",
    "email": "ana.souza@studio.com",
    "password": "password123",
    "role": "receptionist"
  }'

Respostas ​

201 Created

Retorna o ID do usuário criado. A senha é armazenada com hash — nunca em texto plano.

json
{
  "id": 2
}

422 Unprocessable Entity

Ocorre quando o e-mail já existe na instância ou o payload é inválido.

json
{
  "errors": [
    {
      "message": "Email já cadastrado",
      "rule": "database.unique",
      "field": "email"
    }
  ]
}

403 Forbidden

Ocorre quando o usuário autenticado não é owner nem manager (code: FORBIDDEN).

Listar para Dropdown ​

Retorna os usuários em formato simplificado (value/label com nome completo), ideal para selects — como o vínculo de usuário a um profissional.

http
GET /v1/booking/user/users/list

Aceita search, role e isActive como filtros opcionais de query.

Exemplo de Requisição ​

bash
curl -X GET "https://api.us.basis.tavares.in/v1/booking/user/users/list" \
  -H "X-Booking-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"

Respostas ​

200 OK

Retorna um array com os usuários ordenados por nome.

json
[
  {
    "value": 2,
    "label": "Ana Souza"
  }
]

Obter Usuário por ID ​

Recupera os detalhes de um usuário staff da instância.

http
GET /v1/booking/user/users/:id

Parâmetros de Rota ​

NomeTipoObrigatórioDescrição
idnumberSimO ID do usuário.

Respostas ​

200 OK

Retorna o usuário (sem a senha, que nunca é exposta).

404 Not Found

Ocorre quando o usuário não existe na instância.

Atualizar Usuário ​

Atualiza dados, papel e status de um membro da equipe. Exige papel owner ou manager.

http
PUT /v1/booking/user/users/:id

Payload (Body) ​

Aceita os mesmos campos da criação; password é opcional aqui — envie apenas para redefinir a senha.

Respostas ​

204 No Content

Atualização concluída com sucesso.

422 Unprocessable Entity

Ocorre quando o e-mail informado já pertence a outro usuário da instância.

Remover Usuário ​

Remove um usuário via soft delete. Exige papel owner ou manager.

http
DELETE /v1/booking/user/users/:id

Respostas ​

204 No Content

Remoção concluída com sucesso.

404 Not Found

Ocorre quando o usuário não existe na instância.

A Própria Conta ​

Endpoints do usuário autenticado — disponíveis para qualquer papel.

Perfil (GET) ​

http
GET /v1/booking/user/users/me

Respostas ​

200 OK

Retorna os dados do usuário autenticado.

json
{
  "id": 1,
  "bookingId": 1,
  "firstName": "Gerson",
  "lastName": "Tavares",
  "email": "gerson@studio.com",
  "role": "owner",
  "phone": null,
  "avatarUrl": null,
  "lastLoginAt": null,
  "isActive": true,
  "createdAt": "2026-09-12T22:05:23.790-03:00",
  "updatedAt": "2026-09-12T22:05:23.790-03:00"
}

Atualizar Perfil (PUT) ​

http
PUT /v1/booking/user/users/me

Payload (Body) ​

AtributoTipoObrigatórioDescrição
firstNamestringSimNome (máx. 100 caracteres).
lastNamestringSimSobrenome (máx. 100 caracteres).
phonestringNãoTelefone (máx. 50 caracteres).
avatarUrlstringNãoURL do avatar (máx. 255 caracteres).

Respostas ​

204 No Content

Perfil atualizado com sucesso.

Trocar Senha ​

http
PATCH /v1/booking/user/users/change-password

Payload (Body) ​

AtributoTipoObrigatórioDescrição
passwordstringSimNova senha (8 a 32 caracteres).

Exemplo de Requisição ​

bash
curl -X PATCH "https://api.us.basis.tavares.in/v1/booking/user/users/change-password" \
  -H "X-Booking-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{ "password": "newpassword123" }'

Respostas ​

204 No Content

Senha alterada — o próximo login já usa a nova senha (tokens emitidos continuam válidos).

Logout ​

Invalida o token atual imediatamente.

http
POST /v1/booking/user/users/logout

Respostas ​

204 No Content

Logout concluído — o token não pode mais ser usado.