Basis

Appearance

Módulo de Tours (Hospitalidade & Lazer) ​

O módulo de Tours é uma plataforma headless completa para hospitalidade, lazer e experiências. Ele cobre a operação inteira de um estabelecimento — pousada, beach club ou operadora de passeios: recursos reserváveis (quartos, camas balinesas, lanchas, equipamentos e serviços), motor de alocação anti double-booking, precificação dinâmica com regras sazonais, CRM de hóspedes, ponto de venda com comandas e KDS, estoque com ficha técnica e o financeiro completo com folio, split de conta e pagamentos manuais.

Cada estabelecimento é uma instância isolada (um tour), com usuários, papéis, catálogo, tarifas e operação próprios. Um workspace pode ter vários estabelecimentos, cada um com regras independentes — fuso, moeda, virada do dia operacional e horários de check-in/check-out.

Por que utilizar este módulo? ​

  • Um único motor para qualquer coisa reservável: quarto, cama de praia, passeio de barco, prancha ou massagem são o mesmo conceito — tipo (o que se vende) e recurso (a unidade física). O mesmo motor atende o quarto exclusivo e os 20 assentos da lancha.
  • Tudo que ocupa recurso vive na mesma tabela: reserva, manutenção, limpeza, bloqueio do proprietário e hold de checkout competem pela mesma agenda — uma manutenção jamais colide com uma reserva.
  • Preço combinado não muda: diárias, consumos e impostos são congelados no momento da venda/lançamento. A tabela pode mudar amanhã; a conta do hóspede de ontem continua auditável.
  • POS offline-first: comandas, pedidos e pagamentos carregam clientRef (UUID gerado no dispositivo) como chave de idempotência — reenviar o mesmo pedido após reconexão não duplica a venda.
  • RBAC granular: 29 permissões agrupadas em papéis por estabelecimento, do recepcionista ao financeiro.

As Duas Áreas do Módulo ​

ÁreaPrefixo das rotasPúblicoGuard
Gestão da instância/user/toursDono da conta (módulo user)user
Staff (equipe)/v1/tours/userRecepção, POS, governança, admintoursUser
  • A gestão da instância cria e configura os estabelecimentos (nome, fuso, moeda, endereço, domínios autorizados) e segue a autenticação da plataforma.
  • A área de staff concentra toda a operação: reservas, tarifas, clientes, POS, estoque, financeiro, governança e administração.

Autenticação e Contexto ​

Identificação da Instância ​

Todas as requisições para os endpoints /v1/tours/** (públicas ou privadas) devem incluir o identificador da instância:

HeaderTipoObrigatórioDescrição
X-Tour-IdUUIDSimO tokenHeader da instância, gerado na criação (ver Gestão da Instância).

Como funciona o X-Tour-Id

O middleware resolve a instância pelo tokenHeader e valida se o domínio (ou IP) de origem está na lista de domínios autorizados do workspace, conforme a configuração allowBy (domain ou ip). Requisições sem o header, com instância inexistente ou com origem não autorizada recebem 401 Unauthorized. Instância ou workspace inativos recebem 503 Service Unavailable.

bash
curl -X GET "https://api.us.basis.tavares.in/v1/tours/user/reservations" \
  -H "X-Tour-Id: 123e4567-e89b-12d3-a456-426614174000" \
  -H "Accept: application/json"

Token de Acesso (Staff) ​

O login da equipe usa e-mail + PIN numérico (4 a 8 dígitos) — pensado para acesso rápido no POS e na recepção:

ContextoEndpoint de loginCredenciais
StaffPOST /v1/tours/user/users/loginemail + pin

Retorna um token Bearer com validade de 30 dias. O logout invalida o token imediatamente. O PIN nunca é armazenado em claro — apenas o hash (scrypt).

HeaderValorDescrição
AuthorizationBearer <token>Token obtido no login do staff.

Resumo dos Headers ​

http
GET /v1/tours/user/reservations
X-Tour-Id: 123e4567-e89b-12d3-a456-426614174000
Authorization: Bearer {token}
Accept: application/json

Controle de Acesso (RBAC por Permissões) ​

O acesso é controlado por papéis (roles) compostos de permissões, ambos por instância. O papel owner é criado no setup com todas as permissões; os demais papéis são montados pelo administrador (ver Papéis & Permissões).

Mutaciones exigem a permissão correspondente — a API responde 403 com code: FORBIDDEN quando falta:

CódigoÁreaCódigoÁrea
reservation.readreservasbill.issuefinanceiro
reservation.writereservasbill.splitfinanceiro
reservation.cancelreservaspayment.recordfinanceiro
reservation.check_inreservaspayment.refundfinanceiro
resource.assignreservascash.open_closefinanceiro
rate.readtarifasreport.financialfinanceiro
rate.writetarifasstock.readestoque
pos.orderposstock.adjustestoque
pos.void_itemposstock.purchaseestoque
pos.discountposcustomer.readcrm
pos.transferposcustomer.writecrm
kds.update_statusposcustomer.document.readcrm
housekeeping.updateoperaçõesstaff.manageadmin
maintenance.manageoperaçõessettings.manageadmin
audit.readadmin

Billing e Limites de Plano ​

Todas as rotas do módulo passam por limite de plano e contabilização de uso. Quando o plano não permite a operação, a API responde 402 Payment Required com um dos seguintes códigos:

CodeSignificado
PENDING_INVOICESExistem faturas pendentes no workspace.
PLAN_REQUIREDO workspace não possui um plano ativo para o módulo.
USAGE_LIMIT_EXCEEDEDO limite de uso do plano foi atingido.

Convenções da API ​

  • Paginação: parâmetros page/perPage (máx. 100) com resposta no formato { "meta": { "currentPage", "perPage" }, "data": [...] }.
  • Listas para dropdown: endpoints GET .../list retornam [{ "value", "label" }], com search opcional.
  • Ordenação: orderBy (campos permitidos por recurso) + orderDirection (asc/desc).
  • Soft delete: registros removidos não aparecem em consultas. Livros-razão (pagamentos, lançamentos, movimentos de estoque) não usam soft delete — correções são feitas por estorno/void, nunca por remoção.
  • Erros de validação: 422 Unprocessable Entity com errors: [{ "message", "rule", "field" }].
  • Datas e horários: sempre em ISO 8601; filtros de período usam YYYY-MM-DD; janelas de horário usam HH:mm. Timestamps são gravados em UTC — a conversão para o fuso do estabelecimento (timezone da instância) acontece na apresentação.
  • Dia da semana: dayOfWeek segue a convenção JS/luxon — 0 = domingo … 6 = sábado.
  • Dinheiro: valores monetários em decimal com 2 casas, na moeda da instância (currency).
  • Idempotência: operações sensíveis à reconexão (pedidos, pagamentos, comandas) aceitam clientRef (UUID gerado no dispositivo).
  • Rate limit: 3000 req/min para o módulo; as rotas de gestão da instância (/user/tours) seguem o throttle do módulo user (100 req/min).

Códigos de Erro de Negócio ​

CodeStatusSignificado
FORBIDDEN403O usuário não possui a permissão exigida.

Próximos Passos ​