Módulo de Booking (Agendamentos)

O módulo de Booking é uma solução completa de agendamento headless. Ele permite que um workspace transforme qualquer unidade — a barbearia, a clínica, o consultório — em uma agenda online: catálogo de serviços, profissionais, escala de horários, agendamentos com ciclo de vida completo e um portal onde o próprio cliente marca, remarca e cancela.

Cada unidade é uma instância isolada, com políticas, equipe e agenda próprias. Um workspace com três filiais tem três instâncias, cada uma com regras independentes.

Por que utilizar este módulo?

Antes dos detalhes técnicos, vale entender o que o módulo resolve por design:

• A agenda é o produto, não um CRUD: a grade de horários é calculada de verdade — escala recorrente, exceções, buffers de preparo, capacidade e recursos disputados (a cadeira, a sala) impedem dois agendamentos que brigariam pelo mesmo espaço.
• Preço combinado não muda: nome, preço e duração são congelados no agendamento. A tabela de preços pode subir amanhã; o que foi combinado com aquele cliente permanece.
• Trilha de auditoria: toda transição de status registra quem fez, quando e por quê. Em agendamento, isso vira discussão com o cliente mais cedo ou mais tarde — e sem trilha você não tem resposta.
• Cliente sem conta é cidadão de primeira classe: a recepcionista cadastra por telefone sem senha; se o cliente criar acesso no portal depois, o mesmo cadastro é reaproveitado.

---

As Três Áreas do Módulo

O Booking possui três áreas independentes, cada uma com seu prefixo de rotas e seu contexto de autenticação:

Área	Prefixo das rotas	Público	Guard
Gestão da instância	/user/bookings	Dono da conta (módulo user)	user
Staff (equipe)	/v1/booking/user	Dono, gerente, recepcionista, profissional	bookingUser
Portal do cliente	/v1/booking/customer	Clientes da unidade	bookingCustomer

• A gestão da instância cria e configura as unidades (nome, fuso, políticas de agenda, domínios autorizados) e segue a autenticação da plataforma.
• A área de staff concentra a operação: catálogo, equipe, escalas, clientes, agenda e métricas.
• O portal do cliente expõe catálogo, horários disponíveis e os agendamentos do próprio cliente.

---

Autenticação e Contexto

Identificação da Instância

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

Header	Tipo	Obrigatório	Descrição
X-Booking-Id	UUID	Sim	O tokenHeader da instância, gerado na criação (ver Gestão da Instância).

Como funciona o X-Booking-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.

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

Tokens de Acesso

Staff e cliente possuem tokens e credenciais separados, obtidos em endpoints de login distintos:

Contexto	Endpoint de login	Credenciais
Staff	POST /v1/booking/user/users/login	email + password
Cliente	POST /v1/booking/customer/customers/login (ou register)	email + password

Ambos retornam um token Bearer com validade de 30 dias. O logout invalida o token imediatamente.

Header	Valor	Descrição
Authorization	Bearer <token>	Token obtido no login do staff ou do cliente.

Tokens não são intercambiáveis

Um token de staff não acessa endpoints de cliente e vice-versa. Cada contexto possui seu próprio endpoint de login e sua própria base de credenciais.

Resumo dos Headers

GET /v1/booking/user/appointments
X-Booking-Id: 123e4567-e89b-12d3-a456-426614174000
Authorization: Bearer {token}
Accept: application/json

---

Controle de Acesso (RBAC)

Cada usuário staff tem um papel (role) na instância:

Role	Escopo
owner / manager	Gestão total: catálogo, equipe, escalas, configurações e agenda completa.
receptionist	Cria, edita e cancela agendamentos e gerencia clientes; vê a agenda completa. Não gerencia catálogo nem equipe.
professional	Vê apenas a própria agenda (vínculo via bookingUserId no cadastro do profissional). Não cria agendamentos.
staff	Sem acesso à agenda de outros profissionais — útil para logins operacionais futuros.

Escopo de agenda do professional

Quando o usuário é professional, listagens de agendamentos, agenda e métricas são automaticamente restritas aos atendimentos do profissional vinculado àquele login. Um professional sem vínculo (ou um staff) recebe listas vazias — nunca dados de outros profissionais.

---

Billing e Limites de Plano

Todas as rotas do módulo (públicas e privadas) 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:

Code	Significado
PENDING_INVOICES	Existem faturas pendentes no workspace.
PLAN_REQUIRED	O workspace não possui um plano ativo para o módulo.
USAGE_LIMIT_EXCEEDED	O limite de uso do plano foi atingido.

---

Convenções da API

Os endpoints /v1/booking/** seguem convenções consistentes em todas as áreas:

• 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 — ideais para selects e filtros no frontend.
• Ordenação: orderBy (campos permitidos por recurso) + orderDirection (asc/desc).
• Soft delete: registros removidos não aparecem em nenhuma consulta.
• Erros de validação: 422 Unprocessable Entity com errors: [{ "message", "rule", "field" }] (mensagens em pt/en via i18n).
• Datas e horários: sempre em ISO 8601; filtros de período usam YYYY-MM-DD; escalas usam HH:mm.
• Dia da semana: dayOfWeek segue a convenção JS/luxon — 0 = domingo … 6 = sábado.
• Rate limit: 3000 req/min para o módulo; as rotas de gestão da instância (/user/bookings) seguem o throttle do módulo user (100 req/min).
• Enums principais: status de agendamento (pending, confirmed, canceled, completed, no_show); origem (online, phone, walk_in, admin, api).

---

Códigos de Erro de Negócio

Erros de regra de negócio retornam status 4xx com um code identificador no corpo da resposta:

Code	Status	Significado
FORBIDDEN	403	Papel sem permissão para a ação.
OVERRIDE_WINDOW_REQUIRED	422	Abertura extra (isAvailable: true) sem janela de horário.
ITEMS_REQUIRED	422	Agendamento sem nenhum item.
INVALID_CUSTOMER_IDENTITY	422	Falta identificação: cliente cadastrado ou convidado com nome + contato.
GUEST_BOOKING_NOT_ALLOWED	422	A instância não aceita agendamento sem cadastro.
CUSTOMER_NOT_FOUND	404	Cliente inexistente na instância.
CUSTOMER_BLOCKED	422	Cliente bloqueado para novos agendamentos.
SERVICE_NOT_FOUND	404	Serviço inexistente na instância.
SERVICE_INACTIVE	422	Serviço inativo.
PROFESSIONAL_NOT_FOUND	404	Profissional inexistente na instância.
PROFESSIONAL_INACTIVE	422	Profissional inativo.
PROFESSIONAL_SERVICE_MISMATCH	422	O profissional não executa o serviço informado.
SLOT_UNAVAILABLE	422	Horário em conflito com outro atendimento do profissional.
RESOURCE_UNAVAILABLE	422	Nenhum recurso obrigatório (sala, equipamento) livre no horário.
APPOINTMENT_NOT_FOUND	404	Agendamento inexistente (ou de outro cliente).
INVALID_STATUS_TRANSITION	422	Transição de status não permitida para o estado atual.
CANCELLATION_DEADLINE_EXCEEDED	422	Cancelamento fora do prazo (cancellationDeadlineMinutes).
APPOINTMENT_NOT_STARTED	422	No-show antes do horário do agendamento.
CODE_GENERATION_FAILED	500	Não foi possível gerar o código legível do agendamento.
INVALID_DATE	422	Data inválida no cálculo de horários.

---

Próximos Passos

Agora que você entende a base do módulo, explore as funcionalidades detalhadas:

• Gestão da Instância
• Usuários e Autenticação (Staff)
• Catálogo de Serviços
• Profissionais e Vínculos
• Disponibilidade e Exceções
• Clientes
• Agendamentos
• Métricas
• Portal do Cliente