Marcações no FIRO — tipos, modos, estados e fluxos

Uma marcação no FIRO não é uma estrutura rígida. O motor suporta cinco modos de booking, escolhidos por serviço, para cobrir realidades muito diferentes:

Atendimento individual appointment

O modo padrão. Um cliente reserva um slot com um profissional para um serviço. É o caso típico de cabeleireiros, esteticistas, tatuadores, terapeutas, consultores.

Aula / grupo class

Várias pessoas reservam o mesmo slot até ao limite de participantes. Aulas de yoga, pilates, formações, workshops. Cada participante é uma marcação distinta no mesmo horário.

Recurso resource

A marcação prende-se a um recurso — sala, cabine, equipamento — e não obrigatoriamente a um profissional. Útil para ginásios, clínicas com salas partilhadas, espaços de coworking.

Horário fixo fixed_schedule

Sessões recorrentes geradas a partir de uma regra (regra iCal armazenada em recurrence_rule_json) com limite de participantes por sessão. Aulas semanais, séries de tratamentos, programas de várias sessões.

Encomenda de produto product_order

Reservar/comprar produtos sem horário (ex.: um produto a levantar). Cobre casos onde a "marcação" não tem slot temporal mas precisa de existir no fluxo de transações.

Cada marcação atravessa um ciclo de vida controlado. Os estados são:

• Pendente pending — aguarda confirmação manual ou automática.
• Confirmada confirmed — aceite pelo negócio. Bloqueia agenda e dispara lembretes.
• Parcialmente confirmada partially_confirmed — multi-serviço onde alguns itens estão aceites e outros pendentes.
• Check-in checked_in — cliente chegou; pode ser usado em fluxos de recepção.
• Cancelada pelo cliente cancelled_by_customer — distingue auto-cancelamento de cancelamento por iniciativa do negócio.
• Cancelada pelo negócio cancelled_by_business — registada quando a equipa cancela.
• Concluída completed — serviço prestado e fechado.
• Não compareceu no_show — cliente faltou; registo separado para métricas de no-show.

A distinção entre cancelamento por cliente vs. por negócio importa para relatórios, comunicação e políticas de fidelização.

Uma marcação é composta por linhas (BookingItem). Cada linha representa um serviço com início, fim, profissional e preço próprios. Isto permite cenários como:

• Cliente que faz corte com a Joana + brushing com a Maria em sequência.
• Tratamento facial seguido de massagem na mesma marca de tempo.
• Consulta + exame realizados por profissionais diferentes em janelas distintas.

Cada linha tem o seu próprio estado (presente / faltou) e as suas próprias transações de pagamento.

Acompanhantes e participantes

Para serviços em grupo, o motor suporta participant_count (quantos lugares ocupa) e guest_count (acompanhantes que não reservam slot). O cálculo de capacidade respeita ambos.

O motor de disponibilidade calcula slots livres em tempo real a partir de:

• Horário do profissional (por dia da semana).
• Ausências e bloqueios do profissional.
• Marcações existentes nos estados que ocupam agenda.
• Eventos sincronizados do Google Calendar (quando ligado).

Configurações por tenant

• Buffer entre marcações — minutos de margem que ficam reservados depois de cada serviço.
• Antecedência mínima (min_advance_hours) — quanto tempo antes uma reserva pode ser feita. Default 24h, configurável.
• Antecedência máxima (max_advance_days) — quão para a frente o cliente pode reservar.

Endpoints públicos

Há endpoints dedicados (/availability e /booking/availability) que devolvem slots. São consumidos pela página pública de marcação e podem alimentar widgets externos.

Para sessões que repetem com regra (todas as segundas e quartas às 19h, durante 8 semanas, etc.) o FIRO tem FixedSchedule — uma série recorrente com regra iCal.

• Cada série tem um número máximo de participantes por sessão.
• As sessões são geradas a partir da regra em recurrence_rule_json.
• As inscrições ficam ligadas via FixedScheduleBooking.
• Os participantes contam por sessão — desinscrição numa não afecta as outras.

Casos típicos: aulas de pilates por turma, programas de tratamento de 6 sessões, série de aulas privadas com presença obrigatória.

Cada linha de marcação aceita add-ons (BookingItemAddon) — extras com:

• Duração extra (extra_duration_min) que estica o slot reservado.
• Preço próprio que entra no cálculo do total.

Isto permite upsell: tratamento capilar adicional num corte, máscara extra numa estética, sessão estendida numa massagem.

Cada negócio define a sua política. As variáveis relevantes:

• Horas mínimas para cancelar (cancel_min_hours) — abaixo deste limite, o cliente já não consegue cancelar pelo portal.
• Texto da política (cancel_policy_text) — apresentado ao cliente no fluxo de marcação e no portal pessoal.

O cancelamento pode partir do cliente (auto-serviço em /minha-conta) ou do backoffice. Ambos os caminhos registam o estado correcto e disparam comunicação.

Nem tudo entra pela página pública. O backoffice cria marcações manuais com a flag is_manual_booking:

• Walk-in — cliente que apareceu sem marcar; regista-se em segundos para alimentar histórico e relatórios.
• Marcação por telefone — a recepção aceita a chamada e cria a entrada no calendário.
• Bloqueios — marcações em modo class com preço zero servem para bloquear agenda do staff (formações internas, reuniões).

Importação de contactos

A flag is_contact_import distingue marcações criadas em massa via importação, útil em onboarding de tenants que vinham de outra ferramenta.

Todas as alterações relevantes a uma marcação são registadas em BookingChangeLog — quem, o quê e quando. Isto cobre reschedules, mudanças de profissional, alterações de itens e mudanças de estado.

É a base para resolver litígios ("eu não cancelei isso", "esta marcação foi alterada por quem?") e para auditoria interna em equipas grandes.