Zimun: Appointment Scheduling & Booking Service: Guía de la API de reservas

La Booking API ya está disponible para flujos públicos de programación.

Qué cubre esta guía

• Cómo autenticarte y llamar endpoints de reserva de forma segura.
• Cómo listar servicios, leer disponibilidad y completar el flujo de reserva.
• Cuándo usar Booking API directamente frente a integración MCP.

API de reservas frente a MCP

• Usa Booking API cuando construyas tu propia integración backend/cliente y quieras control HTTP directo.
• Usa MCP cuando tu cliente sea nativo MCP y deba invocar herramientas como list_services y get_availability.
• Ambos caminos están diseñados sobre la misma lógica de reservas y comprobaciones de conflicto.

Si desea un flujo de conversación listo para integrar para la reserva de clientes, revise Agente de chat de reservas.

Autenticación

1. Crea credenciales API en Configuración → Clientes API.
2. Solicita un token en /oauth/token usando credenciales de cliente.
3. Llama a Booking API con Authorization: Bearer <token>.

Scopes usados por los flujos de reserva: org:read, availability:read, appointments:write.

Mapa de endpoints

• GET /api/v1/services - Lista servicios de tu organización.
• GET /api/v1/availability - Consulta los espacios disponibles por servicio y fecha.
• POST /api/v1/appointments/hold - Crea un hold temporal antes de confirmar.
• POST /api/v1/appointments/confirm - Confirma un hold y crea la cita.
• POST /api/v1/appointments/reschedule - Reprogramar una cita existente mediante nombramiento_id.
• POST /api/v1/appointments/cancel - Cancele una cita existente mediante cita_id.

Secuencia recomendada

1. Lista servicios y deja que la persona usuaria elija uno.
2. Obtén disponibilidad para el servicio elegido.
3. Crea un hold para el horario seleccionado.
4. Confirma la reserva con los datos de contacto.
5. Si es necesario, reprograme o cancele más tarde usando nombramiento_id desde su estado de integración.

Notas de fiabilidad

• Usa idempotencia en llamadas create/confirm para evitar duplicados en reintentos.
• Trata los holds como temporales y confirma rápido.
• Gestiona explícitamente respuestas 401/403/404 y de conflicto en la UX del cliente.

Nota de alcance

Las APIs públicas actuales se centran en operaciones de reserva. Las APIs de gestión están previstas para una fase posterior.