API de Calendário e Agendamentos

O módulo de Calendário permite agendar compromissos (reuniões, demos, atendimentos) vinculados a um contato, um agente e, opcionalmente, uma conversa ou uma oportunidade do CRM. A API expõe o mesmo mecanismo usado pelos links públicos de agendamento.

Requisitos

• Token Bearer do workspace.
• Um calendar_id existente (GET /api/v1/calendar/calendars) e, se aplicável, um service_id (GET /api/v1/calendar/services).

Endpoints principais

• GET/POST /api/v1/calendar/calendars — calendários do workspace (um por agente ou recurso).
• GET/POST /api/v1/calendar/services — tipos de serviço/duração (ex.: "Demo de 30 min").
• GET /api/v1/calendar/slots — horários disponíveis para um calendário/serviço em um intervalo de datas.
• GET/POST /api/v1/calendar/appointments — listar ou criar agendamentos.
• PUT /api/v1/calendar/appointments/{id} — remarcar.
• POST /api/v1/calendar/appointments/{id}/cancel — cancelar.
• GET/POST /api/v1/calendar/booking-links — links públicos de autoagendamento.

Campos para criar um agendamento

{
  "calendar_id": 3,
  "service_id": 7,
  "contact_id": 55,
  "starts_at": "2026-07-20T15:00:00-05:00",
  "ends_at": "2026-07-20T15:30:00-05:00",
  "title": "Demo do Omnifox",
  "notes": "Cliente interessado no módulo de CRM"
}

Apenas calendar_id e starts_at são obrigatórios; se enviar service_id, a duração é calculada automaticamente.

Exemplo: consultar horários livres antes de agendar

curl -X GET "https://app.omnifox.io/api/v1/calendar/slots?calendar_id=3&service_id=7&from=2026-07-20&to=2026-07-22" \
  -H "Authorization: Bearer SEU_TOKEN"

Dicas

• Sempre consulte /slots antes de POST /appointments para evitar choques de horário; o endpoint de criação também valida a disponibilidade no servidor.
• Vincule deal_id ou conversation_id ao agendamento para que fique registrado no histórico do contato e na linha do tempo do CRM.

Solução de problemas

• 422 ao criar o agendamento: o intervalo starts_at/ends_at se sobrepõe a outro compromisso do mesmo calendário.
• O horário parecia livre mas a criação falhou: pode ter sido reservado entre a consulta e o envio; consulte /slots novamente.
• O agendamento não mostra o contato: confirme que contact_id pertence ao workspace correto.