Manual de Usuario de PragmaticTours

¡Bienvenido a PragmaticTours! Esta guía explica cómo usar la plataforma en tu trabajo diario. Está escrita para el personal de agencias de turismo — despachadores, coordinadores, guías y administradores.

Tabla de Contenidos

Primeros Pasos
Tu Panel de Control
Vista de Calendario
Gestión de Tours
Gestión de Reservas y Clientes
Catálogo de Productos
Gestión de Flota
Ubicaciones y Zonas Operativas
Gestión de Personal
Despacho y Asignaciones
Auto-Asignación y Optimización
Motor de Notificaciones y Comunicaciones Multicanal
Manifiestos de Pasajeros
Equipo e Inventario
Informes Financieros
Informe de Pagos
Configuración de Usuario
Configuración de la Cuenta
Referencia de API (v1)

1. Primeros Pasos

Iniciar Sesión

Abre tu navegador y ve a la dirección de tu agencia (ejemplo: https://tuagencia.pragmatictours.com). Puedes iniciar sesión con:

Correo electrónico y contraseña — la cuenta que tu administrador creó para ti.
Cuenta de Google o Microsoft — si tu agencia ha activado esta opción.

Primera Vez

Si recibiste una invitación por correo electrónico, haz clic en el enlace del correo. Te llevará a una página donde puedes configurar tu contraseña. Después, serás dirigido al espacio de trabajo de tu agencia.

La Navegación Principal

Una vez que hayas iniciado sesión, verás un panel lateral izquierdo con estas secciones:

Menú	Quién Puede Verlo	Qué Puedes Hacer
Despacho	Todos	Ver los tours del día y asignar personal/vehículos
Calendario	Todos	Ver el calendario mensual
Manifiestos	Administradores, Despachadores	Subir y procesar listas de pasajeros
Inventario	Administradores, Despachadores	Gestionar equipo
Catálogo	Solo administradores	Crear plantillas de tours
Flota	Solo administradores	Agregar y gestionar vehículos
Ubicaciones y Zonas	Solo administradores	Crear y gestionar puertos, muelles y áreas de servicio
Equipo e Invitaciones	Solo administradores	Invitar y gestionar personal
Informes	Solo administradores	Ver ingresos, costos y ganancias diarias
Informe de Pagos	Solo administradores	Ver costos de freelancers y vehículos
Claves API	Solo administradores	Generar y revocar claves API
Configuración	Todos	Acceder a la configuración de la cuenta y el perfil

Barra Superior

En la parte superior de la página encontrarás:

Fecha actual — mostrada a la izquierda.
Campana de notificaciones — (solo administradores y despachadores) muestra un distintivo rojo con tu número de no leídas. Haz clic para abrir un menú desplegable con notificaciones recientes (nuevas asignaciones, aceptaciones, cancelaciones, reprogramaciones). Haz clic en "Ver todas las notificaciones" para ver la lista completa. Las notificaciones llegan en tiempo real — no necesitas recargar la página.
Menú de usuario — tus iniciales, nombre y rol a la derecha. Haz clic para acceder rápidamente a Perfil, Preferencias de Comunicación (solo cuando los canales de Telegram o WhatsApp están activados), Cambiar Contraseña, Configuración de Disponibilidad, o Cerrar Sesión. Si perteneces a múltiples agencias, puedes cambiar de cuenta o crear una nueva agencia aquí.

2. Tu Panel de Control

La página de Despacho es tu espacio de trabajo principal. Muestra todo lo que ocurre en un día seleccionado.

Elegir una Fecha

En la parte superior de la página verás: - Un selector de fecha — haz clic para seleccionar cualquier día. - Flechas de día anterior / siguiente — avanza un día a la vez. - Botón Hoy — vuelve a la fecha actual.

Lo Que Ves

Cada tour de ese día aparece como una tarjeta. Cada tarjeta muestra:

Nombre del tour — ej., "Aventura de Snorkel".
Estado — Programado, En Progreso, Completado o Cancelado.
Cantidad de pasajeros — cuántas personas hay en este tour.
Capacidad — asientos ocupados vs total asignado.
Personal asignado — guías, conductores y capitanes ya asignados.
Vehículos asignados — autobuses, furgonetas o botes ya asignados.
Recursos faltantes — roles o vehículos que aún necesitan asignarse.
Diálogo de motivo de cancelación — al hacer clic en Cancelar se abre un modal donde ingresas el motivo de la cancelación.

Tours de Múltiples Días

Cuando un tour se crea a partir de una plantilla multi-día, aparece como una sola tarjeta con una insignia Multi-Day (N días). La tarjeta muestra:

Encabezado del tour padre — el nombre del paquete y el rango de fechas (ej., "10 Jun – 13 Jun").
Insignía Día N — indica qué día del tour multi-día se está mostrando.
Nombre del tour hijo — el nombre del plan del día específico, debajo de la hora de recogida.
Datos del tour hijo — hora de recogida, dirección, asignaciones y manifiesto para ese día específico, no para todo el paquete.
Cancelar — cancela el tour multi-día completo y todos sus tours hijo.
Cancelar Día — cancela solo el día individual (tour hijo) mostrado en la tarjeta, sin afectar al resto del paquete.
Reagendar (todos los días) — desplaza todas las fechas de los tours hijo en el mismo número de días.

Estado de la Flota

En el lado derecho del panel de control verás el panel de Estado de la Flota. Muestra cada vehículo activo de tu flota (excluyendo vehículos deshabilitados) y su estado para el día seleccionado:

Estado	Significado
Disponible (verde)	El vehículo está libre y listo para asignación.
En Mantenimiento (rojo)	El vehículo tiene una bloque de mantenimiento programado. El optimizador no lo sugerirá.
No Disponible (rojo)	El vehículo ya está asignado a otro tour en este día (horario superpuesto).

3. Vista de Calendario

Haz clic en Calendario en el panel lateral para ver una vista mensual.

Cada día muestra un conteo de cuántos tours están programados.
Los tours multi-día aparecen en todos los días que abarcan, no solo en su fecha de inicio.
Haz clic en cualquier día para ver una lista detallada de todos los tours en esa fecha. Para tours multi-día, el detalle del día muestra los datos específicos del tour hijo para ese día, incluyendo el nombre del tour hijo debajo de la hora de recogida.
Usa las flechas o el botón "Hoy" para navegar.
El calendario respeta tu rol: los guías solo ven los tours a los que están asignados.

4. Gestión de Tours

Crear un Nuevo Tour

El formulario de creación se adapta según la plantilla que selecciones. Las plantillas pueden ser de un día o de múltiples días (consulta el Catálogo de Productos).

Tour de un Día

Ve a la página de Despacho para la fecha deseada.
Haz clic en "Nuevo Tour".
Selecciona una plantilla de un día del catálogo.
Completa:
Fecha — por defecto es el día actual.
Cantidad de Pasajeros — cuántas personas participarán.
Hora de Recogida — obligatorio. La hora de finalización se calcula automáticamente desde la duración de la plantilla; puedes ajustarla después al editar.
Dirección de Recogida — obligatorio.
Dirección de Devolución — opcional.
Duración del Traslado — cuánto tiempo toma llegar.
Estado — por defecto es Programado; también puedes iniciar el tour inmediatamente.
Compensación del Personal — elige entre Tarifa Gig (tarifa fija por tour) o Tarifa por Hora. Se puede sobrescribir por asignación.
Precio por Pax — se rellena automáticamente desde la plantilla, se puede modificar.
Haz clic en Guardar.

Tour de Múltiples Días

Ve a la página de Despacho para la fecha de inicio deseada.
Haz clic en "Nuevo Tour".
Selecciona una plantilla multi-día (identificada con una insignia "Multi-Day" en el menú desplegable).
El formulario cambia automáticamente al modo multi-día:
Fecha de Inicio — el primer día del tour (por defecto la fecha seleccionada).
Fecha de Fin — se calcula automáticamente desde la fecha de inicio + número de planes de día; puedes modificarlo.
Los campos de un día (hora de recogida, dirección, etc.) se ocultan — cada plan de día en la plantilla proporciona sus propios valores.
Un mensaje informativo muestra cuántos planes de día incluye la plantilla.
Completa Cantidad de Pasajeros, Estado y Compensación del Personal — estos se comparten entre todos los días. El precio se calcula automáticamente como la suma del precio de cada plan de día.
Haz clic en Guardar.

Detrás de escena, el sistema crea: - Un tour padre (categoría multi-día) con el rango de fechas. - Un tour hijo por cada plan de día, cada uno con su propia fecha, hora de recogida, dirección y precio por pasajero — tomados de la plantilla de un día asignada a cada plan.

Los tours hijo heredan la cantidad de pasajeros del padre. Cada hijo se puede gestionar individualmente desde el panel de control o el calendario — asignar personal, subir manifiestos o cancelar un día sin afectar al resto del paquete.

Validación del Formulario

Antes de enviar el formulario, el sistema verifica que todos los campos obligatorios estén completos. Si algún campo obligatorio está vacío, el formulario mostrará una alerta listando los campos faltantes y los resaltará en rojo. El formulario no se enviará hasta que todos los campos obligatorios estén completos.

Los campos obligatorios incluyen: - Plantilla — debe seleccionarse. - Fecha (un día) o Fecha de Inicio/Fin (multi-día) — deben establecerse. - Cantidad de Pasajeros — debe ser mayor que cero. - Hora de Recogida y Dirección de Recogida (un día) — obligatorios. - Duración del Traslado (un día) — obligatorio.

Estados del Tour

Programado — el tour está planificado y listo para asignaciones.
En Progreso — el tour ha comenzado.
Completado — el tour ha terminado.
Cancelado — el tour no se realizará. Cuando un tour se cancela, la tarjeta solo muestra el nombre del tour, el estado y el motivo de cancelación (si se ingresó uno) o una nota de "Reagendado". Las secciones de Recursos Requeridos, Lista de Equipo y Manifiesto y Asignaciones están ocultas.

Editar un Tour

Haz clic en una tarjeta de tour, luego selecciona Editar. Puedes cambiar cualquiera de los detalles. Una vez que un tour ha comenzado, no puedes editar ni eliminar asignaciones.

Subir un Manifiesto a un Tour

Desde la página del tour, puedes subir un manifiesto de pasajeros en CSV directamente. Consulta la sección Manifiestos de Pasajeros para más detalles.

Cancelar un Tour

Solo los administradores y despachadores pueden cancelar un tour. El tour debe estar en estado Programado para poder cancelarlo.

Abre la tarjeta del tour en el panel de control.
Haz clic en Cancelar junto al botón Editar.
Aparece un diálogo solicitando un motivo de cancelación. Ingresa el motivo y haz clic en Confirmar Cancelación.

Para tours de múltiples días: - Cancelar (padre) — cancela el tour multi-día completo y todos sus tours hijo. - Cancelar Día — cancela solo el día individual (tour hijo) mostrado en la tarjeta, dejando el resto del paquete intacto.

Cuando un tour es cancelado: - Todas las asignaciones pendientes y confirmadas se establecen en Cancelado. - Todos los equipos en salida se liberan. - Se envía un correo de notificación de cancelación a cada guía y conductor confirmado. - El estado del tour cambia a Cancelado y se mueve al pasado. - Se registra el motivo, quién lo canceló y cuándo, con fines de auditoría. Una vez cancelado, la tarjeta del tour se colapsa para mostrar solo el nombre, estado y motivo — todas las secciones operativas (recursos, asignaciones, manifiesto) quedan ocultas.

Reagendar un Tour

Reagendar mueve un tour a una nueva fecha preservando su manifiesto de pasajeros e intentando mantener el mismo personal y vehículos.

Solo los administradores y despachadores pueden reagendar. El tour debe estar en estado Programado para poder reagendarlo.

Abre la tarjeta del tour en el panel de control.
Elige la nueva fecha usando el selector de fecha junto a Reagendar.
Haz clic en Reagendar.

Para tours de múltiples días: - El botón dice "Reagendar (todos los días)". - Todas las fechas de los tours hijo se desplazan el mismo número de días que la fecha de inicio del padre. - Los tours hijo individuales no se pueden reagendar por separado.

Detrás de escena: - Se crea un nuevo tour en la nueva fecha con la misma configuración (cantidad de pasajeros, horarios de recogida, direcciones). - Las filas del manifiesto de pasajeros se transfieren al nuevo tour. - Cada miembro del personal y vehículo confirmado se transfiere como asignación borrador en el nuevo tour, siempre que estén disponibles. Si un recurso no está disponible en la nueva fecha, la asignación se omite silenciosamente para que el auto-optimizador pueda llenar el vacío. - Los equipos en salida se liberan del tour anterior y se recrean en el nuevo. - El tour original se cancela con una nota generada automáticamente (ej. "Reagendado para el 15 de julio de 2026"). - Se envía un correo de notificación de reagendamiento a cada miembro del personal confirmado. - El orquestador de auto-asignación se ejecuta en el nuevo tour para llenar cualquier vacío dejado por recursos no disponibles.

5. Gestión de Reservas y Clientes

La sección de Reservas permite a las agencias de turismo gestionar reservaciones de clientes, realizar seguimiento a la cantidad de pasajeros e integrar las ventas entrantes directamente con la operación diaria de los tours.

Visión General

Una Reserva (Booking) vincula a un Cliente principal (viajero responsable) con una Plantilla de Tour en una fecha específica, junto con los nombres de los pasajeros adicionales, categorías de edad y requisitos especiales (ejemplo: asistencia con silla de ruedas o preferencias alimenticias).

Cómo se Crean las Reservas

Las reservas pueden agregarse a PragmaticTours de dos formas:

Entrada Manual en la Web:
Ve a Reservas en la barra lateral izquierda y haz clic en "+ Nueva Reserva".
Selecciona o crea el Cliente principal (nombre, correo electrónico, teléfono, idioma de preferencia).
Selecciona la Plantilla de Tour y la Fecha de Reserva.
Establece el Estado (pending, confirmed o cancelled) y el Origen (manual_agent, website_widget, etc.).
Agrega los nombres de los pasajeros adicionales y requisitos especiales en Pasajeros de la Reserva.
Haz clic en Guardar.
Integración por API y Widget Web:
Sitios web externos, widgets de reserva o Agencias de Viajes en Línea (OTAs) pueden registrar reservas programáticamente mediante la API de Reservas (POST /api/v1/bookings).
La API busca o crea automáticamente el perfil del cliente por correo electrónico (upsert_by_email!).

[!IMPORTANT] Política de Manejo de Pagos: PragmaticTours NO procesa pagos directamente ni incluye pasarelas de pago internas. Los operadores de turismo cobran a sus clientes utilizando su propia pasarela de pagos (ejemplo: Stripe, PayPal, transferencia bancaria local o terminal punto de venta físico). Una vez que el operador recibe el pago, el operador o la integración API simplemente marca el estado de la reserva como confirmed (confirmado).

Integración con la Programación de Tours y el Panel de Control

PragmaticTours ofrece una integración fluida entre las reservas confirmadas y la logística operativa diaria:

Programación Automática de Tours: Cuando una reserva se marca como confirmed, PragmaticTours verifica el calendario para esa fecha y plantilla. Si aún no existe un tour programado para esa fecha, PragmaticTours crea y programa el tour automáticamente en el panel de control.
Sincronización Automática al Manifiesto: Las reservas confirmadas agregan automáticamente al cliente principal y a los pasajeros adicionales al Manifiesto de Pasajeros del tour y a la lista de asientos.
Estado Pendiente: Las reservas con estado pending (pendiente) NO crean tours en el panel de control hasta que su estado cambie a confirmed.
Cancelación: Al marcar una reserva como cancelled (cancelada), sus pasajeros se eliminan automáticamente del manifiesto del tour programado y se actualiza el conteo de pasajeros del tour.

Gestión de Clientes

La página de Clientes lista todos los perfiles de clientes registrados en tu agencia. Los clientes se identifican de forma única por su correo electrónico. Cuando un cliente recurrente realiza una nueva reserva, PragmaticTours reutiliza automáticamente su perfil de cliente existente y actualiza sus datos de contacto o idioma, evitando la creación de registros duplicados.

Cómo Agregar una Agencia B2B o Revendedor

Para registrar una nueva Agencia B2B o Agente de Reventa: 1. Ve a Clientes en el menú lateral principal (/customers). 2. Haz clic en el botón Agregar Cliente (/customers/new). 3. Completa el nombre de la agencia en Nombre Completo, correo electrónico y Número de Teléfono (campo obligatorio). 4. Selecciona Tipo de Cliente: Revendedor (Agente a Comisión). 5. Define el Porcentaje de Comisión (%) (ej. 10.0 o 15.0) y el Nivel de Tarifas (Margen Bruto o Tarifa Neta al Por Mayor). 6. Haz clic en Guardar Cliente.

Una vez guardada, la agencia estará disponible en el menú desplegable Agencia Padre / Cuenta Aliada al crear o editar subagentes o pasajeros individuales, y podrás consultarla en cualquier momento mediante la pestaña de filtro Agencias B2B y Revendedores.

6. Catálogo de Productos

La sección Productos (solo administradores) es donde creas y gestionas las plantillas de tours. Las plantillas definen los detalles del producto (duración, recogida, ruta) y las reglas de escalamiento de recursos que determinan qué personal y vehículos se necesitan.

Crear una Plantilla

Ve a Productos en la barra lateral.
Haz clic en "Nueva Plantilla" y completa:
Nombre — ej., "Expedición a Gamboa"
Código de Tour — código opcional de tu CSV de manifiesto (ej., "GAM-01")
Duración — en horas (ej., 4.5)
Hora de Recogida — hora de recogida predeterminada
Dirección de Recogida — ej., "Vestíbulo del hotel"
Duración del Tránsito — minutos desde la recogida hasta el destino
Haz clic en "Guardar y Agregar Reglas".

Una vez guardado, serás llevado a la página de detalle de la plantilla donde podrás definir reglas de recursos.

Lista de Plantillas

El índice del catálogo muestra todas tus plantillas con paginación. La navegación de páginas aparece en la parte inferior de la lista para ayudarte a navegar.

Editar una Plantilla

En la página de detalle de la plantilla, haz clic en "Editar" para modificar los campos del producto.

Mínimo de Pasajeros por Idioma

Cuando tus tours transportan pasajeros que hablan múltiples idiomas, el sistema intenta asignar guías que puedan cubrir todos los idiomas. Si ningún guía habla todos los idiomas, el sistema normalmente asigna un guía adicional por cada idioma adicional.

El campo Mínimo de Pasajeros por Idioma te permite establecer un umbral: un idioma secundario solo activa un guía adicional si al menos esa cantidad de pasajeros lo habla. Establécelo en 0 (el valor predeterminado) para siempre asignar guías por idioma.

Ejemplo: Si lo configuras en 20 y un tour tiene 30 pasajeros de inglés, 10 de francés y 10 de neerlandés, el sistema asignará un solo guía que hable inglés. Los grupos de francés y neerlandés son demasiado pequeños para justificar un guía dedicado.

Precio por Pasajero

El campo Precio por Pax establece un precio predeterminado por pasajero para los tours creados a partir de esta plantilla. Cuando creas un nuevo tour, este valor se rellena automáticamente desde la plantilla. Puedes sobrescribirlo en cada tour individual.

Las plantillas de un día requieren Precio por Pax. Si dejas este campo vacío en una plantilla de un día, el sistema no te permitirá guardarla. Las plantillas multi-día no requieren este campo — su precio se deriva de la suma de los precios de los planes de día.

Eliminar vs Deshabilitar una Plantilla

Al eliminar una plantilla: - Si la plantilla no tiene tours activos o asignaciones, se elimina permanentemente. - Si la plantilla tiene tours activos o asignaciones históricas, se deshabilita en lugar de eliminarse. Aparece una insignia "Deshabilitado" junto a su nombre, y ya no aparecerá en el catálogo de productos ni en el menú desplegable de creación de tours. - Puedes rehabilitar una plantilla deshabilitada en cualquier momento haciendo clic en el botón Habilitar en su página de detalle. Esto la restaura al catálogo.

Plantillas Multi-Día

Para crear un tour que abarque múltiples días, establece la Categoría de la plantilla como Paquete Multi-Día al crear una nueva plantilla.

El asistente de creación de plantillas se adapta:

Paso 1 (Tipo) — Selecciona Paquete Multi-Día.
El asistente oculta los campos de un día (duración, hora de recogida, etc.) y muestra la gestión de planes de día.
Paso 2 (Básicos) — Ingresa el nombre y el código como de costumbre.
Paso 3 (Planes de Día) — Agrega planes de día seleccionando una plantilla de un día existente para cada día. Puedes reordenar los planes y opcionalmente sobrescribir la hora de recogida o la dirección para cada plan.
Paso 4 (Precio) — Se omite para plantillas multi-día; el precio se deriva de la suma del precio de cada plan de día.
Paso 5 (Revisión) — Revisa y guarda.

Cada plan de día produce un tour hijo cuando se crea un tour multi-día a partir de esta plantilla. El precio total sugerido se calcula automáticamente como la suma de todos los precios de los planes de día.

7. Gestión de Flota

La sección Flota (solo administradores) es donde gestionas todos tus vehículos — autobuses, furgonetas, botes y más.

Agregar un Vehículo

Haz clic en "Agregar Vehículo" y completa:

Nombre — ej., "Bus 01" o "Panga 3".
Categoría Principal — elige Terrestre (autobuses, furgonetas) o Marino (botes, pangas).
Subcategoría — ej., autobús, furgoneta, panga, catamarán.
Capacidad — cuántos pasajeros puede transportar.
Número de Registro — placa o matrícula.
Licencia Requerida — qué licencia debe tener el conductor o capitán (ej., licencia de "autobús" para un autobús).
Propietario — este vehículo es Propio de tu agencia o Contratado de un tercero? Se usa en el Informe de Pagos para distinguir entre costos de vehículos propios vs contratados.
Estructura de la Flota (fleet_type) — selecciona Activo Físico Individual para vehículos individuales únicos (ej., Bus 01) o Pool de Sindicato Contratado para inventarios de proveedores (ej., Sindicato de Pangas del Canal).
Unidades Mínimas y Capacidad Máxima del Pool — especifica las unidades mínimas requeridas y la capacidad máxima disponible (ej., hasta 10 embarcaciones). La disponibilidad dinámica (5/10 Disponibles) se calcula automáticamente en tours traslapados.
Nombre y Representante del Proveedor — nombre opcional del proveedor/sindicato y usuario representante. Al confirmar asignaciones del pool, las notificaciones de reserva de WhatsApp se envían directamente al representante.
Provisión de Conductor / Capitán — especifica Personal de Agencia (si tu agencia proporciona los conductores/capitanes) o Provisto por Proveedor (si el proveedor/sindicato incluye sus propios operadores). Al seleccionar Provisto por Proveedor, el motor de auto-asignación omite automáticamente la búsqueda de personal interno y evita alertas falsas de falta de personal.
Operador Preferido — el conductor (para vehículos terrestres) o capitán (para vehículos marinos) por defecto que debería sugerirse cada vez que se asigna este vehículo. Solo se muestra el personal que tiene la licencia y el rol correctos.
Costo por Hora / por Día — para seguimiento de costos.

Estructura de la Flota y Sindicatos de Proveedores (Pools de Flota)

Al trabajar con proveedores externos o sindicatos de embarcaciones, puedes gestionar inventarios multi-unidad bajo un solo registro:

Establece la Estructura de la Flota en Pool de Sindicato Contratado.
Define la Capacidad Máxima del Pool (ej., 10 pangas).
Establece la Provisión de Conductor / Capitán en Provisto por Proveedor si el sindicato incluye sus propios capitanes/conductores.
Selecciona un Representante del Proveedor para recibir notificaciones automáticas de reserva por WhatsApp cuando se asignen unidades del pool a los tours.

El sistema gestiona automáticamente la disponibilidad en el panel de despacho (ej., 7/10 Disponibles) y previene la sobre-reserva en tours con horarios coincidentes.

Configurar un Operador Preferido

Al editar un vehículo, puedes seleccionar un Operador Preferido de una lista desplegable. Este miembro del personal será la primera sugerencia cuando el sistema o un despachador asigne este vehículo a un tour.

Para vehículos terrestres, solo puedes seleccionar personal certificado como conductores que tenga la licencia necesaria.
Para vehículos marinos, solo puedes seleccionar personal certificado como capitanes que tenga la licencia necesaria.

Si el operador preferido no está disponible (de vacaciones, ya asignado en otro lugar), el sistema elegirá automáticamente otro operador disponible.

Mantenimiento e Indisponibilidad

Para sacar un vehículo de servicio:

Ve a la página de Editar del vehículo.
Desplázate a la sección Programación de Mantenimiento.
Haz clic en "Programar Nuevo Mantenimiento".
Establece la fecha y hora de inicio y fin, y un motivo (ej., "Cambio de aceite").
El vehículo se marcará automáticamente como no disponible durante ese período.

Los vehículos en mantenimiento no aparecerán como disponibles en el Estado de la Flota, y el optimizador los omitirá.

Eliminar vs Deshabilitar un Vehículo

Al eliminar un vehículo: - Si el vehículo no tiene asignaciones históricas, se elimina permanentemente. - Si el vehículo tiene asignaciones pasadas o está actualmente asignado, se deshabilita en lugar de eliminarse. Aparece una insignia "Deshabilitado" en la lista de flota, y el vehículo ya no aparecerá como disponible para nuevos tours ni en el panel de Estado de la Flota. - Puedes asignar una Base Principal / Ubicación a cada vehículo, así como Áreas / Zonas Adicionales de Servicio para activos que cubren múltiples puertos (ej. un bote que presta servicio tanto en el Lago Gatún como en el Río Chagres). - El sistema valida las restricciones de ubicación: los vehículos solo se sugieren o auto-asignan a tours que operen en una ubicación o zona en la que prestan servicio.

Importar Vehículos desde un CSV

Puedes importar vehículos en masa haciendo clic en "Importar" y subiendo un archivo CSV. El archivo debe contener al menos las columnas nombre y capacidad. Las columnas opcionales incluyen categoría, registro, costos y licencia.

8. Ubicaciones y Zonas Operativas

La sección Ubicaciones y Zonas (solo administradores) es donde defines centros de servicio geográficos, puertos, muelles y límites operativos para el despacho de tours.

Gestión de Ubicaciones

Accede a Ubicaciones y Zonas desde el menú lateral izquierdo para: - Crear una Ubicación: Ingresa Nombre (ej., Gamboa / Lago Gatún), Código / Etiqueta (ej., GAM-LAK), Descripción / Detalles de Cobertura, y coordenadas opcionales de Latitud / Longitud. - Estado Activo / Inactivo: Cambia el estado a inactivo para suspender temporalmente el despacho a un puerto o área sin borrar su historial. - Editar y Eliminar: Actualiza los límites operativos o elimina ubicaciones no utilizadas.

Vinculación de Activos de Flota y Logística de Tours

Vincular Ubicación al Tour: Al crear una plantilla o programar un tour, selecciona su Ubicación / Zona de Servicio. Los tours heredan automáticamente la ubicación de su plantilla.
Coincidencia de Ubicación de Vehículos: En Gestión de Flota, asigna una Base Principal / Ubicación y selecciona Áreas / Zonas Adicionales de Servicio para activos que operan en múltiples puntos. Los vehículos marcados como Todas las Ubicaciones (Activo Global) pueden operar en cualquier lugar.
Control en Despacho:
El Optimizador de Auto-Asignación filtra automáticamente los vehículos que no prestan servicio en la ubicación del tour.
Despacho Manual: Intentar asignar manualmente un vehículo a un tour que opera fuera de su área de servicio muestra una alerta de incompatibilidad de ubicación.

Umbrales Mínimo / Máximo de Pasajeros e Itinerarios Detallados

Límites de Pasajeros Mín/Máx: Define el Umbral Mínimo de Pasajeros (ej. mínimo 5 pasajeros para operar) y el Límite Máximo de Capacidad opcional (ej. máximo 30 pasajeros) en plantillas y tours.
Descripción Detallada e Itinerario: Incluye Resumen, Itinerario Detallado, Inclusiones, Exclusiones, Instrucciones de Recogida y Requisitos Especiales directamente en las plantillas y tours programados.

9. Gestión de Personal

La sección Equipo (solo administradores) te permite gestionar tu personal.

Roles

Rol	Permisos
Administrador	Acceso completo — puede gestionar flota, equipo, productos y configuración
Despachador	Puede programar tours, asignar personal, procesar manifiestos, gestionar inventario
Guía	Puede ver asignaciones y el calendario, pero no puede hacer cambios

Invitar a un Nuevo Miembro

Ve a Equipo y haz clic en "Invitar Miembro".
Completa:
Correo electrónico — la invitación se enviará aquí.
Nombre y Apellido.
Número de WhatsApp — opcional. Incluye un selector de bandera de país internacional (ej., 🇵🇦 +507 Panamá, 🇺🇸 +1 EE. UU., 🇲🇽 +52 México, 🇨🇷 +506 Costa Rica, 🇨🇴 +57 Colombia, 🇪🇸 +34 España, 🇧🇷 +55 Brasil, 🇦🇷 +54 Argentina, 🇨🇱 +56 Chile, 🇵🇪 +51 Perú, 🇬🇧 +44 Reino Unido, 🇩🇪 +49 Alemania, 🇫🇷 +33 Francia, 🇳🇱 +31 Países Bajos). Si el usuario ya configuró su número de WhatsApp en su perfil personal, se mostrará automáticamente. Agregar o actualizar el número aquí lo sincroniza con su perfil.
Rol — administrador, despachador o guía.
Tipo de Empleo — empleado, freelancer o contratista.
Idiomas — qué idiomas habla (se usa para la auto-asignación).
Licencias de Operador — qué vehículos está autorizado a conducir o capitanear.
Roles de Personal — qué roles de despacho puede desempeñar (guía principal, guía, conductor, capitán).
Haz clic en Enviar Invitación.

La invitación expira después de 7 días. Puedes cancelar una invitación pendiente en cualquier momento.

Invitación Masiva

Puedes subir un archivo CSV para invitar a muchas personas a la vez. El archivo debe contener al menos las columnas correo electrónico y rol. También puedes incluir las columnas opcionales first_name, last_name, whatsapp, employment_type, languages, licenses y staff_roles.

Editar el Perfil de un Miembro

Haz clic en el nombre de un miembro o en Gestionar para editar sus certificaciones, tipo de empleo, tarifas y número de teléfono WhatsApp (con selector de código de país con banderas). Esto es importante porque el sistema de auto-asignación usa esta información para asignar a la persona adecuada a cada tour.

Idiomas

Configura los idiomas de un miembro (ej., inglés, español, francés). El sistema de auto-asignación compara estos idiomas con los idiomas del manifiesto de pasajeros. Por ejemplo:

Si un tour tiene pasajeros que hablan inglés y francés, el sistema primero buscará un guía que hable ambos idiomas.
Si no hay un guía bilingüe disponible, asignará dos guías — uno para cada idioma.
Un miembro del personal sin idiomas configurados se considera flexible y puede ser asignado a cualquier tour.

Licencias de Operador

Configura qué licencias tiene un miembro (ej., "autobús", "furgoneta", "panga"). El sistema verifica estas licencias al asignar conductores o capitanes a vehículos específicos.

Roles de Personal

Marca qué roles de despacho puede desempeñar un miembro: guía principal, guía, conductor, capitán. Esto determina qué tipo de asignaciones puede recibir.

Cumplimiento de Horas de Conducción

Para miembros con roles de Conductor o Capitán, puedes establecer límites de horas de conducción diarios y semanales. Estos campos solo aparecen después de marcar la casilla de Conductor o Capitán.

Máximo de Horas por Día — el máximo total de horas de trabajo que esta persona puede acumular en un solo día (ej., 10).
Máximo de Horas por Semana — el máximo total de horas de trabajo para una semana rodante de 7 días (ej., 48).

Cuando estos límites están configurados, el sistema de auto-asignación verifica las horas acumuladas del conductor antes de sugerirlo para un tour. Si asignarlo excedería el límite, el sistema lo omite y selecciona el siguiente operador disponible — incluso si es el operador preferido de un vehículo.

Esto garantiza el cumplimiento de las regulaciones locales de horas de conducción (ej., reglas de horas de la UE, horas de servicio de la FMCSA). Deja ambos campos en blanco para deshabilitar la verificación (sin límite aplicado).

Configurar Indisponibilidad (Bloques de Tiempo)

Los miembros del personal pueden bloquear períodos en los que no están disponibles. Ve a Configuración > Mi Disponibilidad y agrega un bloque de tiempo con un motivo (vacaciones, cita médica, etc.). El sistema de auto-asignación los omitirá durante ese período.

Pausar / Reactivar una Membresía

Al final de una temporada, los administradores y despachadores pueden pausar la membresía de un miembro del equipo en lugar de eliminarlo. Al pausar:

El miembro queda excluido de las sugerencias de auto-asignación.
Su perfil, certificaciones y configuración se mantienen intactos.
Aparece como "En Pausa" en la lista del equipo.

Para pausar, haz clic en Pausar junto al nombre del miembro en la lista del equipo.

Para reactivar, haz clic en Reactivar (solo administradores y despachadores). El sistema envía un correo de notificación informando al miembro que su membresía ha sido reactivada.

Re-invitar a un miembro pausado: Si intentas enviar una invitación a un correo que ya tiene una membresía pausada, el sistema reactiva automáticamente la membresía existente y notifica al usuario — no se crea una nueva invitación.

10. Despacho y Asignaciones

Asignación Manual

Desde la página de Despacho, cada tarjeta de tour incluye un formulario dinámico de asignación manual para agregar personal o vehículos:

Selección de Personal: Selecciona un miembro del personal en el menú desplegable Personal. La lista muestra el Nombre y Apellido de la persona junto con sus capacidades certificadas (ej., Noah UIOne (Driver / Guide)).
Pre-selección Inteligente del Rol: Al seleccionar un miembro del personal, el menú desplegable Rol pre-selecciona automáticamente su rol certificado principal (Conductor, Capitán, Guía Principal o Guía) y filtra las opciones válidas según sus capacidades registradas.
Coincidencia de Vehículo por Licencia y Categoría:
Conductor: Activa el menú desplegable de Vehículo y filtra exclusivamente a vehículos Terrestres (Autobús, Furgoneta, Midi Coach, etc.) que coincidan con las licencias del conductor.
Capitán: Activa el menú desplegable de Vehículo y filtra exclusivamente a vehículos Marítimos (Panga, Catamarán, Skiff, etc.) que coincidan con las licencias del capitán.
Guía / Guía Principal: Desactiva automáticamente el selector de vehículo mostrando "(No requiere vehículo)".
Las opciones del selector de vehículos muestran la capacidad de pasajeros y la categoría (ej., Coaster Bus 01 (30 pax · Road)).
Exclusión de Recursos Asignados y Superpuestos: El personal y los vehículos que ya estén asignados al tour actual o a otro tour superpuesto en la misma fecha se excluyen automáticamente de los menús desplegables.
Actualización Automática en Tiempo Real: Hacer clic en + Asignar o eliminar una asignación actualiza automáticamente el formulario de asignación manual en tiempo real mediante Turbo Streams sin necesidad de recargar la página. El personal/vehículo asignado desaparece inmediatamente y reaparece si se elimina una asignación.
Advertencias Interactivas de Validación de Reglas:
Advertencia de Vehículo Sobredimensionado: Si seleccionas un vehículo con capacidad de 40+ para un grupo pequeño (ej., 8 pasajeros) habiendo una furgoneta más adecuada disponible (ej., furgoneta de 15 pax), o si seleccionas un vehículo con capacidad insuficiente, se muestra una alerta interactiva antes de enviar: > "Advertencia: Este tour tiene 8 pasajeros, pero seleccionaste 'Custom Big Bus' (capacidad 50 pax) habiendo un vehículo más pequeño disponible. ¿Deseas continuar?"
Advertencia de Exceso de Guías / Requisitos de Regla: Si las reglas de la plantilla especifican un número requerido de guías (ej., 1 Guía Principal requerido) y ese requisito ya se ha cumplido, intentar asignar un guía adicional activa un diálogo de confirmación: > "Confirmación de Sobrescritura de Regla: Las reglas del tour especifican 1 GUÍA PRINCIPAL, el cual ya está asignado. ¿Estás seguro de que deseas asignar un GUÍA PRINCIPAL adicional y sobrescribir la regla?" Hacer clic en Cancelar detiene el envío; hacer clic en Aceptar confirma la sobrescritura manual de la regla.

Eliminar una Asignación

Puedes eliminar una asignación haciendo clic en el botón Eliminar junto a ella. Esto no está permitido una vez que el tour ha comenzado. Eliminar una asignación restaura de inmediato al miembro del personal y al vehículo en las opciones del selector manual.

Estados de las Asignaciones

Borrador — propuesta por el sistema de auto-asignación, pendiente de tu revisión. No se envía ninguna notificación.
Confirmada — la asignación está activa. El miembro del personal recibe una notificación por correo electrónico, Telegram o WhatsApp (según los canales habilitados por la agencia). Pueden Aceptar la asignación haciendo clic en el enlace del correo o tocando el botón en línea de Aceptar en Telegram o WhatsApp.
Rechazada — la asignación fue rechazada. Se conserva para fines de auditoría.

Aceptar Asignaciones (para el Personal)

Cuando te asignan a un tour: 1. Recibes una notificación por correo electrónico, Telegram y/o WhatsApp con los detalles del tour. 2. Por correo: Haz clic en el botón "Aceptar Asignación" en el correo — verás un resumen del tour. Haz clic en Aceptar. 3. Por Telegram o WhatsApp: Toca el botón "✅ Aceptar" en el mensaje de notificación — el servicio/bot confirma tu aceptación. 4. Se te enviará un correo de confirmación con una invitación de calendario (.ics) que puedes agregar a Google Calendar, Outlook o Apple Calendar. 5. Tu despachador verá una notificación en vivo de que aceptaste.

Tipo de Compensación

Cada asignación registra si el miembro del personal recibe pago por Gig (tarifa fija por tour) o Por Hora. El tipo de compensación se hereda de la configuración predeterminada del tour, pero se puede sobrescribir por asignación.

Personal freelance muestra una insignia morada de Freelance junto a su nombre. Los despachadores y administradores pueden hacer clic en la insignia ⏱ Por Hora o 💰 Gig para cambiar el tipo de compensación de esa asignación.
Empleados y contratistas no muestran la insignia de compensación — su compensación se gestiona a través del sistema de nómina de tu agencia.

11. Auto-Asignación y Optimización

PragmaticTours puede sugerir automáticamente la mejor combinación de vehículos y personal para tus tours. Esto ahorra tiempo y te ayuda a usar tus recursos de manera eficiente.

Optimizar un Solo Tour

En cualquier tarjeta de tour, haz clic en "Auto-Asignar". El sistema:

Analiza tu flota — verifica qué vehículos están disponibles (no en mantenimiento, no asignados a otro tour).
Selecciona los mejores vehículos — elige vehículos que tengan suficientes asientos para tus pasajeros, usando la menor cantidad de vehículos posible y minimizando los asientos desperdiciados.
Selecciona el mejor personal — basado en:
Roles requeridos (guía principal, guía, conductor, capitán).
Cobertura de idiomas — los idiomas del personal se comparan con los idiomas de los pasajeros del manifiesto.
Licencias — los conductores y capitanes deben tener la licencia correcta para el vehículo.
Disponibilidad — sin bloqueos de tiempo libre ni conflictos de horario.
Operador preferido — si un vehículo tiene un conductor o capitán preferido, se sugiere primero.

Ejemplo: Tienes un tour con 20 pasajeros que hablan inglés y francés. Tu flota tiene un autobús (40 asientos), una furgoneta (15 asientos), una panga (10 asientos) y otra panga (10 asientos). Tienes un guía principal bilingüe que habla inglés y francés, y un guía que solo habla inglés.

El sistema: - Sugerirá la furgoneta (15 asientos) + una panga (10 asientos) = 25 asientos totales, en lugar de usar el autobús (40 asientos) que desperdiciaría 20 asientos. - Sugerirá el guía principal bilingüe para ambos idiomas, en lugar de asignar dos guías separados.

Optimizar un Día Completo

En la página de Despacho, haz clic en "Optimizar Día". El sistema analiza TODOS los tours de esa fecha y propone asignaciones para todos ellos, asegurándose de que: - Cada vehículo se use solo en un tour por día. - Cada miembro del personal solo esté asignado a un tour a la vez.

Esto es útil cuando tienes múltiples tours en el mismo día y quieres el mejor uso general de tu flota y personal.

Revisar Propuestas

Todas las auto-asignaciones se crean como Borrador — nada es definitivo hasta que lo apruebes. Verás un panel con todas las asignaciones propuestas:

Acepta cada propuesta individualmente, o usa "Aceptar Todo" para confirmar todo de una vez.
Rechaza propuestas individuales o haz clic en "Rechazar Todo" para descartar todas las sugerencias en borrador de una sola vez.
Seguridad en Rechazos: Al descartar o rechazar borrador de propuestas, el sistema omite las validaciones de restricciones operativas (como la coincidencia de ubicación), garantizando que rechazar borradores siempre se complete con éxito sin bloquear al despachador.
Una vez aceptada, la asignación pasa a Confirmada y se envían las notificaciones.

Notas Importantes

La auto-asignación es una herramienta de sugerencia. Siempre puedes anularla haciendo cambios manuales.
El sistema nunca asigna un vehículo o persona que esté bloqueado por mantenimiento o tenga un conflicto de horario.
Si no se encuentra una solución (ej., no hay suficientes vehículos para todos los tours), el sistema propondrá lo que pueda y dejará el resto para asignación manual.
Si una plantilla de tour no tiene reglas de recursos definidas, el sistema no puede auto-asignar nada para ese tour. Mostrará un mensaje de advertencia: "No hay reglas de recursos definidas en esta plantilla. Agregue reglas o asigne manualmente." Define las reglas en la página de detalle de la plantilla o asigna personal y vehículos manualmente.

Modos de Optimización: Recursos vs Costo

El sistema ofrece dos modos de optimización. Verás dos conjuntos de botones en la página de Despacho:

Botón	Modo	Objetivo
⚡ Auto-Asignar / ⚡ Optimizar Día / ⚡ Optimizar Multi-Día	Minimizar Recursos (predeterminado)	Usar la menor cantidad de vehículos y personal posible, con menos asientos desperdiciados.
💰 Auto-Asignar (Costo) / 💰 Optimizar Día (Costo) / 💰 Optimizar Multi-Día (Costo)	Minimizar Costo	Usar la combinación más económica de vehículos y personal que cumpla con todos los requisitos.

Ambos modos respetan las mismas restricciones — disponibilidad, licencias, horas, cobertura de idiomas y reglas de recursos. La única diferencia es cómo se elige entre los candidatos que pasan todos los filtros.

Continuidad del personal vs. costo: Al optimizar un tour multi-día, la continuidad del personal siempre prevalece sobre el costo. La jerarquía de desempate es: 1. Puntaje de idioma/rol 2. ¿Esta persona fue asignada en un día anterior del mismo tour multi-día? (preferido) 3. Costo del personal (solo modo costo) 4. Horas trabajadas ese día 5. Nombre (alfabético)

Esto significa que si el guía más barato para el Día 2 es una persona diferente al guía del Día 1, el sistema mantendrá al guía del Día 1 — la continuidad tiene prioridad sobre el ahorro económico. La optimización de costos solo afecta qué guía se elige cuando no hay preferencia de continuidad (ej., primer día de un tour multi-día, o un tour de un solo día).

Cuándo Usar Cada Modo

Minimizar Recursos — Úsalo cuando quieras mantener bajo el uso de tu flota y evitar despachar más vehículos de los necesarios. Ideal cuando la disponibilidad de vehículos es limitada y necesitas reservar capacidad para otros tours.
Minimizar Costo — Úsalo cuando tengas variedad de opciones de vehículos y personal a diferentes precios y quieras minimizar los costos de pago. Una furgoneta pequeña y barata puede preferirse sobre un autobús grande y costoso, incluso si significa usar más de un vehículo.

Cómo Funciona la Optimización por Costo

Vehículos: El costo total de cada vehículo es el mayor entre costo_por_hora × duración_del_tour y costo_por_día (el que sea más alto). Luego, el costo por asiento se calcula como costo_total ÷ capacidad. El sistema elige primero los vehículos con los asientos más baratos, sin importar su tamaño. Esto significa que podría elegir dos furgonetas pequeñas y baratas en lugar de un autobús grande y costoso si las furgonetas son más baratas por pasajero, y respeta el costo mínimo diario del vehículo incluso si el tour es corto.

Personal: El costo del personal se calcula como: - Tarifa Gig (tarifa fija por tour) para compensación por Gig. - Tarifa por hora × duración del tour para compensación por hora.

Entre candidatos con igual cobertura de idiomas y calificaciones de rol, se elige primero al miembro del personal más económico.

Ejemplo: Tienes un tour con 20 pasajeros. Las opciones de tu flota son: - Bus A: 50 asientos, $100/hora ($2.00 por asiento por hora) - Bus B: 30 asientos, $80/hora ($2.67 por asiento por hora) - Van: 15 asientos, $50/hora ($3.33 por asiento por hora)

En el modo Recursos, el sistema elige el vehículo más pequeño suficiente (Van + Bus B = 2 vehículos, mínimo desperdicio). En el modo Costo, el sistema elige los asientos más baratos primero (solo Bus A — $2.00/asiento es el más barato, aunque sea el más grande).

Resolución de Conflictos y Prioridad de Desempate

Cuando varios miembros del personal podrían ocupar un rol, el sistema resuelve los conflictos usando la siguiente jerarquía de decisión. Cada paso reduce el grupo hasta que solo queda un candidato.

Para Guías (Guía Principal y Guía)

Prioridad	Regla	Qué Sucede
1	Cobertura de idiomas	Se prefiere al personal cuyos idiomas hablados coinciden con los idiomas requeridos del tour. Un miembro sin idiomas configurados se considera flexible — puede ser asignado pero no se elige sobre alguien con un idioma documentado que coincida.
2	Calificación como guía principal	Al buscar un guía universal (alguien que hable TODOS los idiomas requeridos), se prefiere a quien pueda actuar como guía principal sobre quien solo pueda guiar.
3	Horas trabajadas	Entre candidatos igualmente calificados, se elige a quien tenga menos horas ya asignadas en ese día. Esto distribuye la carga de trabajo equitativamente y evita que alguien entre en horas extra.
4	Nombre (alfabético)	Como desempate determinista final, se elige al miembro del personal cuyo nombre aparezca primero alfabéticamente.

Para Conductores y Capitanes

Prioridad	Regla	Qué Sucede
1	Licencia requerida	El miembro del personal debe tener la licencia de operador correcta para el vehículo. El personal sin la licencia requerida queda excluido por completo.
2	Límite de horas	El personal que excedería sus `max_horas_diarias` o `max_horas_semanales` queda excluido, incluso si es el operador preferido.
3	Operador preferido	Si el vehículo tiene un `operador_preferido` y esa persona está disponible, tiene licencia y cumple con las horas, se le asigna inmediatamente.
4	Horas trabajadas	Entre los candidatos restantes, se elige a quien tenga menos horas asignadas ese día.
5	Nombre (alfabético)	Desempate determinista final.

Para Vehículos

Prioridad	Regla	Qué Sucede
1	Menos vehículos	El sistema primero minimiza el número total de vehículos necesarios (solucionador CP-SAT) o usa el mejor ajuste (empaquetado greedy como alternativa).
2	Menor capacidad desperdiciada	Entre soluciones con el mismo número de vehículos, se elige la de menor capacidad total (menos asientos vacíos).

Desempate en Modo Costo

Cuando usas el modo 💰 Minimizar Costo, las reglas de desempate anteriores cambian en dos niveles:

Vehículos: En lugar de minimizar la cantidad de vehículos y la capacidad desperdiciada, el sistema minimiza el costo monetario total (costo_por_hora × duración_del_tour). Puede elegir más vehículos si en conjunto son más baratos.

Personal (guías, conductores, capitanes): Después de la cobertura de idiomas, se inserta un nuevo desempate:

Prioridad	Regla	Qué Sucede
3	Costo del personal (solo modo costo)	Entre candidatos igualmente calificados, se elige a quien tenga el menor costo (tarifa gig o tarifa por hora × duración).

Esto significa que la prioridad completa para guías en modo costo es: cobertura de idiomas → calificación como guía principal → costo del personal → horas trabajadas → nombre. Y la prioridad completa para operadores es: licencia → horas → operador preferido → costo del personal → horas trabajadas → nombre.

Qué Sucede Cuando Nadie Está Disponible

Si no se encuentra ningún miembro del personal elegible (todos exceden horas, todos carecen de licencias, todos ya están asignados), el sistema registra una falla en el resultado de la optimización y deja ese espacio vacío para asignación manual. Verás estas fallas listadas en el panel de resultados de optimización.

Protección en el Ámbito de Día

Cuando ejecutas "Optimizar Día", el sistema rastrea cada asignación de personal en todos los tours de esa fecha. Un miembro del personal asignado al tour de la mañana no será propuesto para el tour de la tarde si hay superposición horaria, incluso si cada tour individualmente lo consideraría disponible. Esto evita la doble reserva en todo tu día.

Validación de Idioma

Cuando se asigna un miembro del personal a un tour (ya sea por el optimizador o manualmente), el sistema verifica que los idiomas hablados del miembro asignado coincidan con al menos uno de los idiomas de los pasajeros del tour. Si el miembro del personal tiene idiomas configurados pero ninguno coincide con los del tour, la asignación es rechazada con un mensaje de error. Esto garantiza que un tour bilingüe nunca reciba un guía que solo hable inglés.

Esta validación no aplica al personal sin idiomas configurados (se consideran flexibles) ni a roles que no son de guía (conductores, capitanes).

Optimizar un Tour Multi-Día

Si tienes un tour multi-día (con múltiples tours hijos diarios vinculados a un padre), puedes optimizar todos los días a la vez. En la tarjeta del tour padre, junto a la etiqueta "Multi-Day (X days)", encontrarás:

⚡ Optimizar Multi-Día — Ejecuta la optimización de minimización de recursos en cada tour hijo del padre multi-día.
💰 Optimizar Multi-Día (Costo) — Ejecuta la optimización de minimización de costos en cada tour hijo.

Al hacer clic en cualquiera de los botones, el sistema: 1. Optimiza cada tour hijo de forma independiente, siguiendo las reglas de recursos de su propia plantilla. 2. Prefiere el mismo personal (guías, conductores, capitanes) en días consecutivos cuando están disponibles, proporcionando consistencia para tus huéspedes. 3. Recolecta todas las propuestas en un solo panel padre agrupado por día.

Esto es más eficiente que optimizar cada día individualmente, especialmente para tours de 3+ días donde deseas el mismo guía durante todo el recorrido.

Entendiendo los Requisitos No Cumplidos

Cuando el sistema no puede cumplir con todos los requisitos, registra las fallas y las muestra como un banner de advertencia en la parte superior del panel de propuestas de borrador. Por ejemplo:

⚠️ Algunos requisitos no pudieron cumplirse - Conductor para Mercedes 500 1: No hay conductor disponible (con licencia, dentro de horas, no ya utilizado) - Capitán para Ocean Panga Boat: No hay capitán disponible (con licencia, dentro de horas, no ya utilizado)

Estas advertencias aparecen cuando: - Ningún miembro del personal con el rol requerido está disponible en esa fecha (conflictos de horario, bloques de tiempo libre). - Ningún miembro del personal tiene la licencia correcta para el vehículo. - Todos los candidatos excederían sus límites de horas diarios o semanales. - No hay suficientes personas calificadas para la cantidad de vehículos (ej., 2 pangas pero solo 1 capitán).

Los espacios no cubiertos quedan vacíos para asignación manual. Puedes usar el formulario de asignación manual debajo del panel de borradores para agregar personal o vehículos tú mismo.

12. Motor de Notificaciones y Comunicaciones Multicanal

PragmaticTours incluye un motor de notificaciones en tiempo real diseñado específicamente para la logística de agencias de turismo. Conecta a despachadores, agentes de ventas, guías, conductores, capitanes y proveedores externos a través de tres canales de entrega: Correo Electrónico, Bot de Telegram y WhatsApp Cloud API (Meta).

Canales de Notificación por Nivel de Suscripción

Basecamp (Gratis): Incluye Notificaciones solo por Correo Electrónico.
Voyage (Pro): Incluye Correo Electrónico + la opción de Notificaciones por WhatsApp o Telegram (1 canal activo de mensajería instantánea).
Expedition (Avanzado): Incluye Correo Electrónico + Notificaciones por WhatsApp y Telegram (ambos canales de mensajería activos simultáneamente).

Integración con el Despacho, Agentes, Guías y Conductores

1. Invitaciones Automáticas de Asignación de Tour

Cuando un administrador, despachador o el motor de optimización auto-asigna a un miembro del personal (guía principal, guía, conductor o capitán) a un tour programado: - El sistema envía automáticamente una notificación a través de todos los canales habilitados para ese miembro del personal. - Contenido del Mensaje: Nombre del Tour, Fecha y Hora de Recogida, Lugar/Muelle de Recogida, Cantidad de Pasajeros, Idioma, Nombre del Vehículo e Instrucciones Especiales.

2. Flujo Interactivo Aceptar / Rechazar para Conductores y Guías

El personal de campo no necesita iniciar sesión en el panel web para confirmar sus asignaciones. Pueden interactuar directamente desde las notificaciones: - Vía Correo Electrónico: - Recibe un correo HTML con botones de Aceptar Asignación y Rechazar Asignación. - Al hacer clic en Aceptar Asignación, se abre una página de confirmación con el resumen del tour y se genera un archivo de calendario .ics para Google Calendar, Apple iCal o Microsoft Outlook. - Vía Bot de Telegram: - Recibe una tarjeta en tiempo real en Telegram con botones interactivos ✅ Aceptar / ❌ Rechazar. - Al tocar ✅ Aceptar, el estado de la asignación se actualiza inmediatamente a confirmada en la base de datos sin abrir el navegador. - Vía WhatsApp Cloud API (Meta): - Envía mensajes interactivos de tipo UTILITY aprobados por Meta (plantilla tour_assignment) con botones de respuesta rápida (✅ Aceptar / ❌ Rechazar). - Al tocar ✅ Aceptar, se envía un webhook instantáneo a PragmaticTours para registrar la aceptación.

3. Alertas en Tiempo Real para Despachadores y Agentes

Cuando un conductor o guía acepta o rechaza una asignación, la Campana de Notificaciones en la barra superior del panel del despachador muestra un distintivo rojo con el contador de no leídas.
El Calendario de Despacho Visual se actualiza en tiempo real mediante Turbo Streams (ws/SSE), cambiando el distintivo a verde (Aceptado) o rojo (Rechazado), lo que permite a los despachadores reasignar tours rechazados inmediatamente.

4. Notificaciones Automáticas de Cancelación y Reprogramación

Cancelaciones de Tours: Cuando un agente o despachador cancela un tour, se envía una alerta automática de cancelación a todos los conductores, guías y capitanes asignados vía Correo, Telegram o WhatsApp para evitar desplazamientos innecesarios al punto de recogida.
Reprogramación de Tours: Cambiar la fecha, hora o ubicación de recogida de un tour envía automáticamente una alerta de reprogramación con los detalles anteriores vs. nuevos a todo el equipo asignado.

5. Notificaciones a Proveedores Externos y Unidades de Pool

Cuando se asignan vehículos o equipos de proveedores externos a los tours, se envían notificaciones automáticas por WhatsApp/Correo al Representante del Proveedor asignado con las horas de recogida y cantidad de pasajeros.

Configuración del Personal: Vinculación de Canales de Comunicación

Notificaciones por Correo Electrónico

Se activan automáticamente utilizando la dirección de correo registrada en tu perfil de personal (/settings/profile).

Conexión de Telegram (`/settings/telegram`)

(Visible cuando las notificaciones de Telegram están activadas por tu agencia) 1. Ve a Configuración de Usuario > Conexión de Telegram. 2. Haz clic en Conectar a Telegram para generar un enlace único de vinculación (ejemplo: https://t.me/TuAgenciaBot?start=XYZ123). 3. Abre el enlace en Telegram y activa el bot. Una vez vinculado, recibirás las tarjetas de asignación con botones interactivos directamente en Telegram.

Conexión de WhatsApp (`/settings/whatsapp`)

(Visible cuando las notificaciones de WhatsApp están activadas por tu agencia) 1. Ve a Configuración de Usuario > Conexión de WhatsApp. 2. Haz clic en Generar Código de Vinculación para obtener un código de 6 dígitos o enlace directo wa.me. 3. Envía el código de 6 dígitos al número oficial de WhatsApp Business de tu agencia. Un distintivo verde de Conectado confirmará la verificación. 4. Haz clic en Enviar Mensaje de Prueba para verificar la entrega.

Administración de la Agencia y Gestión de Plantillas de Meta WhatsApp (Solo Administradores)

Los administradores configuran las opciones de notificación en Configuración > Configuración de la Cuenta (/settings/account).

1. Activación de Canales

Activa o desactiva los canales habilitados en Canales de Notificación: Correo Electrónico, Telegram y WhatsApp.

2. Configuración del Bot de Telegram

Crea un bot usando @BotFather en Telegram y copia el token de API.
Ingresa el Token del Bot y el Nombre de Usuario del Bot en la Configuración de la Cuenta.
Haz clic en Registrar Webhook para conectar PragmaticTours con Telegram.

3. Configuración de WhatsApp Cloud API de Meta

Registro Integrado: Haz clic en Conectar con Meta para autorizar tu Cuenta de WhatsApp Business (WABA).
Configuración Manual: Ingresa tu Token de Acceso Permanente, ID de Número de Teléfono e ID de WABA.

4. Gestión de Plantillas de Mensajes de Meta

Meta clasifica las plantillas de WhatsApp en tres categorías: - UTILITY: Mensajes operacionales transaccionales (asignaciones, cancelaciones, reprogramaciones). Aprobación rápida (minutos), menor costo por conversación, alta entregabilidad. - MARKETING: Campañas promocionales y ofertas de ventas. - AUTHENTICATION: Códigos de verificación de un solo uso (OTP).

5. Mapeo de Eventos del Sistema y Cambio Automático de Plantillas

PragmaticTours mapea automáticamente los eventos del sistema con las plantillas de WhatsApp: - tour_assignment: Enviado cuando se asigna personal. Incluye variables posicionales {{1}} (Nombre del Tour), {{2}} (Hora de Recogida), {{3}} (Dirección de Recogida) y botones ✅ Aceptar / ❌ Rechazar. - tour_cancellation: Enviado cuando se cancela un tour. - tour_reschedule: Enviado cuando se actualiza la fecha/hora del tour. - whatsapp_linked: Confirmación cuando el personal vincula su cuenta de WhatsApp.

Los administradores pueden enviar plantillas personalizadas de Meta en Configuración de la Cuenta. Una vez aprobadas (estado 🟢 APROBADO por Meta), PragmaticTours cambia automáticamente a usar la versión de plantilla aprobada más reciente para todas las notificaciones salientes subsecuentes.

13. Manifiestos de Pasajeros

Puedes subir listas de pasajeros en formato CSV. El sistema soporta dos formatos:

Formato Crucero

Se usa típicamente para pasajeros de cruceros que desembarcan para hacer tours. Las columnas pueden incluir: - Número de viaje, nombre del barco, código del tour, nombres de pasajeros, idioma, necesidades especiales.

Formato Charter

Se usa típicamente para charters privados o reservas de grupo. Las columnas pueden incluir: - Número de vuelo, número de cola, total de pasajeros, código del tour de conexión.

Cómo Importar

Ve a Manifiestos y haz clic en "Subir Manifiesto".
Selecciona tu archivo CSV. Opcionalmente, establece una Fecha de Programación si el archivo no incluye fechas.
El sistema procesará el archivo y te mostrará:
Filas válidas — pasajeros que coinciden con una plantilla de tour existente.
Filas inválidas — pasajeros que no pudieron ser emparejados (ej., código de tour desconocido).
Resuelve las filas inválidas de dos formas:
Asignar a una plantilla existente — selecciona un producto del menú desplegable junto a la fila y haz clic en "Asignar". La fila se vuelve válida inmediatamente.
Crear un nuevo producto — haz clic en "+ Crear Producto Faltante" para abrir un formulario de nueva plantilla en una pestaña nueva, prellenado con el código faltante. Después de guardar, haz clic en "Re-validar" para reprocesar el archivo.
También puedes ignorar las filas inválidas — el botón "Importar" está siempre disponible cuando hay filas válidas. Las filas inválidas simplemente se omiten. Una nota indica cuántas serán ignoradas.
Haz clic en "Importar". El sistema creará tours y asignará los pasajeros según los conteos de pasajeros.

Carga por Tour

También puedes subir un manifiesto directamente en la página de un tour específico. Esto es útil cuando ya sabes a qué tour pertenecen los pasajeros.

14. Equipo e Inventario

Almacenes

Crea almacenes para guardar tu equipo. Cada almacén tiene un nombre y una dirección.

Agregar Equipo

Ve a Inventario y haz clic en "Agregar Artículo". Ingresa: - Nombre — ej., "Equipos de Snorkel". - Almacén — dónde se guarda. - Cantidad Total — cuántos tienes. - Notas — cualquier información adicional.

Eliminar vs Deshabilitar un Activo

Al eliminar un activo del inventario: - Si el activo no tiene historial de uso ni reglas de plantilla, se elimina permanentemente. - Si el activo tiene historial de uso o está referenciado por reglas de plantilla, se deshabilita en su lugar. Aparece una insignia "Deshabilitado" en la lista de inventario, y el activo ya no aparecerá en las sugerencias de salida de equipo. - Puedes rehabilitar un activo deshabilitado en cualquier momento desde su página de detalle.

Registrar Salida de Equipo

En una tarjeta de tour, haz clic para agregar equipo. Selecciona el artículo e ingresa la cantidad que tu equipo llevará. La cantidad disponible disminuirá automáticamente.

Registrar Entrada de Equipo

Cuando tu equipo regrese, registra la cantidad devuelta. Si todo vuelve, la cantidad disponible se restaura. Si faltan algunos artículos, el sistema enviará una alerta a los administradores y despachadores.

Equipo Sugerido Automáticamente

Si tus plantillas de tour tienen reglas de equipo configuradas (ej., "1 equipo de snorkel por cada 2 pasajeros"), el sistema sugerirá las cantidades correctas cuando abras un tour.

15. Informes Financieros

La sección Informes (solo administradores) muestra los ingresos diarios, costos de personal, costos de vehículos y ganancia neta de tus tours.

Acceder a los Informes

Haz clic en Informes en la barra lateral (solo administradores).
Por defecto, se muestra el mes actual. Usa las flechas Mes Anterior / Mes Siguiente para navegar.
Para un período personalizado, usa los selectores de fecha Desde y Hasta y haz clic en Filtrar.

Columnas del Informe

Columna	Descripción
Fecha	La fecha del tour.
Tour	El nombre del tour.
Pax	Número de pasajeros.
Precio/Pax	Precio por pasajero establecido en el tour.
Ingresos	`Precio/Pax × Pax` (ingreso del tour).
Costo Personal	Suma de los costos de asignación de personal para el tour.
Costo Vehículo	Suma de los costos de vehículos para el tour.
Neto	`Ingresos - Costo Personal - Costo Vehículo`.

Cómo Afectan los Tours Cancelados a los Informes

Los tours cancelados se incluyen en el Informe Financiero — aparecen con una etiqueta "Cancelado" y todos sus valores (Ingresos, Costo Personal, Costo Vehículo, Neto) se muestran como $0.00 / "—". Esto evita que los tours cancelados distorsionen el informe con ingresos o ganancias engañosas.

Nota: Dado que los ingresos se fijan en $0.00, un tour cancelado que tenía asignaciones confirmadas antes de la cancelación no infla los totales del informe. El Informe de Pagos excluye los tours cancelados por completo.

Exportar a CSV

Haz clic en el botón CSV para descargar el informe actual como un archivo CSV, que puedes abrir en Excel, Google Sheets o cualquier aplicación de hoja de cálculo. El CSV incluye una fila de total al final.

Formato CSV: Las columnas son Fecha, Tour, Pax, Precio/Pax, Ingresos, Costo Personal, Costo Vehículo, Neto — una fila por tour, más una fila TOTAL final. Compatible con Excel, Google Sheets, QuickBooks, Xero y la mayoría de software de contabilidad.

16. Informe de Pagos

El Informe de Pagos (solo administradores) muestra un desglose detallado de lo que se debe pagar: compensación a personal freelance y costos de vehículos para un período determinado.

Acceder

Columna	Descripción
Fecha	La fecha del tour.
Tour	El nombre del tour.
Nombre	Nombre del freelance o vehículo.
Tipo	Personal (Gig/Por Hora) o Vehículo.
Tarifa	Tarifa por hora o gig para personal; costo por hora para vehículos.
Horas	Duración del tour en horas (— para personal Gig).
Total	Tarifa × Horas (o tarifa plana Gig).
Propietario	Propio o Contratado (solo vehículos).

Exportar a CSV

Haz clic en el botón CSV para descargar el informe para cualquier período de fechas.

Formato CSV: Las columnas son Fecha, Tour, Nombre, Tipo, Tarifa, Horas, Total, Propietario — una fila por asignación de personal freelance o vehículo. Compatible con Excel, Google Sheets, QuickBooks, Xero y la mayoría de software de contabilidad/nómina.

Qué se incluye: Solo se incluyen asignaciones confirmadas. Las asignaciones en borrador o rechazadas quedan excluidas. Si un tour se cancela después de que sus asignaciones fueron confirmadas, esas asignaciones se establecen en estado cancelado y no aparecerán en el Informe de Pagos. Esto evita pagar por trabajo cancelado.

17. Configuración de Usuario

La Configuración de Usuario comprende los ajustes personales del espacio de trabajo a los que puede acceder todo el personal haciendo clic en sus iniciales/avatar en el menú desplegable de la barra superior:

Configuración del Perfil (`/settings/profile`)

Actualiza tu Nombre y Apellido.
Elige tu Idioma Preferido de Interfaz (inglés, español, portugués, francés u holandés).
Gestiona tus Números de Contacto (Teléfono móvil, número de WhatsApp con selector de código de país con banderas).

Conexión Telegram (`/settings/telegram`)

(Solo visible cuando las notificaciones de Telegram están activadas por tu agencia) 1. Haz clic en Conectar a Telegram para generar un enlace de emparejamiento único (ej., https://t.me/MiAgenciaBot?start=ABC123). 2. Envía el enlace al bot de Telegram de tu agencia. 3. Una vez vinculado, recibirás notificaciones de asignación en tiempo real con botones interactivos ✅ Aceptar / ❌ Rechazar.

Conexión WhatsApp (`/settings/whatsapp`)

(Solo visible cuando las notificaciones de WhatsApp están activadas por tu agencia) 1. Haz clic en Generar Código de Emparejamiento para producir un código de 6 dígitos o un enlace directo wa.me. 2. Envía el código al número de WhatsApp Business registrado de tu agencia. 3. Una vez verificado, aparecerá una insignia verde de Conectado con tu número de teléfono. 4. Haz clic en Enviar Mensaje de Prueba para verificar la entrega del mensaje.

Cambiar Contraseña (`/settings/password`)

Actualiza tu contraseña de inicio de sesión ingresando tu contraseña actual seguida de tu nueva contraseña.

Configuración de Disponibilidad (`/settings/availability`)

Establece bloques personales de tiempo libre (vacaciones, citas médicas, días personales). Estos bloques evitan automáticamente que el sistema de auto-asignación te programe en esas fechas.

Selector de Agencia y Nueva Agencia

Si tu cuenta pertenece a múltiples agencias de tours, haz clic en el nombre de cualquier agencia en el menú desplegable para cambiar de espacio de trabajo al instante.
Haz clic en + Crear Nueva Agencia para configurar un nuevo espacio de trabajo de agencia bajo tu cuenta de usuario.

18. Configuración de la Cuenta

La Configuración de la Cuenta (Administración de la Agencia) es accesible solo para Administradores a través de Configuración en la navegación lateral izquierda (/settings/account).

Información de la Agencia y Plan de Suscripción

Actualiza el Nombre Oficial de la Agencia.
Consulta el nivel, ciclo de facturación y límites de funciones del Plan de Suscripción actual.

Canales de Notificación

Activa o desactiva los canales de envío de notificaciones de la agencia: Correo Electrónico, Telegram y WhatsApp. Múltiples canales pueden estar activos simultáneamente según tu plan.

Configuración del Bot de Telegram

Crea un bot de Telegram a través de @BotFather y obtén su token de API.
Ingresa el Token del Bot y el Nombre de Usuario del Bot.
Haz clic en Register Webhook para conectar el bot a PragmaticTours.

Configuración de WhatsApp Cloud API

Conectar con Meta (Embedded Signup): Haz clic en Conectar con Meta para autorizar tu cuenta de WhatsApp Business (WABA).
Configuración Manual: Ingresa tu Token de Acceso Permanente, ID de Número de Teléfono e ID de WABA.
Política de Webhook Centralizado: La URL del Webhook, el App Secret y el Webhook Verify Token son gestionados centralmente a nivel de infraestructura de la plataforma.

Gestión de Plantillas de Mensajes de WhatsApp

Cuando WhatsApp está activado para tu agencia, los administradores gestionan las plantillas de mensajes de Meta desde Configuración > Configuración de la Cuenta (/settings/account):

1. Categorías de Plantillas de Meta y Ventajas

Meta clasifica todas las plantillas de mensajes en tres categorías distintas. Seleccionar la categoría correcta afecta la velocidad de revisión, los costos de mensajería y la entregabilidad:

Categoría	Propósito y Contenido	Ventajas y Diferencias
`UTILITY`	Mensajes transaccionales y operativos directamente vinculados a una reserva activa, asignación, cancelación o enlace de cuenta (ej. asignaciones de tours, reprogramaciones, cancelaciones).	• Revisión Rápida: Aprobación en minutos por sistemas automatizados de Meta. • Menor Costo: Tarifa de mensajería más baja por conversación. • Alta Confiabilidad: Riesgo extremadamente bajo de bloqueos o reportes de spam porque el contenido es puramente operativo. • Sin Obligación de Botón de Baja: No requiere botones de cancelación de suscripción de marketing.
`MARKETING`	Mensajes promocionales, ofertas especiales, anuncios de nuevos tours, paquetes de temporada o campañas de reincorporación de clientes.	• Flexibilidad de Contenido: Permite lenguaje promocional, descuentos, botones de llamada a la acción y texto de venta. • Mayor Costo: Nivel de precio más alto por conversación. • Revisión Más Estricta: Sujeto a revisiones de contenido más estrictas por Meta y mayores tasas de reporte si se envían sin solicitud.
`AUTHENTICATION`	Códigos de acceso de un solo uso (OTP) y códigos de verificación de seguridad para autenticación multifactor.	• Estándar de Seguridad: Diseñado específicamente para códigos de seguridad con botones de copia instantánea.

2. Eventos del Sistema y Disparadores de Notificación

PragmaticTours envía automáticamente mensajes de WhatsApp cuando ocurren eventos específicos del sistema:

Evento del Sistema	`template_type` Mapeado	Condición Disparadora	Variables Posicionales y Contenido	Botones Interactivos
Asignación de Tour	`tour_assignment`	Se dispara automáticamente cuando un despachador o el auto-asignador confirma la asignación de un miembro del personal a un tour programado.	`{{1}}` Nombre del Tour `{{2}}` Fecha y Hora de Recogida `{{3}}` Dirección de Recogida	Botones interactivos `✅ Aceptar` / `❌ Rechazar`
Cancelación de Tour	`tour_cancellation`	Se dispara automáticamente cuando un administrador o despachador cancela un tour programado.	`{{1}}` Nombre del Tour `{{2}}` Fecha `{{3}}` Motivo de Cancelación	Ninguno
Reprogramación de Tour	`tour_reschedule`	Se dispara automáticamente cuando un tour se reprograma a una nueva fecha/hora.	`{{1}}` Nombre del Tour `{{2}}` Fecha Anterior `{{3}}` Nueva Fecha y Hora de Recogida	Ninguno
Vincular WhatsApp	`whatsapp_linked`	Se dispara cuando un miembro del personal vincula con éxito su cuenta de WhatsApp.	`{{1}}` Nombre del Miembro del Personal `{{2}}` Nombre de la Agencia	Ninguno
Respuesta de Chat	`chat_reply`	Se dispara durante intercambios de chat interactivos entre el personal y el servicio de WhatsApp.	`{{1}}` Mensaje de Respuesta	Ninguno

3. Requisitos de Formato y Aprobación de Meta

Todas las plantillas de WhatsApp deben ser revisadas y aprobadas por Meta antes de que puedan ser utilizadas para enviar mensajes salientes.
Las variables del cuerpo deben comenzar en {{1}} e incrementarse secuencialmente ({{1}}, {{2}}, {{3}}).
Se deben proporcionar valores de muestra obligatorios para cada variable.

4. Crear Plantillas Predeterminadas

Selecciona un idioma y haz clic en Crear Plantillas Predeterminadas para enviar plantillas estándar preformateadas (tour_assignment_v1, tour_cancellation_v1) a Meta.

5. Crear Plantillas Personalizadas y Mapear Eventos del Sistema

Despliega Crear Nueva Plantilla en Configuración > Configuración de la Cuenta.
Nombre de la Plantilla: Cadena única en minúsculas aceptada por Meta (ej. invitacion_aventura_caribe_2026).
Propósito / Evento del Sistema: Selecciona el evento del sistema de destino en el menú desplegable (ej. Asignación de Tour). Esto mapea el nombre personalizado de Meta directamente a los disparadores internos del sistema (template_type: "tour_assignment").
Cuerpo y Variables: Ingresa el texto del mensaje usando variables posicionales secuenciales ({{1}}, {{2}}, {{3}}).

6. Ciclo de Vida de Sobrescritura y Plantillas Personalizadas

Una vez que Meta apruebe la versión personalizada (estado 🟢 APPROVED), PragmaticTours cambiará automáticamente para usar la versión de plantilla aprobada más reciente para todas las notificaciones salientes posteriores.

Claves API (Solo Administradores)

Los administradores pueden generar claves API para permitir que sistemas externos interactúen con tus datos de PragmaticTours mediante programación a través de Configuración > Claves API (/api_keys).

Cancelación de Cuenta y Exportación de Datos

Haz clic en Restaurar Cuenta.
Tu cuenta se restaurará completamente y podrás seguir usando el espacio de trabajo como antes.

Tu administrador de agencia también puede gestionar cancelaciones y restauraciones. Para ayuda, contacta a nuestro equipo de soporte.

Notificaciones en Tiempo Real

Los administradores y despachadores ven un icono de campana en la barra superior. Un distintivo rojo muestra cuántas notificaciones no leídas tienes. Haz clic en la campana para abrir el menú desplegable:

Las notificaciones aparecen en tiempo real — no necesitas recargar la página.
Cada notificación muestra la inicial de la persona, un mensaje y cuándo ocurrió.
Los elementos no leídos tienen un fondo azul.
Haz clic en "Ver todas las notificaciones" para ver el historial completo.
Abrir el menú desplegable marca automáticamente todas las notificaciones como leídas.

Recibes notificaciones por: - Nuevas asignaciones — cuando se asigna personal a un tour. - Aceptaciones — cuando un miembro del personal acepta una asignación. - Rechazos — cuando un miembro del personal rechaza una asignación. - Cancelaciones — cuando un tour es cancelado. - Reprogramaciones — cuando un tour se mueve a una nueva fecha.

19. Referencia de API (v1)

PragmaticTours proporciona una API REST para que sistemas externos (CRMs, motores de reservas, widgets web, OTAs e integraciones personalizadas) gestionen datos de tours, plantillas y reservas de forma programática. Todos los endpoints devuelven JSON.

Autenticación

Las solicitudes se pueden autenticar mediante: - Clave API: Authorization: Bearer pt_tu_clave_api (se genera en Configuración > Claves API). - Encabezado de Token de Cuenta: X-Account-Token: tu_identificador_de_cuenta

URL Base

https://tuagencia.pragmatictours.com/api/v1

Resumen de Endpoints

Método	Ruta	Descripción
`GET`	`/api/v1/tour_templates`	Listar plantillas de tours activas (para seleccionar IDs de plantilla)
`GET`	`/api/v1/tour_templates/:id`	Obtener detalles de una plantilla de tour específica
`POST`	`/api/v1/bookings`	Crear una nueva reserva (`pending` o `confirmed`)
`PATCH`	`/api/v1/bookings/:id`	Actualizar el estado de una reserva (`confirmed`, `cancelled`, `pending`)
`GET`	`/api/v1/bookings/:id`	Obtener detalles de una reserva específica
`GET`	`/api/v1/bookings`	Listar todas las reservas
`GET`	`/api/v1/tours`	Listar tours (con filtros opcionales)
`GET`	`/api/v1/tours/:id`	Obtener un tour con todos los detalles
`POST`	`/api/v1/tours`	Crear un nuevo tour
`GET`	`/api/v1/me`	Verificar estado de sesión (usado por la app móvil)

API de Plantillas de Tours (Tour Templates)

Utiliza GET /api/v1/tour_templates para listar todas las plantillas de tours activas. Esto permite a los sistemas de reserva externos consultar los tours disponibles y obtener su id o code antes de registrar una reserva.

curl -H "X-Account-Token: company-a" \
  https://tuagencia.pragmatictours.com/api/v1/tour_templates

API de Reservas (Bookings) e Reglas de Integración

[!IMPORTANT] Política de Pasarela de Pagos: PragmaticTours NO procesa pagos ni incluye pasarelas de pago internas. Los operadores cobran a través de su propio procesador de pagos externo (Stripe, PayPal, transferencia bancaria, POS) y cambian el estado de la reserva a "confirmed" una vez recibido el pago.

[!NOTE] Integración con la Programación y Manifiesto de Tours: - Establecer el estado en "confirmed" crea y programa automáticamente un tour en el panel de control para esa fecha (si aún no existe). - Las reservas confirmadas agregan automáticamente al cliente principal y pasajeros al Manifiesto de Pasajeros del tour. - Las reservas pendientes ("pending") no crean tours en el panel de control hasta ser confirmadas.

Crear una Reserva (Ejemplo)

curl -X POST https://tuagencia.pragmatictours.com/api/v1/bookings \
  -H "Content-Type: application/json" \
  -H "X-Account-Token: company-a" \
  -d '{
    "tour_template_id": 1,
    "booking_date": "2026-10-15",
    "status": "confirmed",
    "customer": {
      "full_name": "Maria Santos",
      "email": "maria.santos@example.com",
      "phone": "+507 6555-1234",
      "language_preference": "es"
    },
    "passengers": [
      { "passenger_name": "Maria Santos", "age_category": "adult" },
      { "passenger_name": "Carlos Santos", "age_category": "adult" }
    ]
  }'

Actualizar el Estado de una Reserva (Ejemplo)

curl -X PATCH https://tuagencia.pragmatictours.com/api/v1/bookings/101 \
  -H "Content-Type: application/json" \
  -H "X-Account-Token: company-a" \
  -d '{
    "booking": {
      "status": "confirmed"
    }
  }'

Listar Tours

GET /api/v1/tours

Parámetros de consulta opcionales:

Parámetro	Tipo	Descripción
`from`	date	Filtrar por fecha de inicio del rango
`to`	date	Filtrar por fecha de fin del rango
`template_id`	integer	Filtrar por plantilla de tour
`status`	string	Filtrar por estado

Ejemplo:

curl -H "Authorization: Bearer pt_tu_clave" \
  "https://tuagencia.pragmatictours.com/api/v1/tours?from=2026-08-01&to=2026-08-31"

Obtener un Tour

GET /api/v1/tours/:id

Devuelve el tour con todos los campos. Los tours de varios días incluyen un arreglo child_tours.

Crear un Tour

POST /api/v1/tours
Content-Type: application/json

Ejemplo de un día:

{
  "tour": {
    "tour_template_id": 3,
    "pax_count": 20,
    "date": "2026-08-20",
    "pickup_time": "08:00",
    "pickup_address": "Hotel Lobby",
    "transit_duration_minutes": 30,
    "price_per_pax": 75.0
  }
}

Ejemplo de varios días (crea tours hijos automáticamente):

{
  "tour": {
    "tour_template_id": 7,
    "pax_count": 15,
    "start_date": "2026-09-10",
    "end_date": "2026-09-13"
  }
}

Campo	Un día	Varios días	Auto-completado
`tour_template_id`	Requerido	Requerido	—
`pax_count`	Requerido	Requerido	—
`date`	Requerido	—	—
`start_date`	—	Requerido	—
`end_date`	—	Requerido	—
`pickup_time`	Opcional	—	Sí
`pickup_address`	Opcional	—	Sí
`transit_duration_minutes`	Opcional	—	Sí
`price_per_pax`	Opcional	—	Sí
`category`	Opcional	Opcional	Auto-detected
`compensation_type`	Opcional	—	Default: `gig`

Respuestas de Error

Código	Significado
`400`	Solicitud incorrecta — falta un parámetro requerido
`401`	No autorizado — clave API faltante o inválida
`404`	No encontrado — el recurso no existe
`422`	No procesable — errores de validación

Los cuerpos de error contienen un objeto JSON con una clave error. Según el tipo de error, el valor puede ser un texto o un arreglo de textos:

400 Solicitud incorrecta: { "error": "param is missing" } (texto)
401 No autorizado: { "error": "Invalid or revoked API key" } (texto)
422 Error de validación: { "error": ["La plantilla es obligatoria", "El número de pasajeros debe ser mayor o igual a 0"] } (arreglo)

Operaciones de Agencia Receptor / DMC (Destination Management Company)

1. Cumplimiento de Tours con Revendedores y Proveedores Externos

Tipos de Cumplimiento: Las plantillas de tour y los tours agendados soportan fulfillment_type (in_house para operación con flota y guías propios, o reseller para servicios subcontratados con proveedores externos).
Plantillas para Productos Relevados/Revendidos: Al crear o editar una TourTemplate en el Catálogo de Productos, seleccione Tipo de Operación: Reventa (Proveedor Externo) en el Paso 1. Opcionalmente asigne un Proveedor por Defecto para preasignar automáticamente charteadores o empresas de transporte.
Protección del Optimizador: Los tours de revendedor omiten automáticamente las reglas de auto-asignación de vehículos/conductores y los optimizadores de Horas de Servicio (HOS), evitando conflictos de flota interna.
Estilo Visual en Despacho: Los tours de revendedor se muestran con estilo pizarra (bg-slate-50 border-l-4 border-slate-400 text-slate-800) e insignias del proveedor en el Despacho Visual.

2. Gestión de Proveedores Externos y Vouchers de Servicio

Directorio de Proveedores: Acceda a Proveedores Externos directamente desde la barra de navegación lateral (bajo Gestor de Flota / Catálogo).
Gestión CRUD: Cree, edite y categorice proveedores externos (barcos charter, contratistas de transporte, sindicatos de guías) con datos de contacto, teléfonos de emergencia, tarifas netas por defecto y preferencia de entrega de voucher (WhatsApp o Correo).
Vouchers Automatizados: Generación automática de registros ServiceVoucher (VOUCH-XXXXXXXX) vía Email o WhatsApp, siguiendo el ciclo de vida pending → confirmed / rejected.

3. Jerarquía B2B de Agencias y Agentes

Agregar una Agencia B2B: Desde la sección de Clientes (/customers), haz clic en Agregar Cliente, selecciona Tipo de Cliente: Revendedor (Agente a Comisión), configura el porcentaje de comisión y nivel de tarifas, y guarda el registro.
Filtros del Directorio de Clientes: Utilice las pestañas de navegación secundaria en la lista de Clientes para alternar entre Todos los Clientes, Agencias B2B y Revendedores, y Pasajeros Estándar.
Tipos de Cliente: Los clientes se clasifican en standard (pasajeros individuales o subagentes) o reseller (agencias B2B o agentes a comisión).
Vínculo con Agencia Padre: Al crear o editar un cliente/agente, seleccione su Agencia Padre (agency_id) y su Nivel de Tarifas (gross_markup o net_wholesale).
Exclusión de Lista de Pasajeros: Los clientes revendedores/agencias no se incluyen en el conteo de pasajeros del tour ni en la asignación de asientos del manifiesto.

4. Flujo de Trabajo para Hoteles, Desglose de Habitaciones y Manifiesto de Alojamiento

Configuración de Proveedor Hotelero: Registre hoteles en Proveedores Externos con Categoría: Hotel (ej., Gamboa Rainforest Resort, JW Marriott Panama). Defina el correo de reservas, número de WhatsApp y la tarifa neta por defecto (default_net_rate, ej., $120.00/noche). Los datos de contacto se delegan para evitar duplicación de campos.
Catálogo de Alojamientos y Tipos de Habitación:
Vincule registros de Accommodation (lugares de pernocta y puntos de recogida) con su Proveedor Hotelero (supplier_id).
Configure categorías de RoomType para cada alojamiento (ej., Suite King Deluxe, Habitación Doble Queen, Executive Ocean Suite) con max_occupancy, bed_configuration, default_net_rate y currency.
Alojamientos en Plantillas de Tours Multidía:
Dentro del plan diario de una plantilla TourTemplate multidía, adjunte opcionalmente los detalles del alojamiento nocturno mediante el panel de Alojamiento Nocturno.
Seleccione el RoomType preferido, el Plan de Alimentación (Solo habitación, Alojamiento y Desayuno, Media Pensión, Pensión Completa) y la cantidad de habitaciones (room_count).
Desglose de Habitaciones y Precios en Vouchers de Servicio:
Al confirmar un paquete multidía o estadía en hotel, PragmaticTours genera vouchers ServiceVoucher digitales (VOUCH-XXXXXXXX) enviados por WhatsApp o Correo al departamento de reservas del hotel.
Los vouchers detallan automáticamente el desglose de tipos de habitación, horas de check-in/out, número de huéspedes y tarifa neta total garantizada.
Exportación del Manifiesto de Alojamiento (Rooming Manifest):
Los despachadores pueden descargar un archivo CSV estructurado del Manifiesto de Alojamiento directamente desde cualquier tarjeta de tour en el panel de control (/tours/:id/rooming_manifest.csv).
La exportación incluye número de noche, contacto del hotel, tipo de habitación, plan de alimentación, cantidad de habitaciones y etiquetas de ocupación por pasajero.
Respaldo de Coordenadas para el Solucionador de Despacho (OR-Tools):
Las coordenadas del alojamiento nocturno (latitude, longitude) son utilizadas por el optimizador de auto-asignación como destino final del día y origen del día siguiente.
Si el alojamiento no especifica coordenadas, el optimizador utiliza suavemente la ubicación de la actividad o las coordenadas de la central (depot), asegurando cero interrupciones en el motor de despacho.

5. Hitos de Pago e Intercambio Multimoneda

Hitos de Pago: Seguimiento de hitos deposit, second_payment y final_balance por reserva con fechas de vencimiento y estados (pending, paid, overdue).
Moneda Base y Facturación: Conversión de moneda dual (total_price_base, commission_amount_base) para operaciones DMC internacionales.

¿Necesitas Ayuda?

Si tienes preguntas o encuentras problemas, contacta a tu administrador de agencia. Ellos pueden gestionar tu cuenta, ajustar tus permisos o ayudarte con cualquier duda sobre los flujos de trabajo.