Ver toda la documentación

Guía completa para instalar Maria Bookings Standard y Pro

Maria Bookings App - Software de reservas y citas online

Instala y gestiona Maria Bookings Standard y Pro con pasos de configuración, reservas, herramientas admin, correo, ubicaciones, roles y soporte.

Maria Bookings es una aplicación web de reservas de citas en línea para empresas de servicios. Incluye una página pública de reservas, una página de gestión de reservas, un panel de administración, gestión de servicios y personal, notificaciones por correo electrónico, reglas de reserva, configuración multilingüe y gestión de citas de clientes.

Esta guía cubre tanto Maria Bookings Standard como Maria Bookings Pro.

1. Resumen de ediciones

Maria Bookings Standard

Maria Bookings Standard está diseñado para una sola empresa o sucursal única. Incluye el sistema de reservas principal y todas las herramientas de administración esenciales.

  • Página pública de reservas
  • Página de gestión de reservas del cliente
  • Panel de administración
  • Gestión de citas
  • Gestión de clientes
  • Gestión de servicios
  • Gestión de personal/proveedores
  • Horarios del personal y días libres
  • Notificaciones y plantillas de correo electrónico
  • Reglas de reserva
  • Marca y colores
  • Configuración de idioma y moneda
  • Registros de actividad
  • Cuentas de usuario y acceso por roles
  • Soporte de protección contra bots
  • Soporte de feeds de calendario

Maria Bookings Pro

Maria Bookings Pro incluye todo lo de Standard y añade funciones multisede para empresas en crecimiento con varias sucursales o gestores de sede.

  • Todo lo incluido en Standard
  • Varias sedes
  • Flujo de reserva basado en sede
  • Servicios específicos por sede
  • Asignación de personal específica por sede
  • Rol de gestor (Manager)
  • Acceso del gestor restringido a la sede asignada
  • Estadísticas de rendimiento por sede
  • Detección de problemas de reserva por configuración incompleta de sede/servicio/personal
  • Reserva pública y gestión de administración con reconocimiento de sede

2. Requisitos

  • Node.js 22 LTS o más reciente
  • npm
  • Un entorno de hosting que pueda ejecutar una aplicación Node.js
  • Una base de datos compatible: SQLite, PostgreSQL, MySQL o MariaDB
  • Un dominio o subdominio para uso en producción
  • Credenciales del proveedor de correo electrónico si se requieren notificaciones por correo

Bases de datos compatibles

  • SQLite: Adecuada solo para desarrollo local o hosting en VPS.
  • PostgreSQL: Recomendada para Vercel, Neon, Supabase, Railway y Render.
  • MySQL/MariaDB: Adecuada para Railway, PlanetScale, VPS y otros hosts compatibles con MySQL.

Importante: SQLite no debe usarse en Vercel porque Vercel utiliza un sistema de archivos efímero. Use PostgreSQL para despliegues en Vercel.

3. Archivos del paquete

Después de la compra o compilación, el paquete de la aplicación contiene los archivos de ejecución necesarios para ejecutar Maria Bookings.

Paquete Standard

maria-bookings/

Paquete Pro

maria-bookings-pro/

Use el paquete que corresponda a su licencia. Standard y Pro son compilaciones independientes. Pro no es una versión bloqueada o desactivada de Standard; incluye funcionalidad adicional de sedes y gestores.

4. Instalación

Paso 1: Subir la aplicación

Suba el paquete de Maria Bookings a su servidor o plataforma de hosting.

Para Standard, suba:

maria-bookings

Para Pro, suba:

maria-bookings-pro

Paso 2: Instalar dependencias

Abra una terminal en la carpeta de la aplicación y ejecute:

npm install --omit=dev

Paso 3: Crear variables de entorno

Cree un archivo .env o añada variables de entorno en el panel de su hosting.

Variables obligatorias

PORT=3000
NODE_ENV=production
JWT_SECRET=your-long-random-jwt-secret
SETUP_SECRET=your-long-random-setup-secret

JWT_SECRET se utiliza para las sesiones de inicio de sesión del administrador. Use un valor aleatorio fuerte de al menos 32 caracteres.

SETUP_SECRET protege el asistente de instalación. Debe introducir el mismo valor durante la configuración.

Ejemplo de SQLite

DB_TYPE=sqlite
DB_PATH=./data/appointments.db

Use SQLite solo para desarrollo local o hosting en VPS.

Ejemplo de PostgreSQL

DB_TYPE=postgres
DATABASE_URL=postgresql://user:password@host:5432/dbname?sslmode=require

PostgreSQL se recomienda para Vercel, Neon, Supabase, Railway y Render.

Ejemplo de MySQL/MariaDB

DB_TYPE=mysql
DATABASE_URL=mysql://user:password@host:3306/dbname

Configuración de proxy inverso

Si la aplicación se ejecuta detrás de Nginx, Cloudflare, Railway, Render, Vercel u otro proxy, configure:

TRUST_PROXY=1

Si la aplicación no está detrás de un proxy, configure:

TRUST_PROXY=0

Paso 4: Iniciar la aplicación

Ejecute:

npm start

De forma predeterminada, la aplicación se ejecuta en:

http://localhost:3000

Paso 5: Abrir el asistente de instalación

Visite:

/setup.html

Ejemplo:

https://yourdomain.com/setup.html

Paso 6: Completar la configuración

El asistente de instalación le guía a través de:

  1. Seleccionar o confirmar el tipo de base de datos
  2. Introducir el secreto de instalación
  3. Probar la conexión a la base de datos
  4. Crear la cuenta de administrador
  5. Establecer el nombre del negocio
  6. Seleccionar el idioma del administrador

Las contraseñas de administrador deben ser seguras e incluir:

  • Al menos 10 caracteres
  • Al menos una letra mayúscula
  • Al menos una letra minúscula
  • Al menos un número
  • Al menos un carácter especial

Una vez completada la configuración, la página de instalación se bloquea y la aplicación redirige a los usuarios al panel de administración.

5. URL principales de la aplicación

  • Sitio público: /
  • Página de reservas: /booking.html
  • Página de gestión de reservas: /manage.html
  • Panel de administración: /admin
  • Asistente de instalación: /setup.html

6. Descripción general del panel de administración

El panel de administración es donde los propietarios de negocios y usuarios autorizados gestionan el sistema de reservas.

Panel principal

El panel principal muestra la actividad de reservas, próximas citas, reservas recientes, totales de citas, personal activo, servicios activos y clientes.

Estadísticas

El área de estadísticas proporciona informes sobre citas, ingresos, estado de las reservas, reservas completadas, reservas pendientes y rendimiento del personal.

En Pro, las estadísticas también pueden incluir el rendimiento por sede.

Citas

Use Citas para ver, buscar, filtrar, editar, confirmar, completar, cancelar o eliminar reservas.

Los estados de las citas incluyen:

  • Pendiente
  • Confirmada
  • Completada
  • Cancelada
  • No presentado

Clientes

Use Clientes para ver los registros de clientes, buscar por nombre, correo electrónico o teléfono, y revisar el historial de citas.

Servicios

Use Servicios para crear y gestionar servicios reservables.

Cada servicio puede incluir:

  • Nombre
  • Descripción
  • Duración
  • Precio
  • Categoría
  • Orden de clasificación
  • Estado activo o inactivo

Personal

Use Personal para gestionar proveedores de servicios, miembros del equipo, horarios, asignaciones de servicios, fotos de perfil y días libres.

Cada miembro del personal puede incluir:

  • Nombre
  • Cargo
  • Biografía
  • Foto
  • Correo electrónico
  • Teléfono
  • Servicios asignados
  • Horario semanal
  • Días libres

Plantillas de correo electrónico

Use Plantillas de correo electrónico para personalizar el asunto y el cuerpo de los correos de notificación.

Los tipos de plantillas compatibles incluyen:

  • Correo de nueva reserva al cliente
  • Correo de nueva reserva al proveedor
  • Correo de nueva reserva al administrador
  • Correo de confirmación de reserva al cliente
  • Correo de cancelación al cliente
  • Correo de cancelación al proveedor
  • Correo de cancelación al administrador
  • Correo de recordatorio al cliente
  • Correo de recordatorio al proveedor

Configuración

Use Configuración para definir la identidad del negocio, las reglas públicas de reserva, el idioma, la moneda, la marca, la entrega de correo electrónico, la protección contra bots, el SEO y el comportamiento del sistema.

Registros de actividad

Los registros de actividad guardan las acciones importantes del administrador. Los registros pueden habilitarse o deshabilitarse, y su retención puede configurarse.

Usuarios

Use Usuarios para gestionar las cuentas de inicio de sesión de administradores y personal.

Los administradores tienen acceso completo. Los usuarios de personal pueden restringirse a áreas y permisos específicos.

7. Funciones de Pro

Sedes

Maria Bookings Pro añade una sección de Sedes. Úsela para crear y gestionar sucursales o ubicaciones del negocio.

Cada sede puede incluir:

  • Nombre
  • Slug
  • Dirección
  • Zona horaria
  • Estado

Reservas basadas en sede

En Pro, el flujo de reserva pública incluye un paso de selección de sede. Los clientes eligen una sede antes de seleccionar servicio, personal, fecha y hora.

Servicios por sede

Los servicios pueden ser de toda la organización o específicos de una sede.

  • Servicios de la organización: Compartidos entre sedes.
  • Servicios de la sede: Disponibles solo en una sucursal específica.

Gestores (Managers)

Maria Bookings Pro incluye el rol de Gestor. Los gestores pueden asignarse a una sede y gestionar únicamente los datos permitidos para esa sede.

Según la configuración del administrador, los gestores pueden estar autorizados a crear, editar o eliminar servicios de su propia sede.

Problemas de reserva

Pro incluye la detección de problemas de reserva para ayudar a los administradores a encontrar errores de configuración que puedan ocultar servicios de la reserva pública.

Ejemplos de problemas de reserva incluyen:

  • Una sede no tiene personal
  • Una sede no tiene servicios
  • Un servicio no tiene personal asignado
  • Un servicio de la organización no es reservable en ninguna sede
  • Un servicio solo es reservable en algunas sedes

8. Flujo público de reserva

Flujo de reserva Standard

  1. El cliente abre /booking.html
  2. El cliente selecciona un servicio
  3. El cliente selecciona un miembro del personal o el primer proveedor disponible
  4. El cliente selecciona una fecha y un horario disponible
  5. El cliente introduce nombre, correo electrónico, teléfono y notas
  6. El cliente revisa la reserva
  7. El cliente confirma la reserva
  8. La aplicación muestra un código de referencia

Flujo de reserva Pro

  1. El cliente abre /booking.html
  2. El cliente selecciona una sede
  3. El cliente selecciona un servicio disponible en esa sede
  4. El cliente selecciona un miembro del personal o el primer proveedor disponible
  5. El cliente selecciona una fecha y un horario disponible
  6. El cliente introduce nombre, correo electrónico, teléfono y notas
  7. El cliente revisa la reserva
  8. El cliente confirma la reserva
  9. La aplicación muestra un código de referencia

Las nuevas reservas se crean como pendientes de forma predeterminada. Los administradores o proveedores pueden confirmarlas desde el panel de administración o desde los enlaces de confirmación en el correo electrónico si las notificaciones están habilitadas.

9. Gestión de una reserva como cliente

Los clientes pueden gestionar su propia reserva desde:

/manage.html

Para consultar una reserva, el cliente introduce el código de referencia mostrado después de la reserva.

Para cancelar una reserva, es posible que el cliente deba verificarse usando la dirección de correo electrónico completa o el número de teléfono utilizado durante la reserva.

Las citas completadas no se pueden cancelar en línea.

10. Reglas de reserva

Las reglas de reserva se gestionan desde Admin > Configuración.

Las configuraciones de reserva disponibles incluyen:

  • Zona horaria del negocio
  • Horario laboral de la organización
  • Intervalo de franjas horarias en minutos
  • Aviso mínimo en horas
  • Días máximos de antelación
  • Si se requiere el número de teléfono
  • Etiqueta de personal mostrada en el formulario de reserva
  • Si los clientes pueden elegir un proveedor
  • Configuración de notificaciones por correo electrónico
  • Configuración de correos de recordatorio

Los horarios del personal pueden anular el horario general de la organización. Se pueden añadir días libres para miembros individuales del personal.

11. Configuración de correo electrónico

Maria Bookings admite múltiples proveedores de correo electrónico.

Proveedores de correo electrónico compatibles

  • SMTP
  • Resend
  • SendGrid
  • Amazon SES
  • Mailgun
  • Postmark
  • Webhook

Ejemplo de SMTP

MAIL_PROVIDER=smtp
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_SECURE=false
SMTP_USER=your-smtp-user
SMTP_PASS=your-smtp-password
SMTP_FROM=Appointments <noreply@yourdomain.com>

Ejemplo de Resend

MAIL_PROVIDER=resend
RESEND_API_KEY=re_xxxxxxxx
MAIL_FROM=Appointments <noreply@yourdomain.com>

Ejemplo de SendGrid

MAIL_PROVIDER=sendgrid
SENDGRID_API_KEY=SG.xxxxxxxx
MAIL_FROM=Appointments <noreply@yourdomain.com>

Ejemplo de Amazon SES

MAIL_PROVIDER=ses
AWS_ACCESS_KEY_ID=your-access-key
AWS_SECRET_ACCESS_KEY=your-secret-key
AWS_REGION=eu-north-1
MAIL_FROM=noreply@yourdomain.com

Ejemplo de Mailgun

MAIL_PROVIDER=mailgun
MAILGUN_API_KEY=key-xxxxxxxx
MAILGUN_DOMAIN=mg.yourdomain.com
MAILGUN_API_BASE=https://api.mailgun.net
MAIL_FROM=Appointments <noreply@yourdomain.com>

Ejemplo de Postmark

MAIL_PROVIDER=postmark
POSTMARK_SERVER_TOKEN=xxxxxxxx
POSTMARK_MESSAGE_STREAM=outbound
MAIL_FROM=Appointments <noreply@yourdomain.com>

Ejemplo de Webhook

MAIL_PROVIDER=webhook
MAIL_WEBHOOK_URL=https://your-endpoint.example/hooks/mail
MAIL_WEBHOOK_SECRET=optional-bearer-token
MAIL_FROM=Appointments <noreply@yourdomain.com>

Después de cambiar las variables de entorno de correo electrónico, reinicie la aplicación. Luego vaya a Admin > Configuración > Entrega de correo electrónico y envíe un correo de prueba.

12. Correos de recordatorio

Maria Bookings puede enviar correos de recordatorio antes de las citas.

Los recordatorios compatibles incluyen:

  • Correos de recordatorio de 24 horas
  • Correos de recordatorio de 1 hora
  • Correos de recordatorio opcionales para el proveedor

En un VPS, los recordatorios se ejecutan automáticamente mientras la aplicación está en funcionamiento.

En Vercel u hosting sin servidor, configure una solicitud cron a:

/api/internal/reminders

Configure un secreto cron en el entorno:

CRON_SECRET=your-long-random-cron-secret

13. Protección contra bots

Maria Bookings admite protección contra bots para formularios públicos de reserva y contacto.

Proveedores compatibles

  • Cloudflare Turnstile
  • hCaptcha
  • Google reCAPTCHA v2

Variables de entorno

TURNSTILE_SECRET_KEY=your-secret-key
HCAPTCHA_SECRET_KEY=your-secret-key
RECAPTCHA_SECRET_KEY=your-secret-key

Las claves de sitio pueden introducirse en Admin > Configuración > Protección contra bots. Las claves secretas deben permanecer en el entorno del servidor y no almacenarse públicamente.

14. Idiomas y moneda

Maria Bookings incluye soporte multilingüe para el panel de administración, la página pública de reserva, la página de gestión de reservas, el portal público y las plantillas de correo electrónico.

La configuración de idioma está disponible en Admin > Configuración > Idioma y moneda.

  • Idioma del administrador: Se usa para el panel de administración y los correos de administradores/personal.
  • Idioma del sitio público: Se usa para la reserva pública, la gestión de reservas, el portal público y los correos de clientes.
  • Símbolo de moneda: Se usa para los precios de los servicios y los resúmenes de la reserva pública.

15. Marca y SEO

La configuración de marca está disponible en Admin > Configuración.

Puede configurar:

  • Nombre del negocio
  • Eslogan o descripción
  • Dirección
  • URL del logotipo
  • Color primario
  • Color de acento
  • Visibilidad de la atribución "impulsado por"
  • URL canónica del sitio
  • Título SEO
  • Descripción SEO
  • Palabras clave SEO

La aplicación también proporciona archivos públicos de descubrimiento, como los puntos de acceso robots y sitemap.

16. Roles de usuario y permisos

Administrador

Los administradores tienen acceso completo a toda la configuración, usuarios, registros, servicios, personal, clientes y citas.

Personal

Las cuentas de personal pueden vincularse a perfiles de personal/proveedor. Los usuarios de personal pueden restringirse a sus propias citas y a menús de administración limitados.

Gestor (Manager)

El rol de Gestor está disponible en Pro. Los gestores pueden asignarse a una sede y restringirse a operaciones específicas de esa sede.

17. Feeds de calendario

Los miembros del personal pueden tener URL privadas de suscripción a calendario. Estas permiten ver las citas en aplicaciones de calendario compatibles.

Los administradores pueden regenerar una URL de calendario si un enlace antiguo ya no debe usarse.

18. Lista de verificación recomendada para la configuración inicial

  1. Instalar las dependencias.
  2. Configurar las variables de entorno.
  3. Iniciar la aplicación.
  4. Abrir /setup.html.
  5. Probar la conexión a la base de datos.
  6. Crear la cuenta de administrador.
  7. Abrir el panel de administración.
  8. Actualizar la identidad del negocio y la marca.
  9. Establecer la zona horaria, el idioma y la moneda.
  10. Añadir servicios.
  11. Añadir miembros del personal.
  12. Asignar servicios al personal.
  13. Establecer los horarios del personal.
  14. Configurar la entrega de correo electrónico.
  15. Enviar un correo de prueba.
  16. Probar una reserva pública.
  17. Confirmar, completar y cancelar una cita de prueba.

Lista de verificación adicional para Pro

  1. Añadir sedes.
  2. Asignar personal a las sedes.
  3. Crear servicios de toda la organización o específicos de una sede.
  4. Asignar servicios al personal en cada sede.
  5. Revisar los problemas de reserva.
  6. Probar el flujo de reserva pública para cada sede.
  7. Crear cuentas de gestor si es necesario.
  8. Verificar las restricciones de acceso del gestor.

19. Actualización de Maria Bookings

  1. Haga una copia de seguridad de los archivos de la aplicación.
  2. Haga una copia de seguridad de la base de datos.
  3. Suba el nuevo paquete Standard o Pro.
  4. Mantenga sus valores existentes de .env.
  5. Ejecute npm install --omit=dev si las dependencias han cambiado.
  6. Reinicie la aplicación.
  7. Abra el panel de administración y confirme que el panel principal se carga.
  8. Pruebe una reserva desde la página pública de reservas.

No reemplace una instalación Pro con el paquete Standard a menos que desee eliminar intencionalmente la funcionalidad Pro.

20. Solución de problemas

La aplicación no se inicia

  • Confirme que Node.js 22 LTS o más reciente esté instalado.
  • Confirme que npm install --omit=dev se completó correctamente.
  • Confirme que las variables de entorno necesarias estén configuradas.
  • Revise los registros del servidor para detectar configuraciones faltantes de base de datos o correo.

La configuración indica que falló la conexión a la base de datos

  • Revise DB_TYPE.
  • Revise DATABASE_URL o DB_PATH.
  • Confirme que el servidor de base de datos sea accesible desde su plataforma de hosting.
  • Para PostgreSQL, confirme la configuración SSL requerida por su proveedor.

El secreto de instalación es rechazado

  • Confirme que el valor introducido en el asistente de instalación coincida exactamente con SETUP_SECRET.
  • Reinicie la aplicación después de cambiar las variables de entorno.

Los correos electrónicos no se envían

  • Confirme que MAIL_PROVIDER esté configurado correctamente.
  • Confirme que todas las credenciales necesarias del proveedor estén presentes.
  • Reinicie la aplicación después de cambiar las variables de correo.
  • Use Admin > Configuración > Entrega de correo electrónico para enviar un correo de prueba.

No aparecen franjas horarias

  • Confirme que el servicio esté activo.
  • Confirme que el miembro del personal esté activo.
  • Confirme que el miembro del personal esté asignado al servicio seleccionado.
  • Confirme que el horario del personal incluya el día seleccionado.
  • Confirme que la fecha esté dentro de la ventana máxima de días de antelación para reservar.
  • Confirme que las reglas de aviso mínimo no estén bloqueando la franja horaria.
  • En Pro, confirme que la sede tenga personal y servicios reservables.

Los clientes no pueden cancelar reservas

  • Confirme que el código de referencia de la reserva sea correcto.
  • Confirme que el cliente esté usando el correo electrónico o número de teléfono completo de la reserva para la verificación.
  • Confirme que la cita no esté ya completada.

Los servicios de sede en Pro se ocultan de la reserva

  • Abra Problemas de reserva en el panel de administración.
  • Confirme que la sede esté activa.
  • Confirme que el servicio esté activo.
  • Confirme que haya personal asignado a esa sede.
  • Confirme que el personal esté vinculado al servicio.

21. Recomendaciones de seguridad

  • Use valores aleatorios fuertes para JWT_SECRET, SETUP_SECRET y CRON_SECRET.
  • Use HTTPS en producción.
  • Mantenga privadas las credenciales de la base de datos.
  • No exponga públicamente el archivo .env.
  • Use credenciales de proveedores de correo electrónico de confianza.
  • Habilite la protección contra bots en los formularios públicos si el spam se convierte en un problema.
  • Otorgue al personal y a los gestores solo los permisos que necesiten.
  • Regenere las URL de feeds de calendario si se comparte accidentalmente un enlace privado.
  • Haga una copia de seguridad de la base de datos antes de las actualizaciones.

22. Soporte

Para soporte, contacte a Maria Stella Tech:

contact@mariastellatech.com