API de Calendario y Citas

El módulo de Calendario permite agendar citas (reuniones, demos, soporte) vinculadas a un contacto, un agente y opcionalmente una conversación o una oportunidad del CRM. La API expone el mismo motor que usan los enlaces de reserva públicos.

Requisitos

• Token Bearer del workspace.
• Un calendar_id existente (GET /api/v1/calendar/calendars) y, si aplica, un service_id (GET /api/v1/calendar/services).

Endpoints principales

• GET/POST /api/v1/calendar/calendars — calendarios del workspace (uno por agente o recurso).
• GET/POST /api/v1/calendar/services — tipos de servicio/duración (ej: "Demo 30 min").
• GET /api/v1/calendar/slots — horarios disponibles para un calendario/servicio en un rango de fechas.
• GET/POST /api/v1/calendar/appointments — listar o crear citas.
• PUT /api/v1/calendar/appointments/{id} — reprogramar.
• POST /api/v1/calendar/appointments/{id}/cancel — cancelar.
• GET/POST /api/v1/calendar/booking-links — enlaces públicos de auto-reserva.

Campos para crear una cita

{
  "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 de Omnifox",
  "notes": "Cliente interesado en el módulo CRM"
}

Solo calendar_id y starts_at son obligatorios; si mandás service_id, la duración se calcula sola.

Ejemplo: consultar horarios libres 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 TU_TOKEN"

Consejos

• Siempre consultá /slots antes de POST /appointments para evitar choques de horario; el endpoint de creación igual valida disponibilidad server-side.
• Vinculá deal_id o conversation_id a la cita para que quede trazada en el historial del contacto y en la línea de tiempo del CRM.

Solución de problemas

• 422 al crear la cita: el rango starts_at/ends_at se solapa con otra cita del mismo calendario.
• El slot aparecía libre pero la creación falla: puede haberse reservado entre la consulta y el envío; volvé a pedir /slots.
• La cita no muestra el contacto: confirmá que contact_id corresponde al workspace correcto.