API: Booking (Reservas y clases)

La API de Booking permite que tu sistema refleje el calendario de clases de la sucursal directamente en la aplicación de TotalPass. A través de ella, no solo gestionas la creación de las clases, sino también el control de lugares (slots), mapas de posiciones y la aprobación de reservas.

Mira a continuación el flujo completo de implementación:

1. Autenticación y Generación de Token

Al igual que en la API de Check-in, el proceso comienza autenticando a la sucursal.

⚠️ Atención Crítica: A pesar de que las credenciales (partner_api_key y place_api_key) son exactamente las mismas, ¡los endpoints de autenticación son diferentes para cada API!

• Utiliza el endpoint de autenticación de Booking para realizar la vinculación.

• La respuesta devolverá los planes activos de la sucursal en TotalPass y el token de acceso.

• Este token expira en 24 horas. Tu sistema debe estar preparado para generar un nuevo token siempre que vaya a consumir los demás endpoints.

2. Configuración de la Sucursal y Webhooks

Para que las reservas realizadas por los usuarios en la app lleguen a tu sistema, necesitas configurar la sucursal y la URL de recepción.

• Registro del Webhook: Registra tu URL de recepción a través del endpoint de registro de webhook. Puedes usar el mismo enlace para todas las sucursales, siempre que tu código identifique el origen mediante las credenciales.

• Confirmación de Reservas (Recomendado): Recomendamos fuertemente habilitar la funcionalidad de "confirmación de reservas" en todas las sucursales autenticadas para garantizar la sincronización.

• Aprobación o Rechazo: Al recibir una reserva, tu sistema puede aprobarla o rechazarla. En caso de optar por rechazarla, es obligatorio devolver a TotalPass el campo "reason" indicando el motivo dentro de los estándares previstos en la documentación técnica. Esta información de rechazo también debe quedar visible para tu cliente (la sucursal) dentro del panel de tu ERP.

3. Creación de Clases (Eventos) y Gestión de Lugares (Slots)

Con el webhook configurado, ya puedes enviar el calendario de clases a la app de TotalPass.

• Crear Clases: Utiliza el endpoint de creación de evento individual. Presta mucha atención a los campos obligatorios, como plan y zona horaria; enviarlos en blanco o de forma incorrecta causará fallas en la reserva del usuario.

• Gestión de Lugares Externos (Sincronización): Al crear una clase, defines el número de lugares disponibles (slots). Si estos lugares se comparten con usuarios externos a TotalPass, tu ERP debe avisarnos cada vez que un lugar sea ocupado externamente. Utiliza el endpoint de update event occurrence slots para actualizar los lugares disponibles y evitar el overbooking (sobrecupo).

• Reglas de Modificación y Cancelación de Clases:

  • No es posible modificar el horario (startTime) o la fecha (eventDate) de una clase ya creada.

  • Flujo de reprogramación: Para cambiar el horario de una clase, tu sistema debe: 1) Crear una nueva clase con el horario correcto; 2) Cancelar la anterior vía PUT /partner/event-occurrence/{occurrenceUuid} definiendo isCancelled: true (para notificar a los usuarios); 3) Finalmente, eliminar la antigua vía DELETE.

  • Eliminación: Al eliminar una clase que ya tiene reservas, TotalPass cancelará las reservas automáticamente y enviará una notificación Push/Correo electrónico a los usuarios.

4. Mapas de Posiciones (Seat Maps)

Si la sucursal utiliza bicicletas numeradas, sacos de boxeo o posiciones fijas, puedes utilizar nuestra funcionalidad de Seat Maps. Su uso no es obligatorio.

• Si decides utilizarlo, debes crear el mapa a través del endpoint de creación de mapa de posiciones antes de crear la clase.

• Toma el ID devuelto y envíalo al momento de la creación de la clase.

• Cada mapa pertenece únicamente a una sucursal específica (la sucursal cuyo token fue utilizado para crearlo).

• Siempre será posible hacer alteraciones en un mapa de posiciones ya existente, pero es importante entender las consecuencias de los cambios (descritas en la documentación técnica).

Observaciones Finales sobre las APIs de TotalPass

• Acuerdo de Adhesión: Para obtener el acuerdo e iniciar la integración, envía el Nombre de tu ERP, RFC y el nombre de tu representante legal al correo tp.integraciones@totalpass.com.mx

• Credenciales de Acceso: Las claves de acceso (partner_api_key y place_api_key) son exactamente las mismas tanto para la API de Check-in como para la API de Booking. Sin embargo, los endpoints son diferentes.

• Confidencialidad: Tu partner_api_key es proporcionada por TotalPass, es estrictamente confidencial y nunca debe ser solicitada a tus clientes.

• Clave del Cliente: La place_api_key es generada y proporcionada por el propio cliente, y se obtiene directamente en el Portal de Academias y Aliados de TotalPass en la pestaña "Integraciones".