> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orquena.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Agendamento e calendários

> Decisão pelo scheduling nativo e papel de Cal.com, iCalendar, Google e Microsoft.

# Agendamento e calendários

O agendamento será uma capacidade nativa e uma das primeiras implementações funcionais da Nuvexa.

## Por que será nativo

Agentes de IA precisam de ferramentas seguras para:

* Consultar serviços reais.
* Verificar profissionais e unidades.
* Calcular disponibilidade.
* Criar holds temporários.
* Confirmar agendamentos.
* Reagendar e cancelar.

Essas operações dependem do mesmo tenant, catálogo, políticas, transações e auditoria da plataforma. Um produto externo não será a fonte principal desses dados.

## Entidades principais

```text theme={null}
AvailabilityRule
WorkingPeriod
BreakPeriod
BlockedPeriod
AppointmentHold
Appointment
AppointmentParticipant
AppointmentChange
CancellationPolicy
ReminderSchedule
ExternalCalendarMapping
```

## Fluxo de reserva

```text theme={null}
Consulta de disponibilidade
    ↓
AppointmentHold com expiração
    ↓
Validação final transacional
    ↓
Appointment confirmado
    ↓
Outbox e eventos
    ↓
Calendários, lembretes e mensagens
```

## Regras críticas

* Horários são armazenados em UTC.
* A timezone da organização ou unidade controla interpretação.
* Conflitos são impedidos no backend e no banco.
* Holds possuem expiração e idempotência.
* Confirmar hold expirado falha de forma segura.
* Cancelamentos preservam histórico.
* Preço e duração são copiados como snapshot no momento da confirmação.
* A IA não inventa serviços, profissionais, preços ou horários.

## Lembretes

Scheduling decide **quando** um lembrete é necessário. Um plugin de Notifications decide **como** ele será entregue.

```text theme={null}
Scheduling
    ↓ reminder.requested
Notifications
    ↓
WhatsApp, email ou push provider
```

Isso evita acoplamento com WAHA ou qualquer canal.

## Cal.com e Cal.diy

Cal.com é uma referência madura para bookings, schedules, event types, equipes, organizações e webhooks.

Em 2026, a distribuição comunitária gratuita passou a ser o **Cal.diy**, edição MIT que removeu recursos comerciais e enterprise, incluindo equipes, organizações, insights, workflows e SSO. O próprio projeto não o posiciona como infraestrutura comercial completa para produção.

<Warning>
  Cal.diy não será usado como engine do scheduling da Nuvexa. Ele não cobre as necessidades multi-organização e de equipes da plataforma.
</Warning>

Usos aprovados:

* Pesquisa de UX e contratos de API.
* Comparação de estados de booking.
* Futuro connector para clientes que já usam Cal.com.
* Importação controlada.

## Calendários externos

O calendário interno da Nuvexa permanece fonte da verdade. Conectores futuros poderão publicar ou sincronizar eventos com:

* Google Calendar.
* Microsoft Outlook Calendar.
* Clientes compatíveis com iCalendar.

A primeira direção será **push da Nuvexa para o calendário externo**. Sincronização bidirecional só será liberada após implementar versões, conflitos, tombstones e reconciliação.

## Feed iCalendar

Organizações e profissionais poderão receber URLs privadas `.ics` para assinatura em calendários compatíveis.

Tokens de feed serão revogáveis, armazenados por hash e nunca conterão dados previsíveis do usuário.

## Testes obrigatórios

* Concorrência pelo mesmo horário.
* Mudanças de timezone e horário de verão.
* Serviços com duração e buffers diferentes.
* Bloqueios e intervalos.
* Jornadas que cruzam meia-noite.
* Hold expirando durante confirmação.
* Comandos repetidos.
* Isolamento entre organizações.
* Falhas na sincronização externa.

## Links oficiais

<CardGroup cols={2}>
  <Card title="Cal.com API v2" icon="braces" href="https://cal.com/docs/api-reference/v2/introduction">
    Bookings, schedules, event types e organizações.
  </Card>

  <Card title="Webhooks do Cal.com" icon="webhook" href="https://cal.com/docs/developing/guides/automation/webhooks">
    Eventos para integrações externas.
  </Card>

  <Card title="Cal.com no GitHub" icon="github" href="https://github.com/calcom/cal.com">
    Código, releases e informações do Cal.diy.
  </Card>

  <Card title="RFC 5545 — iCalendar" icon="calendar" href="https://datatracker.ietf.org/doc/html/rfc5545">
    Formato padrão para troca de eventos.
  </Card>
</CardGroup>