Serviços e disponibilidade

Serviços, requisitos com vários recursos, horários e como os slots são calculados.

Serviços

Um serviço é o que o cliente agenda.

Campo	Significado
`duration_min`	Duração do serviço
`step_min`	Grade de início (a cada 15, 30 minutos…)
`buffer_before_min` / `buffer_after_min`	Tempo de preparo ou limpeza bloqueado ao redor do agendamento
`price_cents`, `currency`	Preço que o bot informa (sempre do banco de dados)
`deposit_cents`	Sinal via Pix exigido para confirmar
`lead_time_min`	Antecedência mínima (por exemplo 60 minutos)
`max_advance_days`	Com quanta antecedência máxima o cliente pode agendar
`window_mode`	O slot é uma janela fixa (entregas: 14:00–16:00)
`fulfillment_mode`	`scheduled` (padrão, com horário) ou `queue` (despacho por fila, sem horário fixo)
`intake_form`	JSON Schema de dados extras a coletar (convênio, endereço…)
`requirements`	Quais recursos o serviço precisa ao mesmo tempo

Janela ou despacho: dois modos de cumprimento

Cada serviço define como o agendamento é cumprido (fulfillment_mode):

scheduled (o padrão): o agendamento ocupa um intervalo de tempo conhecido — um horário fixo ou, com window_mode, uma janela (entregas das 14:00 às 16:00, com cota por zona).
queue (despacho, para água, gás ou delivery sob demanda): o agendamento não tem horário fixo — entra na fila de pendências de um entregador. O motor o atribui ao entregador com menos tarefas ativas e cada entregador tem um limite de tarefas ativas por vez, garantido no banco de dados. A fila usa os mesmos estados de um agendamento: pendente → aceita → iniciada → concluída (ou falhou).

Assim, um mesmo negócio de entregas pode oferecer janelas programadas, despacho imediato ou os dois.

Requisitos

Um requisito diz: deste grupo, preciso de tantas unidades. Um serviço pode ter vários; um slot só existe se todos estiverem livres.

{
  "name": "Depilação a laser",
  "duration_min": 45,
  "buffer_after_min": 10,
  "requirements": [
    { "resource_group_id": "grp_professionals", "units": 1 },
    { "resource_group_id": "grp_lasers", "units": 1 },
    { "resource_group_id": "grp_rooms", "units": 1 }
  ]
}

Com duas profissionais e só um laser, o Wagend nunca oferece duas sessões de laser sobrepostas.

Opções avançadas:

units: "party_size" — consome tantas unidades quanto pessoas (restaurantes, aulas).
offset_min / duration_min num requisito — usa um recurso só em parte do serviço (por exemplo o lavatório nos últimos 15 minutos de uma coloração).

Horários

Cada recurso tem um horário: regras semanais no fuso do recurso mais exceções para datas específicas (fechado ou horário especial).

{
  "tz": "America/Sao_Paulo",
  "weekly": { "tue": [["09:00", "19:00"]], "sat": [["08:00", "12:00"], ["13:00", "16:00"]] },
  "overrides": [{ "date": "2026-12-24", "ranges": [["09:00", "13:00"]] }, { "date": "2026-12-25", "closed": true }]
}

Como os slots são calculados

Expandir os horários para o período pedido, no fuso de cada recurso.
Remover agendamentos e pré-reservas ativos (mais os buffers) e bloqueios manuais.
Cortar em slots candidatos conforme duração e grade do serviço.
Aplicar antecedência mínima e máxima, regras de corte e tamanho do grupo.
Cruzar todos os requisitos, testando os membros de cada grupo conforme a estratégia de alocação.
Devolver uma lista curta e ordenada.

Quando não há nada disponível, a resposta traz unavailable_reason (closed, no_staff, no_equipment, no_space, lead_time, max_advance, cutoff, full) para o bot explicar o motivo.