BellSera — Gestão de Agendamentos de Spa e Salão para NexoPOS

A BellSera adiciona ao NexoPOS o agendamento de consultas de serviço e as operações diárias de atendimento. Ela conecta o catálogo de produtos, clientes, pedidos, equipe, salas, pagamentos e POS para que uma empresa de serviços possa gerenciar reservas agendadas e clientes de atendimento imediato a partir de um único sistema.

O módulo inclui:

• Uma página pública de agendamento self-service.
• Tipos de pedidos POS por reserva e por atendimento presencial.
• Um calendário de agendamentos e uma lista de agendamentos.
• Gestão de disponibilidade de equipe e de salas.
• Filas de execução de vários serviços com temporizadores persistentes.
• Ferramentas de presença, pagamento, troca de equipe, avaliação e relatórios.
• Mensagens SMS opcionais de confirmação, lembrete e pesquisa através do NsSMS.

Informações do módulo

Visão geral do recurso

Reserva online pública

A página pública de reservas permite que um cliente:

1. Navegue pelas categorias de serviços e pelos serviços disponíveis.
2. Revise a imagem, a descrição, a duração, o preço e a exigência de pagamento de cada serviço.
3. Adicione um ou mais serviços a um carrinho de reservas.
4. Escolha qualquer membro da equipe disponível ou solicite um membro específico e elegível.
5. Escolha um quarto disponível quando a atribuição de quartos estiver ativada.
6. Selecione uma data e pesquise por um horário de consulta válido.
7. Digite o nome, o endereço de e-mail, o número de telefone e as observações deles.
8. Envie o pedido de marcação e receba uma referência de reserva única.

Os horários disponíveis respeitam:

• Dias úteis e horários de funcionamento configurados.
• O intervalo do slot.
• Aviso mínimo de reserva.
• A janela máxima de reserva antecipada.
• Duração do serviço e buffers antes/depois.
• Funções da equipe atribuídas a cada categoria de serviço.
• Compromissos existentes que bloqueiam o pessoal, a sala ou o recurso selecionado.
• O status operacional atual da equipe e das salas.

O checkout público cria ou reutiliza um cliente do NexoPOS, cria um pedido do NexoPOS vinculado e armazena o agendamento e suas linhas de serviço individuais.

Nota de pagamento: a página pública calcula se não é necessário pagamento, se é necessário um pagamento parcial ou se é necessário o pagamento integral. Registra esse valor como devido e exibe as instruções de pagamento manual configuradas. Ela não processa diretamente um pagamento online.

Os endpoints de disponibilidade pública e de checkout são limitados por taxa para reduzir abusos.

Configuração do catálogo de serviços

A BellSera estende o catálogo do NexoPOS em vez de manter um banco de dados de produtos separado.

Em Configurações do BellSera → Catálogo, os administradores podem definir:

• Categorias de Serviço — os produtos nessas categorias podem se tornar serviços agendáveis.
• Categorias de Produtos Vendáveis — produtos de varejo regulares ou complementos opcionais de agendamento.
• Atribuição de sala — se uma sala deve ser selecionada para serviços de agendamento no PDV.

Uma categoria não pode ser, ao mesmo tempo, uma categoria de serviço e uma categoria vendável.

Cada produto tem uma guia de configuração de Consultas com:

• Serviço disponível para reserva ativado/desativado.
• Duração do serviço em minutos.
• Tempo de espera antes do serviço.
• Tempo de espera após o serviço.
• Requisito de pagamento: nenhum, depósito parcial ou pagamento integral.
• Tipo de depósito: valor fixo ou percentagem.
• Valor do depósito.

Um serviço deve ter uma unidade de venda configurada antes de poder ser agendado.

Inscrição de funcionários e elegibilidade para serviços

A equipe de agendamento é baseada em usuários e funções normais do NexoPOS.

Os administradores configuram:

• As funções do NexoPOS cujos utilizadores ativos podem tornar-se pessoal de atendimento.
• As funções permitidas para executar serviços em cada categoria de serviço.
• O nome de exibição de cada trabalhador.
• Se o trabalhador está habilitado para agendamentos.
• A disponibilidade atual do trabalhador: disponível, indisponível ou ocupado.

Os perfis dos trabalhadores são criados automaticamente a partir das funções configuradas. Eles não podem ser criados ou excluídos manualmente na tela de equipe de atendimento; desative um perfil de trabalhador em vez disso.

Apenas trabalhadores ativos e disponíveis com uma função elegível para uma categoria de serviço são oferecidos para novas reservas. Iniciar um serviço marca o trabalhador como ocupado, e concluir ou interromper o último serviço ativo do trabalhador o torna novamente disponível.

Gestão de salas

As salas podem ser criadas e gerenciadas em BellSera → Salas.

Cada sala suporta:

• Nome.
• Miniatura.
• Descrição.
• Preço extra.
• Status de disponibilidade: disponível, indisponível ou ocupado.

Apenas os quartos disponíveis podem ser atribuídos. Um quarto pode estar livre ou adicionar uma taxa ao serviço.

No ponto de venda (POS), é cobrada uma taxa de sala uma vez por linha de serviço:

total da linha = (preço unitário do serviço × quantidade − desconto) + taxa do quarto

A taxa do quarto não é multiplicada pela quantidade de serviço. Os quartos também podem ser retornados manualmente ao estado disponível com Definir quarto como livre.

Reservas e entradas sem marcação (walk-ins)

O módulo registra dois tipos de pedidos do NexoPOS:

Quando qualquer um dos tipos de pedido estiver ativado nas configurações de tipo de pedido do NexoPOS POS, a BellSera adiciona o fluxo de agendamento ao POS:

• Solicita ao caixa que escolha Reserva ou Atendimento presencial após a redefinição do carrinho.
• Reconhece produtos configurados como serviços por agendamento.
• Seleciona uma sala disponível quando a atribuição de salas estiver ativada.
• Seleciona o pessoal elegível que está disponível no horário do serviço.
• Exibe a equipe atribuída e as informações da sala em cada linha de carrinho de serviço.
• Permite que funcionários e atribuições de salas sejam alterados a partir do carrinho.
• Gerencia quantidades reservando um trabalhador para cada ocorrência de serviço agendada.
• Revalida as informações da reserva antes do pagamento quando o carrinho de serviços é alterado.
• Impede que um pedido pago/não em espera use um trabalhador, sala ou horário indisponível.
• Preserva os campos do agendamento quando um pedido é mantido, editado e recarregado.
• Cria automaticamente um agendamento vinculado após a criação ou atualização do pedido no NexoPOS.

O cabeçalho do PDV também inclui um botão Consultas que abre o calendário em tela cheia e a interface de operações de serviços sem sair do PDV.

Painel de gerenciamento de consultas

O menu do painel do BellSera fornece:

• Calendário
• Consultas
• Criar agendamento
• Salas
• Disponibilidade da Equipa
• Desempenho dos Funcionários
• Configurações do BellSera

A lista de compromissos permite criar, editar, excluir e excluir em lote registros de compromissos de acordo com as permissões do usuário atual.

Uma consulta criada manualmente pode incluir:

• Uma referência gerada ou personalizada.
• Data e hora de início e de término.
• Status e origem da consulta.
• Funcionário ou sala designados.
• Nome do cliente, endereço de e-mail e número de telefone.
• Notas internas.

O agendamento manual rejeita conflitos de equipe ou de sala. Pelo menos um membro da equipe ou uma sala deve ser atribuído.

Operações de calendário e de dia

O calendário exibe reservas agendadas e atendimentos sem agendamento (walk-ins) e fornece uma visão operacional detalhada para cada consulta.

Os operadores podem:

• Navegue pelo calendário mensal e abra todos os compromissos de um dia.
• Distinguir reservas de entradas sem marcação.
• Revise as informações do cliente, do serviço, da equipe, do quarto, do pedido e do pagamento.
• Alterar o status do ciclo de vida da consulta.
• Registrar a presença e uma nota de presença.
• Abra a guia de pagamento do pedido NexoPOS vinculada para adicionar um pagamento quando houver saldo restante.
• Abra um serviço individual para iniciar, monitorar, concluir ou interromper.
• Monitore todos os serviços atualmente em execução no hub de serviços ativos.

Os status do ciclo de vida de um agendamento são:

• pagamento_pendente
• aguardando confirmação
• confirmado
• feito o check-in
• concluído
• cancelado
• não comparecimento
• expirado

A presença é monitorada de forma independente como:

• esperado
• chegou
• tarde
• não compareceu
• esquerda

A presença e o status do ciclo de vida são sincronizados de forma suave. Por exemplo, ao marcar um cliente confirmado como “chegou”, a marcação verifica a consulta, enquanto uma atualização de presença de “não compareceu” pode marcar uma consulta aberta como “não compareceu”.

As reservas agendadas devem ser marcadas como Chegada ou Atrasada antes que um serviço possa começar. Os atendimentos sem agendamento podem começar imediatamente.

Execução de serviços, temporizadores e filas

Cada linha de serviço tem seu próprio estado operacional:

• pendente
• pronto
• em progresso
• concluído
• incompleto
• cancelado

O primeiro serviço disponível é promovido para Pronto. Os operadores podem então:

• Inicie o serviço pronto.
• Siga um temporizador de tempo decorrido/contagem regressiva com base na duração do serviço.
• Feche e reabra o cronômetro sem interromper o serviço.
• Conclua o serviço com sucesso.
• Interrompa o serviço por estar incompleto.
• Reinicie um serviço incompleto.
• Inicie o próximo serviço pronto.
• Reorganize os serviços pendentes, prontos e incompletos com arrastar e soltar ou controles de seta.

Serviços em andamento, concluídos e cancelados ficam fixos e não podem ser reordenados.

Iniciar um serviço marca o trabalhador e a sala atribuídos como ocupados. Concluir ou interromper o serviço libera esses recursos quando eles não estiverem sendo usados por outro serviço em execução.

O calendário consulta o servidor para serviços ativos e destaca os serviços que atingiram a duração esperada.

Um trabalho de segurança por hora pode interromper automaticamente os serviços que permaneceram em andamento por mais tempo do que o limite de ociosidade configurado. Defina Service Idle Auto-Stop como 0 para desativar esse comportamento.

Troca de equipe

Os serviços elegíveis podem ser atribuídos a outro trabalhador disponível.

O módulo:

• Mostra apenas os trabalhadores elegíveis para a categoria de serviço e gratuitos para a janela de serviço.
• Requer um motivo para a troca.
• Interrompe um serviço em andamento como incompleto antes de alternar.
• Liberta o trabalhador anterior quando apropriado.
• Registra uma entrada de auditoria contendo o trabalhador anterior, o novo trabalhador, o motivo, o estado do serviço e o horário da troca.
• Contagens de serviços transferidos em relatórios de desempenho de funcionários.

Avaliações e pesquisas com clientes

Os serviços concluídos podem receber uma classificação de 1 a 5.

As avaliações podem ser inseridas:

• Por um operador autorizado na tela de operações do serviço.
• Pelo cliente por meio de um link de pesquisa pública exclusivo enviado por SMS.

Cada link de pesquisa pertence a um serviço concluído e só pode ser usado enquanto esse serviço permanecer elegível para avaliação. Depois de enviado, a avaliação e o carimbo de data/hora são armazenados no item do agendamento.

Relatórios de desempenho dos funcionários

A página de Desempenho dos Funcionários aceita um intervalo de datas e relata o seguinte por trabalhador e como totais:

• Serviços iniciados.
• Serviços concluídos.
• Serviços interrompidos por estarem incompletos.
• Serviços desativados.
• Número de serviços avaliados.
• Avaliação média.
• Taxa de conclusão.

Por padrão, o relatório abrange o início do mês atual até hoje.

Notificações SMS opcionais

A entrega de SMS é uma integração flexível com o módulo opcional NsSMS. A falta ou a falha na entrega de SMS nunca bloqueia um fluxo de trabalho de agendamento.

Quando o NsSMS é instalado, ativado e configurado com um provedor, a BellSera pode enviar:

• Uma confirmação quando um agendamento muda pela primeira vez para confirmado.
• Um lembrete antes de uma consulta confirmada.
• Um link de pesquisa exclusivo quando um serviço é concluído.

As opções de antecedência para o lembrete são 1, 3, 6, 12 ou 24 horas.

Os modelos suportam estas tags:

#customer_name# #customer_phone# #appointment_reference# #starts_at# #ends_at# #service_name# #staff_name# #room_name# #store_name# #survey_url#

As mensagens de confirmação, lembrete e pesquisa são enviadas no máximo uma vez para o respectivo registro.

Lista de verificação de configuração

Use esta ordem ao configurar uma nova instalação:

1. Ative o módulo NsAppointments.
2. Abra as Configurações do BellSera → Catálogo e selecione as categorias de serviço e de itens vendáveis.
3. Edite cada produto de serviço e configure a guia Consultas.
4. Selecione as funções do NexoPOS que devem criar a equipe de atendimento.
5. Edite cada categoria de serviço e atribua as funções que podem executá-la.
6. Revise os perfis de trabalhadores gerados em Disponibilidade de Funcionários.
7. Crie salas e habilite a atribuição de salas se o negócio usar salas.
8. Configure os dias úteis, horários, intervalo de agendamento, antecedência e janela de reserva.
9. Ativar reservas e/ou atendimento sem agendamento nas configurações do tipo de pedido no NexoPOS.
10. Opcionalmente, instale e configure o NsSMS e, em seguida, personalize os modelos de SMS de agendamento.
11. Garanta que o agendador do Laravel e o worker da fila estejam em execução, se forem necessários lembretes de SMS ou a parada automática por inatividade.

Referência de configurações

Catálogo

Equipe

Reserva

SMS

Permissões

As migrações do módulo atribuem todas as permissões do BellSera às funções de Administrador do NexoPOS e Administrador da Loja.

As rotas do servidor aplicam essas permissões; a visibilidade do menu não é o limite de segurança.

Automação agendada

O módulo contribui com dois trabalhos agendados:

Ambos os trabalhos implementam o contrato de job em fila do Laravel. As implantações em produção que usam esses recursos devem executar o agendador NexoPOS/Laravel e um worker de fila.

Dados de demonstração

A tela de redefinição do NexoPOS inclui um modo de demonstração de Agendamentos de Spa. Ele provisiona:

• Categorias de serviços e varejo orientadas para spa.
• Produtos de serviços reserváveis com duração, intervalos, preços e depósitos.
• Funções da equipe de marcação de consultas.
• Clientes de demonstração.
• Quartos com imagens e preços.
• Agendamentos adequados para o spa de amostra.

Aviso: esta opção executa uma redefinição suave do NexoPOS antes de carregar a demonstração. Use-a apenas quando a redefinição dos dados da aplicação for intencional.

Modelo de dados principal

A BellSera armazena os dados do seu domínio nestas tabelas:

O módulo também adiciona campos de agendamento aos pedidos do NexoPOS e aos produtos dos pedidos, para que as atribuições do PDV permaneçam ao salvar, colocar em espera, editar e recarregar o pedido.

A superfície HTTP

Páginas públicas

API pública

Todos os caminhos de API estão sob /api/ns-appointments/public.

Os APIs do painel autenticado, do POS, das configurações e dos relatórios são definidos em Routes/api.php e protegidos pelas permissões do BellSera.

Layout da fonte

O projeto/diretório independente não faz parte das entradas de ativos do módulo NexoPOS em execução. O frontend do módulo ativo é construído a partir de Resources/ts/ usando o arquivo raiz vite.config.js.

Desenvolvimento

Execute um teste de módulo focado:

php artisan test --compact modules/NsAppointments/Tests/Frontend/PublicBookingFlowTest.php

Outros testes de funcionalidades em modules/NsAppointments/Tests/Frontend abrangem:

• Reservas públicas e verificações rigorosas de disponibilidade.
• Criação de pedidos POS e campos de agendamento do pedido-produto persistidos.
• Comportamento do calendário e presença.
• Atribuição de quartos e categoria/equipe.
• Filas de serviço, temporizadores, alternância de equipe, avaliações e relatórios.
• Configurações de SMS, lembretes e pesquisas.
• Permissões e definições de demonstração.

Construa o frontend do módulo:

npm run build -- --config modules/NsAppointments/vite.config.js

Os pontos de entrada do Vite são:

• Recursos/ts/pos.ts
• Recursos/ts/booking.ts
• Recursos/ts/calendar.ts
• Recursos/ts/desempenho-de-funcionários.ts
• Recursos/ts/settings.ts
• Recursos/ts/survey.ts

Os ativos compilados são gravados em Public/build e carregados por meio das diretivas de ativos do módulo NexoPOS.