Basis

Appearance

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

Os usuários staff são quem opera o estabelecimento: recepção, POS, governança e administração. Cada instância Tours tem sua própria base de usuários — o mesmo e-mail pode existir em duas unidades diferentes sem conflito. O acesso é feito com e-mail + PIN numérico (4 a 8 dígitos), pensado para agilidade no balcão, e o PIN nunca é armazenado em claro — apenas o hash.

O primeiro usuário (owner) nasce no setup da instância com o e-mail do dono da conta e um PIN temporário de 6 dígitos. Os demais são cadastrados aqui, e cada um recebe seus papéis — que definem o que pode fazer (ver Papéis & Permissões).

Headers obrigatórios

Todas as requisições devem incluir o header X-Tour-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 toursUser). 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/tours/user/users/login

Payload (Body) ​

AtributoTipoObrigatórioDescrição
emailstringSimE-mail do usuário na instância.
pinstringSimPIN numérico (4 a 8 dígitos).

Exemplo de Requisição ​

bash
curl -X POST "https://api.us.basis.tavares.in/v1/tours/user/users/login" \
  -H "X-Tour-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "bruno@tours.dev",
    "pin": "445566"
  }'

Respostas ​

200 OK

Retorna o token Bearer da sessão, válido por 30 dias.

json
{
  "type": "bearer",
  "name": "76055f09-1bbe-4ffd-9fd5-979cfdc95017",
  "token": "oat_Ng.OEtmT0k1b0RfRXR5Y3VLVFFrdGFZMjJkNVVlUEIwMDdmRkc3X1pNNjEyNDU0MjI0OTY",
  "abilities": ["*"],
  "lastUsedAt": null,
  "expiresAt": "2026-11-06T18:11:18.472Z"
}

422 Unprocessable Entity

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

json
{
  "errors": [{ "message": "Email/PIN inválidos" }]
}

Listar Usuários ​

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

http
GET /v1/tours/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 de exibição ou e-mail.
isActivebooleanNãoFiltra por usuários ativos/inativos.
orderByenumNãoid, displayName, 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/tours/user/users?search=maria&isActive=true" \
  -H "X-Tour-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": 10
  },
  "data": [
    {
      "id": 1,
      "tourId": 1,
      "userId": null,
      "displayName": "Bruno Demo",
      "email": "bruno@tours.dev",
      "locale": "pt-BR",
      "isActive": true,
      "createdAt": "2026-10-07T11:56:13.490-03:00",
      "updatedAt": "2026-10-07T15:09:42.397-03:00"
    }
  ]
}

Criar Usuário ​

Cadastra um novo membro da equipe (exige permissão staff.manage).

http
POST /v1/tours/user/users

Payload (Body) ​

AtributoTipoObrigatórioDescrição
displayNamestringSimNome de exibição (máx. 150 caracteres).
emailstringNãoE-mail único na instância (máx. 250 caracteres) — usado no login.
pinstringSimPIN inicial, numérico de 4 a 8 dígitos.
userIdnumberNãoID do usuário da plataforma vinculado (deve existir).
localestringNãoLocalidade do usuário (máx. 10 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/tours/user/users" \
  -H "X-Tour-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "Maria Atendente",
    "email": "maria.atendente@tours.dev",
    "pin": "445566",
    "isActive": true
  }'

Respostas ​

201 Created

Retorna o ID do usuário criado. O PIN é armazenado com hash — nunca em texto plano. Atribua os papéis em Atualizar Papéis.

json
{
  "id": 4
}

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 possui a permissão staff.manage (code: FORBIDDEN).

Listar para Dropdown ​

Retorna os usuários em formato simplificado (value/label com o nome de exibição), ideal para selects — como o responsável por um turno ou por uma ordem de manutenção.

http
GET /v1/tours/user/users/list

Aceita search e isActive como filtros opcionais de query.

Exemplo de Requisição ​

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

Respostas ​

200 OK

Retorna um array com os usuários.

json
[
  {
    "value": 1,
    "label": "Bruno Demo"
  },
  {
    "value": 4,
    "label": "Maria Atendente"
  }
]

Obter Usuário por ID ​

Recupera os detalhes de um usuário staff da instância, incluindo seus papéis.

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

Parâmetros de Rota ​

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

Respostas ​

200 OK

Retorna o usuário com toursRoles (o PIN nunca é exposto).

json
{
  "id": 4,
  "tourId": 1,
  "userId": null,
  "displayName": "Maria Atendente",
  "email": "maria.atendente@tours.dev",
  "locale": null,
  "isActive": true,
  "createdAt": "2026-10-07T15:11:18.847-03:00",
  "updatedAt": "2026-10-07T15:11:18.847-03:00",
  "toursRoles": [
    {
      "id": 1,
      "code": "owner",
      "name": "Proprietário"
    }
  ]
}

404 Not Found

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

Atualizar Usuário ​

Atualiza dados e status de um membro da equipe (exige permissão staff.manage).

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

Payload (Body) ​

AtributoTipoObrigatórioDescrição
displayNamestringSimNome de exibição (máx. 150 caracteres).
emailstringNãoE-mail único na instância (máx. 250 caracteres).
pinstringNãoNovo PIN (4 a 8 dígitos) — envie apenas para redefinir.
userIdnumberNãoID do usuário da plataforma vinculado.
localestringNãoLocalidade (máx. 10 caracteres).
isActivebooleanNãoAtiva ou desativa o usuário.

Exemplo de Requisição ​

bash
curl -X PUT "https://api.us.basis.tavares.in/v1/tours/user/users/4" \
  -H "X-Tour-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "Maria Atendente Silva",
    "email": "maria.atendente@tours.dev",
    "isActive": true
  }'

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.

403 Forbidden

Ocorre quando o usuário autenticado não possui a permissão staff.manage (code: FORBIDDEN).

Atualizar Papéis ​

Substitui os papéis de um usuário staff (exige permissão staff.manage). Os papéis definem as permissões do usuário na instância — veja Papéis & Permissões.

http
PUT /v1/tours/user/users/:id/roles

Payload (Body) ​

AtributoTipoObrigatórioDescrição
roleIdsnumber[]SimIDs dos papéis da instância a vincular ao usuário.

Exemplo de Requisição ​

bash
curl -X PUT "https://api.us.basis.tavares.in/v1/tours/user/users/4/roles" \
  -H "X-Tour-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "roleIds": [1]
  }'

Respostas ​

204 No Content

Papéis atualizados com sucesso.

422 Unprocessable Entity

Ocorre quando algum papel não existe na instância.

403 Forbidden

Ocorre quando o usuário autenticado não possui a permissão staff.manage (code: FORBIDDEN).

Remover Usuário ​

Remove um usuário via soft delete (exige permissão staff.manage).

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

Respostas ​

204 No Content

Remoção concluída com sucesso.

403 Forbidden

Ocorre quando o usuário autenticado não possui a permissão staff.manage (code: FORBIDDEN).

A Própria Conta ​

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

Perfil (GET) ​

http
GET /v1/tours/user/users/me

Respostas ​

200 OK

Retorna os dados do usuário autenticado, com seus papéis.

json
{
  "id": 1,
  "tourId": 1,
  "userId": null,
  "displayName": "Bruno Demo",
  "email": "bruno@tours.dev",
  "locale": "pt-BR",
  "isActive": true,
  "createdAt": "2026-10-07T11:56:13.490-03:00",
  "updatedAt": "2026-10-07T15:09:42.397-03:00",
  "toursRoles": [
    {
      "id": 1,
      "code": "owner",
      "name": "Proprietário"
    }
  ]
}

Atualizar Perfil (PUT) ​

http
PUT /v1/tours/user/users/me

Payload (Body) ​

AtributoTipoObrigatórioDescrição
displayNamestringSimNome de exibição (máx. 150 caracteres).
localestringNãoLocalidade (máx. 10 caracteres).

Exemplo de Requisição ​

bash
curl -X PUT "https://api.us.basis.tavares.in/v1/tours/user/users/me" \
  -H "X-Tour-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "Bruno Demo",
    "locale": "pt-BR"
  }'

Respostas ​

204 No Content

Perfil atualizado com sucesso.

Trocar PIN ​

Redefine o PIN do usuário autenticado — não exige o PIN anterior.

http
PATCH /v1/tours/user/users/change-pin

Payload (Body) ​

AtributoTipoObrigatórioDescrição
pinstringSimNovo PIN (4 a 8 dígitos).

Exemplo de Requisição ​

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

Respostas ​

204 No Content

PIN alterado — o próximo login já usa o novo PIN (tokens emitidos continuam válidos).

Logout ​

Invalida o token atual imediatamente.

http
POST /v1/tours/user/users/logout

Respostas ​

204 No Content

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