Hace poco creé una página web para una masajista autónoma que tiene su propia consulta. Es el tipo de proyecto en el que los requisitos son fáciles de definir, pero en el que es fácil equivocarse si intentas resolverlo todo por tu cuenta: una página de inicio atractiva, un sistema de reservas online que funcione de verdad y una forma de que la propietaria pueda gestionar su agenda y sus tratamientos sin tener que llamarme cada vez que haya algún cambio.
Así es como decidimos utilizar Hapio y por qué nos funcionó bien.
El punto de partida
Mi clienta ya tenía una página de Facebook y aceptaba reservas a través de Messenger. Eso funciona… hasta que deja de hacerlo. Reservas duplicadas, citas olvidadas, tener que responder manualmente a las mismas preguntas sobre precios y disponibilidad. Quería tener su propia página web en la que los clientes pudieran reservar directamente y en la que ella misma pudiera cerrar días, modificar el horario de apertura y añadir nuevos tratamientos por su cuenta.
Lo importante es que ella es masajista, no administradora de sistemas. Todo lo que creamos tiene que tener sentido para alguien que no piense en términos de bases de datos y API.
¿Por qué no creamos nosotros mismos el sistema de reservas?
I podría Hemos creado un sistema de reservas a medida. Laravel, un bookings tabla, lógica para las franjas horarias disponibles, gestión de conflictos, tiempos de espera entre tratamientos, gestión de los días de cierre, vacaciones de verano…
Pero ese es precisamente el tipo de código que parece sencillo en una pizarra y que, en la práctica, se convierte en seis meses de casos extremos. Un único recurso (un terapeuta), horarios de atención recurrentes con excepciones, márgenes de tiempo antes y después de cada sesión, duraciones de sesión diferentes… No es ciencia espacial, pero suponeuna gran cantidadde código que no aporta ningún valor añadido específico a este proyecto en concreto.
De eso se encarga Hapio. Disponemos de una API ya preparada para la disponibilidad, las reservas, los servicios y la programación. Así pude centrarme en lo que realmente importaba del proyecto: una página web atractiva y un proceso de reserva que parecierapropio, y no un sistema de reservas genérico.
La arquitectura por la que nos decantamos
Hemos creado una aplicación sencilla con Laravel que actúa como envoltura de Hapio. Piensa en ello como una «interfaz de usuario + capa de integración», no como un «sistema completo de reservas».
Hapio se encarga de:
- Reservas (crear, consultar, cancelar)
- Servicios/tratamientos (nombre, duración, precio, tiempos de espera)
- Horario habitual (de lunes a domingo)
- Días en los que no se trabaja (días festivos, bajas por enfermedad, etc.)
- Cálculo de las plazas disponibles teniendo en cuenta todo lo anterior
Laravel se encarga de:
- La página de inicio y la interfaz de usuario de reservas (Livewire)
- Panel de administración para consultar el horario, los servicios y el resumen de reservas
- Correo electrónico (confirmación, recordatorio, cancelación; tanto al cliente como al propietario)
- Enlaces de cancelación seguros (firmados con HMAC, para que los clientes no puedan acceder a la reserva de otra persona adivinando el enlace)
- Almacenamiento en caché de las plazas disponibles (Redis)
- Gestión de webhooks cuando cambian los datos de Hapio
La base de datos de Laravel solo contiene, básicamente, usuarios administradores, sesiones y tareas en cola. No se almacenan datos de reservas de forma local. Hapio es la fuente de información oficial.
Me parece lo adecuado para una empresa de este tamaño. Una pequeña base de datos local, una instancia de Redis, nada que mantener que no sea necesario.
El proceso de reserva
El cliente sigue cuatro pasos: elegir tratamiento → elegir hora → rellenar los datos → listo.
Los tratamientos se recuperan de Hapio al cargar la página. Los horarios se recuperan semanalmente; los almacenamos en caché de forma intensiva en Redis, ya que son los datos que generan más tráfico. Una vista semanal en la que el cliente puede consultar hasta doce semanas por adelantado.
Una vez confirmada la reserva:
- La reserva se crea en Hapio
- Los datos del cliente (nombre, teléfono, correo electrónico y mensaje opcional) se guardan como metadatos en la reserva.
- Se genera un enlace de cancelación (firmado con HMAC mediante una clave secreta que controlamos)
- Se envía un correo electrónico al cliente y al propietario
La cancelación se realiza a través del enlace que aparece aquí; no es necesario iniciar sesión. Tenemos una norma de 24 horas: no se puede reservar ni cancelar con menos antelación que esa. La norma se aplica en nuestro código en el momento de la lectura, no en la caché, por lo que funciona de forma coherente incluso si la caché aún no se ha invalidado.
El panel de administración
El propietario inicia sesión y dispone de cuatro pestañas:
- Reservas: futuras y pasadas, con la posibilidad de cancelarlas
- Agenda: haz clic en un día del calendario para abrirlo o cerrarlo
- Horario de apertura: el horario semanal habitual, día a día
- Servicios: añadir, editar y desactivar tratamientos
Todo pasa por la API de Hapio. El panel de administración es, básicamente, una interfaz intuitiva que se superpone a su modelo de datos. Cuando ella modifica el horario de apertura o cierra un día, Hapio envía un webhook, nosotros invalidamos la caché y reconstruyamos los intervalos horarios en segundo plano.
Nos costó un poco de trabajo conseguir que el flujo del webhook fuera robusto —verificación de la firma, idempotencia, recurso a un vaciado completo de la caché si algo sale mal—, pero una vez que estuvo en marcha, mereció la pena. Las plazas disponibles se actualizan rápidamente sin que tengamos que consultar la API.
Lo que funcionó bien
Separación de responsabilidades.No tenemos que ocuparnos de la lógica de las reservas. Hapio se encarga de los conflictos, los márgenes de tiempo y la programación. Nosotros nos ocupamos de la experiencia de usuario y de los aspectos específicos del sitio web.
Webhooks + caché.Las franjas horarias disponibles se almacenan en caché durante 24 horas. Cuando se produce algún cambio en Hapio (una nueva reserva, un cambio en el horario o un nuevo servicio) y se recibe una notificación, invalidamos la caché correspondiente y la actualizamos de nuevo. De este modo, los clientes ven los horarios actualizados sin que tengamos que recuperar toda la información de la API cada vez que se carga una página.
Metadatos de las reservas.Los datos de los clientes se almacenan como metadatos en la reserva de Hapio. No necesitamos una tabla de clientes independiente. Para un negocio unipersonal, eso es suficiente.
Enlaces de cancelación.Enlaces firmados con HMAC en los correos electrónicos de confirmación y recordatorio. El cliente no necesita iniciar sesión ni recordar un número de reserva. Verificamos el token en el servidor antes de permitir la cancelación.
Gestión administrativa sin complicaciones técnicas.La propietaria puede gestionar ella misma su horario y sus servicios. No hace falta que intervenga cuando quiera cerrar un día o añadir un nuevo tratamiento.
Cosas en las que tuvimos que pensar
SDK y gestión de errores.Utilizamos el SDK de PHP de Hapio como dependencia de ruta. En ocasiones, el SDK genera advertencias de PHP que ocultan los mensajes de error reales; por ello, hemos encapsulado las llamadas y suprimido las advertencias para que los errores de la API se muestren correctamente.
La regla de las 24 horas.La regla de negocio «al menos 24 horas antes de la reserva o cancelación» se aplica en nuestro código en el momento de la lectura, no en Hapio. Eso significa que la caché puede contener franjas horarias que no se muestran al cliente; las filtramos al devolver los datos. Sencillo y predecible.
Un recurso, una ubicación.La configuración apunta a una única ubicación y un único recurso (el terapeuta). Si el negocio creciera hasta contar con varios terapeutas o sedes, tendríamos que replantearnos las cosas, pero para la configuración actual es perfecta.
Resumen
Para una pequeña clínica de masajes cuya propietaria tiene que encargarse de todo ella sola, Hapio fue la elección acertada. No creamos un sistema de reservas, sino una página web y una capa de integración que permite acceder a Hapio de una forma que se adapta al negocio.
Laravel + Livewire para la interfaz de usuario y el correo electrónico. Hapio para toda la lógica de reservas. Redis para la caché. Webhooks para mantener la caché sincronizada.
Gracias a Hapio —y a la ayuda de la IA a lo largo del proceso—, le llevó aproximadamente un fin de semana crear toda la página web desde cero hasta convertirla en algo que realmente pudiera empezar a utilizar para su negocio.
No es la arquitectura más compleja que he creado, pero es una de las que me parece más adecuada para el proyecto. Y eso es lo que se busca.
Borrador. Se han omitido intencionadamente las referencias a sitios, lugares o personas concretos.
