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 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 prerreserva temporal antes de la confirmación, usando el mismo location_id cuando sea necesario.
• POST /api/v1/appointments/confirm - Confirma una prerreserva 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.

Reservas de cita (servicios con precio fijo). Una prerreserva o una reserva creada a través de esta interfaz para un servicio o un recurso con precio fijo es una reserva de cita (acuerdo de cita) en el sentido de las Condiciones Generales (Parte C, cláusula 13, apdo. 2), no un contrato sobre el servicio. En ese caso, la respuesta de la prerreserva y la respuesta de la reserva incluyen kind: "reservation", contract: "on_site", el precio en price_cents con price_label, cuyo texto es exactamente «Preis der Organisation, zahlbar vor Ort; Preis und Vertrag werden vor Ort geregelt» (precio de la organización, pagadero en el establecimiento; el precio y el contrato se acuerdan en el establecimiento), y notice con este texto fijo: «Terminreservierung: Mit dieser Reservierung ist noch kein Vertrag über die Leistung geschlossen. Preis der Organisation, zahlbar vor Ort; Preis und Vertrag werden vor Ort geregelt.» (En español: «Reserva de cita: Con esta reserva todavía no se ha celebrado ningún contrato sobre el servicio. Precio de la organización, pagadero en el establecimiento; el precio y el contrato se acuerdan en el establecimiento.») Tu interfaz debe mostrar este aviso al cliente final, a más tardar junto con el resultado de la reserva; es tu obligación conforme a la cláusula 8, apdo. 5, letra c), de la Parte B de las Condiciones Generales. La respuesta de la prerreserva lo incluye para que pueda mostrarse antes de que el cliente final envíe la reserva; una versión en otro idioma debe ser completa y fiel. Zimun no recaba ni documenta por esta interfaz ningún consentimiento del cliente final a disposiciones propias de Zimun, no acepta pagos en línea ni tarjetas y envía a la dirección de correo electrónico facilitada con la reserva una comunicación de reserva de cita, no una confirmación de reserva.

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 prerreserva 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 prerreservas 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.