Papéis & Permissões

O controle de acesso do módulo Tours segue o modelo RBAC: cada usuário staff recebe um ou mais papéis (roles), e cada papel é composto de permissões. As permissões são o que a API verifica de fato — quando falta a permissão exigida, a resposta é 403 com code: FORBIDDEN.

Os dois lados do modelo têm escopos diferentes:

Papéis são por instância: cada estabelecimento monta os seus (recepcionista, caixa, governança…). Papéis semeados pelo sistema carregam isSystem: true — o owner (Proprietário) é criado no setup da instância com todas as permissões.
Permissões formam um catálogo global (29 itens semeados no setup), compartilhado por todas as instâncias. As rotas passam pela cadeia normal do módulo — X-Tour-Id e token staff são obrigatórios — mas o catálogo em si não é filtrado por instância.

A vinculação de papéis a usuários é feita em Atualizar Papéis.

Headers obrigatórios

Todas as requisições devem incluir o header X-Tour-Id (UUID) com o identificador da instância e Authorization: Bearer {token} com o token de um usuário staff (guard toursUser).

Catálogo de Permissões

As 29 permissões semeadas no setup, agrupadas por categoria:

Código	Categoria	Descrição
`reservation.read`	`reservas`	Visualizar reservas
`reservation.write`	`reservas`	Criar e editar reservas
`reservation.cancel`	`reservas`	Cancelar reservas e aplicar multa
`reservation.check_in`	`reservas`	Realizar check-in e check-out
`resource.assign`	`reservas`	Atribuir unidade física à reserva
`rate.read`	`tarifas`	Consultar tabelas de preço
`rate.write`	`tarifas`	Criar e alterar tarifas e regras
`pos.order`	`pos`	Lançar pedidos em comanda
`pos.void_item`	`pos`	Cancelar item já lançado
`pos.discount`	`pos`	Conceder desconto
`pos.transfer`	`pos`	Transferir itens entre comandas
`kds.update_status`	`pos`	Alterar status de preparo
`bill.issue`	`financeiro`	Fechar e emitir conta
`bill.split`	`financeiro`	Dividir conta
`payment.record`	`financeiro`	Registrar recebimento
`payment.refund`	`financeiro`	Estornar recebimento
`cash.open_close`	`financeiro`	Abrir e fechar caixa
`report.financial`	`financeiro`	Acessar relatórios financeiros
`stock.read`	`estoque`	Consultar estoque
`stock.adjust`	`estoque`	Ajustar saldo e registrar perdas
`stock.purchase`	`estoque`	Registrar entradas de compra
`customer.read`	`crm`	Consultar cadastro de clientes
`customer.write`	`crm`	Criar e editar clientes
`customer.document.read`	`crm`	Acessar documentos de identificação
`housekeeping.update`	`operacoes`	Atualizar status de limpeza
`maintenance.manage`	`operacoes`	Abrir e encerrar ordens de manutenção
`staff.manage`	`admin`	Gerenciar usuários e papéis
`settings.manage`	`admin`	Configurar tour, impostos e taxas
`audit.read`	`admin`	Consultar trilha de auditoria

Endpoints — Papéis

Listar Papéis

Lista os papéis da instância, com paginação, busca e filtros.

http

GET /v1/tours/user/roles

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, padrão: 25).
`search`	`string`	Não	Busca por código ou nome (máx. 150 caracteres).
`isSystem`	`boolean`	Não	Filtra por papéis de sistema / criados pelo administrador.
`orderBy`	`enum`	Não	`id`, `code`, `name` ou `createdAt` (padrão: `id`).
`orderDirection`	`enum`	Não	`asc` ou `desc` (padrão: `desc`).

Exemplo de Requisição

bash

curl -X GET "https://api.us.basis.tavares.in/v1/tours/user/roles" \
  -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 papéis no formato meta/data.

json

{
  "meta": {
    "currentPage": 1,
    "perPage": 10
  },
  "data": [
    {
      "id": 2,
      "tourId": 1,
      "code": "recepcionista",
      "name": "Recepcionista",
      "isSystem": false,
      "createdAt": "2026-10-07T11:56:13.797-03:00",
      "updatedAt": "2026-10-07T11:56:13.797-03:00"
    },
    {
      "id": 1,
      "tourId": 1,
      "code": "owner",
      "name": "Proprietário",
      "isSystem": true,
      "createdAt": "2026-10-07T11:56:13.297-03:00",
      "updatedAt": "2026-10-07T11:56:13.297-03:00"
    }
  ]
}

Criar Papel

Cria um novo papel na instância (exige permissão staff.manage). As permissões são atribuídas em seguida, em Atualizar Permissões do Papel.

http

POST /v1/tours/user/roles

Payload (Body)

Atributo	Tipo	Obrigatório	Descrição
`code`	`string`	Sim	Código único na instância (máx. 50 caracteres).
`name`	`string`	Sim	Nome de exibição (máx. 150 caracteres).
`isSystem`	`boolean`	Não	Marca o papel como de sistema (padrão: `false`).

Exemplo de Requisição

bash

curl -X POST "https://api.us.basis.tavares.in/v1/tours/user/roles" \
  -H "X-Tour-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "doc-atendente",
    "name": "Atendente Doc",
    "isSystem": false
  }'

Respostas

201 Created

Retorna o ID do papel criado.

json

{
  "id": 5
}

422 Unprocessable Entity

Ocorre quando o código já existe na instância ou o payload é inválido.

json

{
  "errors": [
    {
      "message": "Código já cadastrado",
      "rule": "database.unique",
      "field": "code"
    }
  ]
}

403 Forbidden

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

Retorna os papéis em formato simplificado (value/label), ideal para selects.

http

GET /v1/tours/user/roles/list

Aceita search e isSystem como filtros opcionais de query.

Exemplo de Requisição

bash

curl -X GET "https://api.us.basis.tavares.in/v1/tours/user/roles/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 papéis.

json

[
  {
    "value": 5,
    "label": "Atendente Doc"
  },
  {
    "value": 1,
    "label": "Proprietário"
  }
]

Obter Papel por ID

Recupera os detalhes de um papel da instância, incluindo suas permissões.

http

GET /v1/tours/user/roles/:id

Parâmetros de Rota

Nome	Tipo	Obrigatório	Descrição
`id`	`number`	Sim	O ID do papel.

Respostas

200 OK

Retorna o papel com toursPermissions.

json

{
  "id": 5,
  "tourId": 1,
  "code": "doc-atendente",
  "name": "Atendente Doc",
  "isSystem": false,
  "createdAt": "2026-10-07T15:11:06.548-03:00",
  "updatedAt": "2026-10-07T15:11:06.548-03:00",
  "toursPermissions": []
}

404 Not Found

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

Atualizar Papel

Atualiza código, nome ou flag de sistema de um papel (exige permissão staff.manage).

http

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

Payload (Body)

Atributo	Tipo	Obrigatório	Descrição
`code`	`string`	Não	Código único na instância (máx. 50 caracteres).
`name`	`string`	Não	Nome de exibição (máx. 150 caracteres).
`isSystem`	`boolean`	Não	Marca o papel como de sistema.

Respostas

204 No Content

Atualização concluída com sucesso.

422 Unprocessable Entity

Ocorre quando o código informado já pertence a outro papel da instância.

403 Forbidden

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

Atualizar Permissões do Papel

Substitui as permissões de um papel (exige permissão staff.manage). Envie o array completo — os vínculos anteriores são substituídos.

http

PUT /v1/tours/user/roles/:id/permissions

Payload (Body)

Atributo	Tipo	Obrigatório	Descrição
`permissionIds`	`number[]`	Sim	IDs das permissões a vincular ao papel.

Exemplo de Requisição

bash

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

Respostas

204 No Content

Permissões atualizadas com sucesso.

422 Unprocessable Entity

Ocorre quando alguma permissão não existe no catálogo.

403 Forbidden

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

Remover Papel

Remove um papel via soft delete (exige permissão staff.manage).

http

DELETE /v1/tours/user/roles/: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).

Endpoints — Catálogo de Permissões

O catálogo é global e já vem semeado com as 29 permissões do módulo. As consultas (index, show, list) servem para montar telas de composição de papéis; as mutações exigem a permissão settings.manage e permitem estender o catálogo.

Listar Permissões

Lista as permissões do catálogo, com paginação, busca e filtros.

http

GET /v1/tours/user/permissions

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, padrão: 25).
`search`	`string`	Não	Busca por código ou descrição (máx. 150 caracteres).
`category`	`string`	Não	Filtra por categoria (máx. 50 caracteres).
`orderBy`	`enum`	Não	`id`, `code` ou `category` (padrão: `id`).
`orderDirection`	`enum`	Não	`asc` ou `desc` (padrão: `desc`).

Exemplo de Requisição

bash

curl -X GET "https://api.us.basis.tavares.in/v1/tours/user/permissions?category=financeiro" \
  -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 permissões no formato meta/data.

json

{
  "meta": {
    "currentPage": 1,
    "perPage": 10
  },
  "data": [
    {
      "id": 29,
      "code": "audit.read",
      "category": "admin",
      "description": "Consultar trilha de auditoria"
    },
    {
      "id": 28,
      "code": "settings.manage",
      "category": "admin",
      "description": "Configurar tour, impostos e taxas"
    },
    {
      "id": 27,
      "code": "staff.manage",
      "category": "admin",
      "description": "Gerenciar usuários e papéis"
    }
  ]
}

Criar Permissão

Adiciona uma permissão ao catálogo global (exige permissão settings.manage).

http

POST /v1/tours/user/permissions

Payload (Body)

Atributo	Tipo	Obrigatório	Descrição
`code`	`string`	Sim	Código único no catálogo (máx. 100 caracteres).
`category`	`string`	Sim	Categoria (máx. 50 caracteres).
`description`	`string`	Sim	Descrição (máx. 255 caracteres).

Exemplo de Requisição

bash

curl -X POST "https://api.us.basis.tavares.in/v1/tours/user/permissions" \
  -H "X-Tour-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "demo.docs",
    "category": "docs",
    "description": "Permissão de demonstração da documentação"
  }'

Respostas

201 Created

Retorna o ID da permissão criada.

json

{
  "id": 33
}

422 Unprocessable Entity

Ocorre quando o código já existe no catálogo ou o payload é inválido.

403 Forbidden

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

Retorna as permissões em formato simplificado (value/label com o código), ideal para selects na composição de papéis.

http

GET /v1/tours/user/permissions/list

Aceita search e category como filtros opcionais de query.

Exemplo de Requisição

bash

curl -X GET "https://api.us.basis.tavares.in/v1/tours/user/permissions/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 as permissões.

json

[
  {
    "value": 29,
    "label": "audit.read"
  },
  {
    "value": 13,
    "label": "bill.issue"
  },
  {
    "value": 14,
    "label": "bill.split"
  },
  {
    "value": 17,
    "label": "cash.open_close"
  }
]

Obter Permissão por ID

Recupera os detalhes de uma permissão do catálogo.

http

GET /v1/tours/user/permissions/:id

Parâmetros de Rota

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

Respostas

200 OK

Retorna a permissão.

json

{
  "id": 33,
  "code": "demo.docs",
  "category": "docs",
  "description": "Permissão de demonstração da documentação"
}

404 Not Found

Ocorre quando a permissão não existe no catálogo.

Atualizar Permissão

Atualiza código, categoria ou descrição de uma permissão (exige permissão settings.manage).

http

PUT /v1/tours/user/permissions/:id

Payload (Body)

Atributo	Tipo	Obrigatório	Descrição
`code`	`string`	Não	Código único no catálogo (máx. 100 caracteres).
`category`	`string`	Não	Categoria (máx. 50 caracteres).
`description`	`string`	Não	Descrição (máx. 255 caracteres).

Respostas

204 No Content

Atualização concluída com sucesso.

422 Unprocessable Entity

Ocorre quando o código informado já pertence a outra permissão do catálogo.

403 Forbidden

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

Remover Permissão

Remove uma permissão do catálogo (exige permissão settings.manage).

http

DELETE /v1/tours/user/permissions/: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 settings.manage (code: FORBIDDEN).

Papéis & Permissões ​

Catálogo de Permissões ​

Endpoints — Papéis ​

Listar Papéis ​

Parâmetros de Query ​

Exemplo de Requisição ​

Respostas ​

Criar Papel ​

Payload (Body) ​

Exemplo de Requisição ​

Respostas ​

Listar para Dropdown ​

Exemplo de Requisição ​

Respostas ​

Obter Papel por ID ​

Parâmetros de Rota ​

Respostas ​

Atualizar Papel ​

Payload (Body) ​

Respostas ​

Atualizar Permissões do Papel ​

Payload (Body) ​

Exemplo de Requisição ​

Respostas ​

Remover Papel ​

Respostas ​

Endpoints — Catálogo de Permissões ​

Listar Permissões ​

Parâmetros de Query ​

Exemplo de Requisição ​

Respostas ​

Criar Permissão ​

Payload (Body) ​

Exemplo de Requisição ​

Respostas ​

Listar para Dropdown ​

Exemplo de Requisição ​

Respostas ​

Obter Permissão por ID ​

Parâmetros de Rota ​

Respostas ​

Atualizar Permissão ​

Payload (Body) ​

Respostas ​

Remover Permissão ​

Respostas ​

Papéis & Permissões

Catálogo de Permissões

Endpoints — Papéis

Listar Papéis

Parâmetros de Query

Exemplo de Requisição

Respostas

Criar Papel

Payload (Body)

Exemplo de Requisição

Respostas

Listar para Dropdown

Exemplo de Requisição

Respostas

Obter Papel por ID

Parâmetros de Rota

Respostas

Atualizar Papel

Payload (Body)

Respostas

Atualizar Permissões do Papel

Payload (Body)

Exemplo de Requisição

Respostas

Remover Papel

Respostas

Endpoints — Catálogo de Permissões

Listar Permissões

Parâmetros de Query

Exemplo de Requisição

Respostas

Criar Permissão

Payload (Body)

Exemplo de Requisição

Respostas

Listar para Dropdown

Exemplo de Requisição

Respostas

Obter Permissão por ID

Parâmetros de Rota

Respostas

Atualizar Permissão

Payload (Body)

Respostas

Remover Permissão

Respostas