Zimun: Appointment Scheduling & Booking Service: Booking API Guide

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 descubrir ubicaciones, listar servicios, leer disponibilidad y completar el flujo de reserva.
• Cuándo usar la Booking API directamente frente a la 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 quieres un flujo conversacional listo para integrar para la reserva de clientes, consulta 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>.

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

Mapa de endpoints

• GET /api/v1/locations - Lista las ubicaciones activas de reserva de tu organización.
• GET /api/v1/services - Lista los servicios de tu organización, incluidos los location_ids.
• GET /api/v1/availability - Lee los huecos disponibles por servicio y fecha, con location_id cuando sea necesario.
• POST /api/v1/appointments/hold - Crea una retención temporal antes de la confirmación, usando el mismo location_id cuando sea necesario.
• POST /api/v1/appointments/confirm - Confirma una retención y crea la cita.
• POST /api/v1/appointments/reschedule - Reprograma una cita existente mediante booking_id.
• POST /api/v1/appointments/cancel - Cancela una cita existente mediante booking_id.

Secuencia recomendada

1. Lista las ubicaciones si la organización puede reservar en más de un lugar.
2. Deja que el usuario elija una ubicación cuando sea necesario.
3. Lista los servicios y conserve solo los que cubren esa ubicación.
4. Obtén la disponibilidad con service_id, date y location_id cuando sea necesario.
5. Crea la retención con el mismo location_id.
6. Confirma la reserva con los datos de contacto.
7. Guarda el booking_id para poder reprogramar o cancelar más tarde.

Notas de fiabilidad

• Usa idempotencia en las llamadas de creación y confirmación para evitar duplicados en los reintentos.
• Trata las retenciones 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.