Agendas e disponibilidade

A agenda (calendar) define quem atende, o fuso horário, a duração, o intervalo entre horários e a capacidade simultânea. Ela é diferente de um agendamento (appointment), que ocupa um horário para um cliente.

O módulo exigido é agendamentos. Use calendars:read para consultar e calendars:write para alterar, com uma oferta de API que permita escrita.

Recurso	Coleção
Agendas	/v1/calendars
Tipos de evento	/v1/calendars/{calendar_id}/event-types
Regras de disponibilidade	/v1/calendars/{calendar_id}/availability
Modelos de disponibilidade	/v1/calendars/{calendar_id}/templates

Cada coleção aceita GET e POST. Acrescente /{id} para GET, PATCH ou DELETE. A exclusão desativa o registro quando ele possui situação ativa. Os campos obrigatórios e limites estão na Referência.

Preparar uma agenda

1. Consulte Usuários e crie a agenda com name e user_id. Defina timezone, duração e capacidade conforme a operação.
2. Cadastre regras com início e fim. recurrence_type aceita weekday, specific_date, date_range e custom_dates.
3. Consulte GET /v1/calendars/{calendar_id}/slots?date=2026-10-20.
4. Crie o Agendamento com a agenda e o horário escolhido.

Regras de maior prioridade prevalecem. Regras empatadas na maior prioridade compõem a janela disponível. A API verifica duração, intervalo, fuso, conflitos e capacidade também no momento de gravar: uma consulta de horários não reserva vaga. Ao editar, use exclude_appointment_id na consulta de slots para desconsiderar apenas o próprio agendamento.

Para aplicar um modelo, use POST /v1/calendars/{calendar_id}/templates/{id}/apply. Feriados são consultados por GET /v1/holidays e GET /v1/holidays/{id} com calendars:read; eles não têm escrita pública.

Agendas que dependem de Pets ou veículos apresentam booking_blocker e não aceitam criação de agendamentos neste escopo. Agendas inativas também bloqueiam reservas. Use Idempotência em todas as escritas.