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 descubrir ubicaciones, 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/locations - Liste las ubicaciones activas de reserva de su organización.
• GET /api/v1/services - Liste los servicios de su organización, incluidos los location_ids.
• GET /api/v1/availability - Lea las franjas disponibles por servicio y fecha, con location_id cuando sea necesario.
• POST /api/v1/appointments/hold - Cree un hold temporal antes de confirmar, usando la misma location_id cuando sea necesario.
• POST /api/v1/appointments/confirm - Confirma un hold y crea la cita.
• POST /api/v1/appointments/reschedule - Reprograme una cita existente mediante booking_id.
• POST /api/v1/appointments/cancel - Cancele una cita existente mediante booking_id.

Secuencia recomendada

1. Liste las ubicaciones si la organización puede reservar en más de un lugar.
2. Permita que el usuario elija una ubicación cuando sea necesario.
3. Liste los servicios y conserve solo los que cubren esa ubicación.
4. Obtenga la disponibilidad con service_id, date y location_id cuando sea necesario.
5. Cree el hold con la misma location_id.
6. Confirma la reserva con los datos de contacto.
7. Guarde la booking_id para poder reprogramar o cancelar más tarde.

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.