Agenda

Leitura usa agenda:ler e escrita usa agenda:escrever. A API segue as mesmas regras do app e do agente de IA: horário de trabalho, bloqueios, intervalo e antecedência mínima. O módulo Agenda precisa estar no plano; se o plano perder o módulo, a chave deixa de funcionar na hora.

• Datas e horas sempre com o fuso, como 2026-10-12T14:00:00-03:00 (ou Z). Sem o deslocamento a API recusa, nunca chuta o fuso. As respostas trazem inicio e fim em UTC e inicio_local e fim_local no fuso da agenda.
• Veja os horários livres em GET /disponibilidade (janela de até 62 dias) e marque em POST /compromissos. Duas chamadas ao mesmo tempo para o mesmo horário: uma marca e a outra recebe 409 horario_ocupado, mesmo com muitas chamadas em paralelo.
• Sem agenda_id, o compromisso vai para a primeira agenda com o horário livre. O contato vem de contato_id, conversa_id ou telefone (só um deles). Pelo telefone, o contato é criado se ainda não existir.
• Duração: mande fim ou duracao_min; sem nenhum, vale a duração padrão da agenda.
• Remarcar, cancelar e confirmar têm rota própria. Compromisso cancelado não volta: marque um novo. Cancelar duas vezes é seguro. PATCH marca presença (estado: concluido ou faltou) e edita título, local, link e notas.
• Eventos de webhook: agendamento.criado, agendamento.remarcado (traz também anterior), agendamento.cancelado e agendamento.confirmado. Disparam para qualquer origem: app, agente de IA ou API.
• Fora da API de propósito: apagar agenda, apagar compromisso (só cancelar), encaixe fora do horário, operações em massa e trocar o profissional de uma agenda. Apagar bloqueio existe, um por chamada.
• Não existe cadastro de serviços: cada agenda tem a sua duração padrão (duracao_min).

{
  "agenda_id": "f7233bb7-10b6-49d2-aa3b-8c2e7d88064d",
  "inicio": "2026-10-12T14:00:00-03:00",
  "fim": "2026-10-12T14:45:00-03:00",
  "contato_id": "08054a7f-a752-481e-9915-cf4cf944df39",
  "titulo": "Avaliação",
  "local": "Rua das Flores, 120 - sala 4"
}