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
Cotizaciones, Propuestas y Pre-Facturas
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
Reservas	Administradores, Despachadores	Gestionar reservas y pasajeros
Cotizaciones y Propuestas	Administradores, Despachadores	Diseñar propuestas multidía, pre-facturas y convertir a tours
Clientes	Administradores, Despachadores	Gestionar directorio de clientes y agencias socias B2B
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. Cotizaciones, Propuestas y Pre-Facturas

El módulo de Cotizaciones y Propuestas (accesible para Administradores y Despachadores) es el motor comercial integral de PragmaticTours. Permite a los operadores turísticos, agencias receptivas (DMCs) y empresas de transporte turístico diseñar propuestas de itinerarios a medida (de un día o multidía), calcular con precisión matemática los costos unitarios y márgenes de rentabilidad, generar presentaciones visuales para clientes y pre-facturas proforma, y convertir reservas aprobadas directamente en tours operativos en tu calendario de despacho.

Fundamentos del Sector: En Qué se Basa el Motor de Cotizaciones

Históricamente, en la industria del turismo receptivo y agencias de viajes, la elaboración de itinerarios personalizados y presupuestos se ha gestionado mediante herramientas desconectadas: 1. Hojas de Cálculo Complejas en Excel (.xlsx): Empleadas por diseñadores de producto y cotizadores para calcular tramos de transporte, viáticos de guías, tarifas netas de hotel, entradas a parques nacionales y matrices de precios por volumen de pasajeros. 2. Documentos de Propuesta en Word (.docx): Usados por agentes de ventas para redactar la narrativa comercial del viaje, fotos de portada, inclusiones, exclusiones y políticas de viaje. 3. Plantillas de Pre-Factura Proforma en Word (.docx): Utilizadas por el departamento de administración y cobranzas para solicitar transferencias bancarias, detallando cuentas bancarias y deducciones de comisiones a agencias mayoristas.

Aunque las hojas de cálculo son flexibles, generan graves fricciones en la operación diaria: - Vulnerabilidad de Fórmulas: Modificaciones involuntarias en celdas de Excel provocan errores de cálculo, ventas por debajo del costo y pérdida de rentabilidad. - Desconexión con Flota y Proveedores: Las tarifas en hojas estáticas quedan desactualizadas frente a la disponibilidad real de vehículos en flota, fluctuaciones estacionales de hoteles o aumentos en tarifas de subcontratistas. - Doble Digitado y Errores Humanos: Al confirmarse un itinerario en Word, el equipo debe transcribir manualmente cada día, pasajero, hotel y servicio al sistema operativo o pizarra de despacho.

PragmaticTours unifica el motor de cálculo financiero, la presentación comercial ante el cliente y el calendario de despacho operativo en un flujo continuo y automatizado.

flowchart TD
    SPREADSHEET["Costeo Tradicional en Excel (.xlsx)\nCostos fijos, entradas variables, hotel DBL/SGL,\nabsorción de tour leader, tramos de volumen"] --> ENGINE["Motor Financiero PragmaticTours (CalculateTotals)\nCascada matemática automatizada y termómetro de margen"]
    WORD_DOC["Propuesta Tradicional en Word (.docx)\nNarrativa, fotos de portada, tabla de itinerario"] --> PROPOSAL["Canvas Web y PDF Chromium de la Propuesta\nDiseño responsive con Tailwind, exportación instantánea"]
    PRE_DOC["Pre-Factura Tradicional en Word (.docx)\nProforma, datos bancarios, comisiones B2B"] --> PREINVOICE["Canvas Web y PDF de Pre-Factura\nCobro comercial formal con deducción de agencia"]
    ENGINE --> PROPOSAL
    ENGINE --> PREINVOICE
    PROPOSAL --> APPROVE["El Cliente Aprueba la Propuesta"]
    PREINVOICE --> APPROVE
    APPROVE --> DISPATCH["Conversión en 1 Clic (ApproveAndSchedule)\nCreación automática de tours, manifiestos y despacho"]

El Motor Matemático de Cascada de Costos

La lógica detrás del servicio Quotes::CalculateTotals de PragmaticTours implementa el modelo financiero estándar de los DMCs internacionales:

$$\text{Costo Neto Estimado Total} = \text{Costos Fijos} + \text{Costos de Adultos} + \text{Costos Niños Cama Extra} + \text{Costos Niños Compartiendo} + \text{Costos Infantes} + \text{Costos Absorbidos del Tour Leader}$$

Costos Fijos de Grupo ($\text{Costo}_{\text{fijo}}$): Gastos que no varían con la cantidad de pasajeros, tales como fletes de autobuses, minibuses o vans privadas, alquiler de lanchas o botes, honorarios diarios del guía principal, viáticos del chofer y permisos de ingreso vehicular.
Costos Variables por Pasajero ($\text{Costo}_{\text{variable}}$): Gastos que se multiplican directamente por cada viajero, incluyendo boletos a parques nacionales, entradas a museos, comidas en restaurantes, boletos aéreos domésticos, degustaciones de café o cacao y kits de bienvenida. Cada rubro puede clasificarse como Tarifa Adulto o Tarifa Niño.
Motor de Costeo para Niños y Familias:
En viajes familiares, los menores tienen dinámicas de costo sustancialmente distintas a los adultos:
- Niños con Cama Extra / Sofá Cama (children_with_bed_count): Los hoteles aplican un suplemento diario por cama plegable o sofá cama (child_extra_bed_cost en RoomType).
- Niños Compartiendo Habitación / Cama Existente (children_sharing_count): Los hoteles no cobran adicional o aplican una tarifa mínima de servicio (child_sharing_room_cost en RoomType).
- Infantes menores de 2 años (infant_count): Viajan gratis o abonan costos mínimos de seguro/administración (cost_per_infant).
- Registro de Edades (children_ages): Lista de edades separadas por coma para el rooming list de hoteles, emisión de boletos de avión y entradas a parques.
Estrategia de Absorción de Costos Fijos (absorb_fixed_costs_in_adults):
- Activado (Recomendado - Estándar Familiar): Los costos fijos del transporte y guías son absorbidos exclusivamente por los adultos de pago. Los niños solo abonan sus gastos marginales (cama extra de hotel, menú infantil, boleto de niño y pasaje aéreo infantil + margen).
- Desactivado (Reparto Equitativo): Los costos fijos se dividen proporcionalmente entre todos los participantes (adultos y niños).
Tarifas de Alojamiento y Base de Ocupación:
Base Doble Compartida (DBL): Para adultos compartiendo habitación doble, el costo neto por persona y noche se calcula como: $$\text{Tarifa DBL por Adulto} = \frac{\text{Tarifa Neta de la Habitación}}{2}$$
Suplemento de Habitación Individual (SGL): Para viajeros solos que requieren habitación privada, el suplemento cubre la diferencia completa de la habitación individual frente a la base compartida: $$\text{Suplemento SGL} = (\text{Tarifa Neta SGL} - \text{Tarifa DBL Compartida}) \times (1 + \text{Margen \%})$$
Absorción de Tour Leader / Acompañante de Grupo de Cortesía (FOC):
En viajes grupales organizados, las agencias mayoristas del exterior frecuentemente incluyen un Tour Conductor o Líder de Grupo libre de costo (Free of Charge - FOC, foc_leader_count).
El líder puede alojarse en un hotel o habitación individual independiente (leader_accommodation_id, leader_room_type_id).
La habitación individual del líder, sus comidas de guía, vuelos internos y entradas se prorratean y absorben entre los adultos de pago: $$\text{Costo de Leader por Adulto} = \frac{\text{Total Gastos del Leader FOC}}{\text{Cantidad Efectiva de Adultos}}$$
Margen de Ganancia Bruta y Precios de Venta Diferenciados:
El sistema calcula costos netos y precios sugeridos independientes para:
- Adultos (Habitación Doble)
- Niños con Cama Extra
- Niños Compartiendo Cama Existente
- Infantes
Puedes adoptar los precios sugeridos con un solo clic o fijar tarifas de venta comerciales personalizadas por categoría.
Matriz Dinámica de Descuento por Volumen (Tramos de Pasajeros):
Al crecer el grupo, los costos fijos se diluyen. PragmaticTours calcula automáticamente la matriz de tarifas escalonadas para tramos estándar (ej. 6–7 pax, 8–9 pax en van Hiace; 10–11 pax, 12–16 pax en minibús Coaster), generando precios exactos en base DBL, SGL, Niño con Cama y Niño Compartiendo.
Comisiones para Agencias B2B y Revendedores:
Para reservas intermediadas por agencias aliadas o mayoristas, el sistema deduce el porcentaje pactado de comisión (ej. 10% o 15%) en la pre-factura, mostrando claramente el total bruto de venta y el monto neto a transferir a tu empresa.

El Flujo de 5 Pasos de la Cotización

Cada cotización avanza a través de una barra de etapas visible en su panel superior:

stateDiagram-v2
    [*] --> 1_Configuracion: Crear Cotización (/quotes/new)
    1_Configuracion --> 2_Itinerario: Actividades y Hoteles Día a Día
    2_Itinerario --> 3_Costeo: Costos Netos y Márgenes Comerciales
    3_Costeo --> 4_Enviada: Enviar Propuesta o Pre-Factura
    4_Enviada --> 5_Aprobada: Cliente Aprueba
    5_Aprobada --> Despachada: Convertir en Tour Operativo
    4_Enviada --> Cancelada: Cliente Desiste

Etapa del Flujo	Estado en Sistema (`status`)	Descripción y Acciones
1. Trip Setup (Configuración)	`draft`	Definición de parámetros logísticos: fechas de viaje, días de duración, número de pasajeros de pago, líderes FOC, cliente, agencia B2B y divisa.
2. Itinerary & Activities (Itinerario)	`draft`	Construcción de las jornadas diarias, importación de plantillas de tours del catálogo, selección de hoteles y habitaciones, plan de comidas (D/A/C) y asignación de rubros.
3. Calculated & Costed (Costeo Comercial)	`completed`	Análisis de la cascada de costos netos acumulados, definición del margen de ganancia %, ajuste manual de tarifas, anticipos y verificación de la matriz de volumen.
4. Proposal / Pre-Invoice Sent (Enviada)	`sent` / `pre_invoice_sent`	Compartición del canvas web interactivo, generación de PDFs en alta resolución o despacho por correo electrónico con el PDF adjunto.
5. Approved & Scheduled (Aprobada y Despachada)	`approved`	Confirmación formal y conversión en 1 clic a tours operativos programados en el calendario de despacho.

Termómetro de Rentabilidad y Métricas Financieras

En la cabecera de la cotización, PragmaticTours presenta tarjetas KPI en tiempo real: - Costo Neto Estimado: Costo operativo total acumulado y costo unitario por pasajero de pago. - Margen / Markup: Porcentaje de margen aplicado y ganancia bruta proyectada en moneda real. - Precio por Persona: Tarifa de venta unitaria por viajero en la divisa seleccionada. - Total Cotizado: Valor global del paquete ofrecido al cliente. - Comisión de Agencia: Porcentaje y monto descontado correspondiente a la comisión del intermediario B2B. - Depósito Requerido: Anticipo mínimo solicitado (por defecto 30% o monto configurable) para asegurar la reserva. - Indicador de Salud Financiera: - Alerta de Pérdida (<10% margen): Advierte sobre cotizaciones en riesgo de rentabilidad negativa. - Margen Ajustado (10%–25% margen): Rentabilidad moderada que exige un estricto control de costos operativos. - Margen Saludable (≥25% margen): Rango comercial óptimo para operaciones receptivas.

Guía Paso a Paso: Creación y Estructuración de una Cotización

Paso 1: Configurar la Logística Inicial (`/quotes/new`)

Dirígete a Cotizaciones y Propuestas en el menú lateral (/quotes).
Haz clic en el botón "+ Nueva Cotización".
Completa los parámetros iniciales:
Título: Nombre atractivo y descriptivo del paquete (ej. "Circuito de 7 Días: Selva Panameña y Playas de San Blas").
Cliente: Selecciona un contacto existente o activa "Nuevo Cliente" para registrar nombre, email, teléfono e idioma de preferencia directamente en el formulario.
Agencia B2B / Revendedor (Opcional): Si la cotización es para un mayorista o agencia aliada, elígelo para calcular automáticamente sus deducciones por comisión.
Fecha de Inicio y Duración (Días): Ingresa la fecha de llegada y la cantidad de días. La fecha de finalización se calcula de forma automática.
Demografía de Pasajeros y Familias:
- Adultos: Cantidad de pasajeros adultos.
- Niños (2–11 años): Cantidad total de niños.
- Niños con Cama Extra / Sofá Cama: Menores que requieren cama plegable adicional en la habitación.
- Niños Compartiendo Cama Existente: Menores que comparten la cama existente de los padres sin costo de habitación adicional.
- Infantes (<2 años): Bebés en brazos o cuna.
- Edades de los Niños: Lista separada por comas (ej. 10, 5) para rooming lists y boletos aéreos.
- Líderes de Cortesía (FOC Leaders): Cantidad de acompañantes cuyos gastos de habitación individual y actividades serán absorbidos por los adultos.
Moneda: Divisa de cobro (ej. USD, EUR, GBP, CAD).
Plantilla de Tour con Selector de Búsqueda: Utiliza el combobox interactivo para buscar y filtrar plantillas de tour del catálogo por nombre o código en el Día 1.
Hotel del Grupo y Hotel del Tour Leader (Día 1): Selecciona el hotel y habitación para el grupo, y si aplica, un hotel y habitación individual independiente para el Tour Leader.
Haz clic en Crear Cotización.

Paso 2: Constructor de Itinerario Día por Día

Dentro del espacio de trabajo de la cotización (/quotes/:id), el programa se organiza en fichas cronológicas de cada día:

1. Cabecera del Día y Controles Rápidos

Cada ficha muestra el número de día (D1, D2...), fecha del calendario, título del día, comidas y hoteles: - Insignias de Plan de Alimentación: Indicadores rápidos de B (Desayuno), L (Almuerzo) y D (Cena). - Insignias de Alojamiento: Muestra el hotel asignado para los viajeros y, de forma separada, el hotel y habitación individual del Tour Leader. - Horas de Tránsito: Horas estimadas de transporte terrestre o marítimo durante la jornada.

2. Auto-Poblado de Días con Buscador Interactivo de Plantillas

Para acelerar el diseño del itinerario, utiliza el Buscador de Plantillas de Tour en cualquier día: - Escribe palabras clave (ej. "Canal", "Aeropuerto", o código "PC-01") para filtrar al instante tours de tu catálogo. - PragmaticTours importa automáticamente el título, descripción detallada, horas de traslado, asignación de guías, tipo de vehículo requerido, entradas a atracciones y almuerzo directamente a los rubros del día.

3. Gestión de Rubros de Costo (`QuoteItem`)

En cada jornada puedes añadir y ajustar conceptos de costo individuales: - Categorías Disponibles: - Transport / Vehicle: Vans privadas, minibuses, autobuses o traslados aeropuerto-hotel. - Boat / Water Taxi: Lanchas rápidas, catamaranes o ferries. - Lead Tour Guide: Guía principal bilingüe o naturalista líder. - Assistant Guide / Naturalist: Guía asistente, baquiano o guía local comunitario. - Driver / Chauffeur: Honorarios y viáticos del chofer profesional. - Attraction / Entrance Ticket: Entradas a parques nacionales, museos, reservas o comarcas. - Airplane Ticket / Domestic Flight: Vuelos comerciales internos o vuelos chárter. - Meal / Restaurant: Almuerzos campestres, cenas de bienvenida o box lunches. - Perk / Amenity: Aguas frías, refrigerios, toallitas húmedas o sombreros de cortesía. - Hotel / Lodging Room: Habitaciones adicionales o tarifas de day-use. - Custom Expense y Discretionary: Gastos imprevistos u operativos específicos. - Tipos de Costo y Categorías de Tarifa: - Por Pasajero (per_pax): Se multiplica por la cantidad de viajeros. - Tarifa Adulto vs. Tarifa Niño (rate_category): Boletos de atracciones, comidas en restaurantes y vuelos domésticos pueden clasificarse como Tarifa Adulto o Tarifa Niño para no mezclar costos infantiles con tarifas adultas. - Costo Fijo de Grupo (per_group_flat): Tarifa fija global sin importar la cantidad de personas (ej. flete de bus de $350). - Por Unidad (per_unit): Multiplicado por una cantidad fija establecida. - Asignación de Proveedores: Vincula el rubro a un proveedor registrado. El menú desplegable filtra automáticamente a los proveedores que pertenecen a la categoría elegida. - Opciones de Visualización y Absorción: - Incluir en la Propuesta (include_in_proposal): Marcado por defecto. Determina si el concepto aparece en la viñeta de "Incluye" del documento para el cliente. Puedes desmarcarlo en gastos internos que no deben revelarse al cliente final. - Costo de Tour Leader (is_leader_cost): Activa esta casilla si el gasto corresponde exclusivamente al acompañante FOC (ej. vuelo interno del líder o su almuerzo). Estos rubros se aíslan y se absorben entre los adultos de pago.

4. Selector de Alojamiento y Habitaciones

En la base de cada día, abre el Selector de Hoteles: - Hotel y Habitación para Viajeros: Selecciona el hotel asociado y tipo de habitación (ej. Habitación Doble Estándar). El sistema aplica la tarifa en base doble ($ \text{Tarifa Neta} / 2 $) a los adultos y aplica la tarifa neta específica de cama extra o habitación compartida para niños. - Hotel y Habitación para el Tour Leader: Selecciona el hospedaje del líder (en el mismo hotel o en un hotel para tripulaciones/guías con habitación individual). La tarifa neta completa de la habitación sencilla se suma a la bolsa de costos absorbidos.

5. Agregar Días Adicionales

Haz clic en "+ Agregar Siguiente Día al Itinerario" al final del listado para generar el Día 2, Día 3, etc., heredando automáticamente fechas correlativas y hoteles sugeridos.

Paso 3: Centro de Costeo Comercial y Fijación de Márgenes

En la parte inferior de la cotización se encuentra el Centro de Precios Comerciales (#commercial-pricing):

Tarjetas de Composición de Costos Netos:
Costos Fijos: Sumatoria de fletes de transporte, viáticos de choferes y guías principales.
Costos Variables / Pax: Total de entradas, comidas y boletos aéreos dividido entre los pasajeros de pago.
Alojamiento (Hoteles): Gasto total en hotelería de clientes (habitaciones dobles + camas extras/niños compartiendo).
Absorción de Tour Leader FOC: Total de hospedaje individual, vuelos y viáticos del líder, indicando exactamente cuánto absorbe cada adulto de pago.
Costo Neto Total / Pax: Punto de equilibrio financiero exacto por pasajero para operar el paquete.
Definición de Márgenes y Precios Comerciales por Categoría:
Margen de Ganancia %: Ingresa el margen bruto proyectado (ej. 28.0%). El sistema calcula de inmediato los precios sugeridos por categoría.
Precio Adulto Cotizado: Adopta el precio sugerido o ingresa una tarifa personalizada.
Tarjeta de Precios Comerciales para Niños e Infantes:
- Casilla de Absorción de Costos Fijos (absorb_fixed_costs_in_adults): Si está marcada, los costos fijos de vehículo y guía los absorben los adultos, y los niños solo pagan sus costos directos. Si se desmarca, los costos fijos se prorratean por igual entre todos los participantes.
- Precio Niño Cama Extra: Tarifa de venta para niños que usan cama adicional o sofá cama.
- Precio Niño Compartiendo: Tarifa con descuento para niños que comparten cama con los padres.
- Precio Infante: Tarifa nominal o $0 para menores de 2 años.
Comisión de Agencia %: Si la venta proviene de un mayorista o agencia B2B, define el porcentaje de comisión acordado (ej. 12.0%) para deducirlo en la pre-factura.
Depósito Requerido %: Porcentaje de anticipo solicitado (ej. 30.0%) para bloquear reservas y servicios.
Matriz Dinámica de Descuentos por Volumen:
Analiza la tabla de tarifas dinámicas para grupos de diferentes tamaños (6–7 PAX, 8–9 PAX, 10–11 PAX, 12–16 PAX), desglosando precios en Habitación Individual (SGL), Doble Compartida (DBL), Niño con Cama Extra y Niño Compartiendo.
Puede activarse/desactivarse en la propuesta mediante la casilla "Incluir Tabla de Inversión y Tarifas".

Documentos para el Cliente: Propuesta vs. Pre-Factura

PragmaticTours genera dos presentaciones documentales adaptadas a momentos específicos del ciclo comercial:

Aspecto	Propuesta Comercial (`/quotes/:id/proposal`)	Pre-Factura Proforma (`/quotes/:id/pre_invoice`)
Objetivo Principal	Inspirar y Vender: Presentación atractiva del itinerario diseñada para enamorar al cliente y cerrar la venta.	Confirmar y Cobrar: Solicitud financiera formal de anticipo o liquidación total.
Público Objetivo	Pasajeros finales, familias, líderes de grupo, organizadores corporativos.	Departamentos de contabilidad, agencias de viajes mayoristas, administradores B2B.
Estilo Visual	Banner panorámico de portada, narrativa detallada, cuadrícula de comidas y atractivos destacados.	Formato sobrio de factura proforma, datos de facturación, identificadores fiscales y montos claros.
Desglose de Tarifas	Precio total del paquete, tarifa por persona, tarifas de niños e infantes, y tabla por volumen.	Desglose pormenorizado por categoría (Adultos, Niños con Cama Extra, Niños Compartiendo, Infantes), deducción formal de comisión a la agencia, monto neto a transferir y depósito exigido.
Políticas y Pagos	Destaca el depósito porcentual y políticas de cancelación.	Instrucciones completas de transferencia internacional (SWIFT/IBAN) con selección de cuenta bancaria (`Current.account.bank_accounts`), recargo por tarjeta y fechas límite.

Canales de Entrega al Cliente

Canvas Web Responsive Interactivo:
Abre "Vista Previa de Propuesta" o "Vista Previa de Pre-Factura" para acceder a la versión web.
Adaptada a teléfonos móviles, tabletas y computadoras de escritorio.
Los viajeros pueden navegar jornada por jornada, consultar las comidas incluidas y descargar su archivo PDF en cualquier instante.
Exportación en PDF de Alta Resolución (Headless Chromium):
Haz clic en "Descargar PDF" o "Imprimir / PDF" para compilar el documento en el servidor mediante Chromium headless (Quotes::GeneratePdf).
Genera documentos en tamaño Carta con vectores nítidos, banners de alta resolución, márgenes limpios y sin cortes abruptos entre páginas.
Despacho por Correo Electrónico (QuoteMailer):
Haz clic en "Enviar PDF al Cliente por Correo" para remitir la propuesta o pre-factura al correo del cliente.
El mensaje se envía en el idioma preferido del cliente (EN, ES, FR, NL o PT), adjunta el PDF generado y establece como dirección de respuesta (reply_to) el correo del agente creador.
Duplicar Cotizaciones (/quotes/:id/duplicate):
¿Necesitas cotizar el mismo programa para otro cliente o en fechas diferentes? Pulsa "Duplicar" en la barra superior. El sistema crea un nuevo borrador idéntico con todos los días, actividades y hoteles listos para personalizar.

El Puente Operacional: Convertir Cotizaciones en Tours en Despacho

La ventaja competitiva de PragmaticTours sobre las hojas de cálculo convencionales radica en su conversión operativa en 1 clic (Quotes::ApproveAndSchedule):

Una vez el cliente aprueba la propuesta y abona su depósito, cambia el estado a approved o haz clic en "Aprobar y Despachar".
PragmaticTours genera de forma automática la estructura operativa:
Se crea el tour multidía padre que engloba todo el rango de fechas.
Se crean los tours hijos individuales correspondientes a cada jornada en tu Calendario de Despacho.
Se sincronizan fechas de inicio, alojamientos de recogida y regreso (pickup_accommodation_id, dropoff_accommodation_id), direcciones físicas del catálogo de hoteles, horas estimadas de traslado, cantidad de pasajeros y datos del cliente.
Se generan los manifiestos de pasajeros (TourPassenger) en el tour padre y tours hijos con el detalle completo del grupo familiar (ej. 2 Adultos, 2 Niños (1 c/ Cama, 1 Compartiendo, Edades: 10, 5), 1 Infante).
Se emiten automáticamente los Vouchers de Servicio (ServiceVoucher) para proveedores externos (empresas de transporte, guías, restaurantes, atracciones y aerolíneas locales).
¡Los tours quedan inmediatamente visibles en tu Panel de Despacho, listos para que el optimizador de auto-asignación programe vehículos y guías, o para procesar el manifiesto de pasajeros!

Reportes Financieros y Operacionales Derivados

Las cotizaciones aprobadas alimentan de inmediato los módulos de análisis financiero de PragmaticTours:

Reporte de Rentabilidad de Tours (/report):
Muestra ingresos reales, costos unitarios acumulados y margen de utilidad bruta tanto para el tour multidía padre como para cada excursión diaria individual.
Reporte de Cuentas por Pagar a Proveedores (/payable_report):
Agrupa los compromisos de pago por proveedor y categoría de gasto:
- Transporte / Vehículo (Fletes de buses, vans, botes)
- Alojamiento (Desglose de habitaciones dobles, camas extras de niños, niños compartiendo y habitación individual del líder FOC)
- Guías y Personal (Honorarios de guías bilingües y asistentes)
- Entradas y Atracciones (Boletos de adultos y niños)
- Alimentación y Restaurantes (Planes de comida para adultos y menús infantiles)
- Vuelos Domésticos (Pasajes aéreos regulares o chárter)
- Seguros y Cortesías (Pólizas de viaje, kits de bienvenida)
Reporte de Comisiones de Revendedores (/reseller_commission_report):
Monitorea las operaciones intermediadas por agencias de viajes mayoristas, volumen cotizado bruto, porcentaje y monto de comisiones deducidas y saldo neto por cobrar.

Personalización de Plantillas de Propuesta y Pre-Factura para tu Agencia

Cada agencia turística posee una identidad de marca distintiva: desde operadores de safaris y ecoturismo de lujo, hasta empresas de turismo de aventura, traslados VIP ejecutivos o circuitos culturales. Emitir propuestas con un formato genérico reduce la percepción de valor de tus servicios. PragmaticTours te permite personalizar totalmente el diseño, colores, logotipos y textos de tus documentos para proyectar una imagen profesional y memorable.

1. Gestión de Formatos en el Módulo de Plantillas (`/proposal_templates`)

Los administradores y despachadores pueden gestionar todos los formatos en Cotizaciones y Propuestas → Gestionar Formatos (/proposal_templates): - Filtrado por Tipo de Documento: Administra formatos de Propuesta, Pre-Factura y anexos de Términos y Condiciones. - Filtrado por Idioma: Mantén plantillas independientes y redactadas con propiedad en EN, ES, FR, NL y PT. - Formato Predeterminado por Mercado: Marca una plantilla como Predeterminada para su tipo e idioma. Al emitir una cotización para un cliente angloparlante o hispanohablante, el sistema selecciona automáticamente la plantilla correspondiente. - Generador de Plantillas Iniciales (Generar Plantillas Predeterminadas): En cuentas nuevas, haz clic en este botón para sembrar plantillas base con diseño profesional y alta conversión listas para usar.

flowchart LR
    TEMPLATES["Plantillas de Propuesta (/proposal_templates)\nGestión de HTML por tipo e idioma"] --> PROPOSAL_EN["Proposal (EN)\nPlantilla Luxury en Inglés"]
    TEMPLATES --> PROPOSAL_ES["Propuesta (ES)\nPlantilla DMC en Español"]
    TEMPLATES --> PREINVOICE_EN["Pre-Invoice (EN)\nProforma Corporativa"]
    TEMPLATES --> PREINVOICE_ES["Pre-Factura (ES)\nProforma Comercial"]
    ACCOUNT["Identidad de la Cuenta (/settings/account)\nBanners, Cuentas Bancarias, Redes Sociales"] --> RENDERER["Quotes::RenderDocument"]
    PROPOSAL_EN --> RENDERER
    PROPOSAL_ES --> RENDERER
    PREINVOICE_EN --> RENDERER
    PREINVOICE_ES --> RENDERER
    QUOTE["Datos del Tour y Niveles de Precio"] --> RENDERER
    RENDERER --> OUTPUT["Canvas Web y PDF Chromium"]

2. Diseño de Plantillas con HTML y Clases de Tailwind CSS

Al editar una plantilla (/proposal_templates/:id/edit), dispones de un editor con soporte completo para HTML estándar y clases de utilidad de Tailwind CSS:

Tipografía y Jerarquía: Emplea clases de tracking y peso visual (ej. font-black text-3xl tracking-tight, font-serif text-slate-800 o subtítulos en mayúsculas text-xs uppercase tracking-widest text-blue-600).
Paleta de Colores de la Agencia: Adapta los tonos al manual de marca de tu empresa (ej. bg-emerald-900 text-emerald-100 para ecoturismo, bg-amber-900 text-amber-100 para expediciones o bg-slate-900 text-amber-400 para servicios premium de lujo).
Tarjetas y Contenedores: Enmarca secciones en tarjetas redondeadas y limpias (bg-white rounded-2xl border border-gray-200 shadow-sm p-6).
Optimización de Impresión y Saltos de Página:
Aplica print:p-0 print:space-y-4 para eliminar márgenes de pantalla al momento de generar el PDF.
Utiliza la clase de Tailwind break-inside-avoid en las fichas de días y tablas de precios para impedir que una jornada quede cortada a la mitad entre dos páginas al imprimir.

3. Referencia Completa de Etiquetas Dinámicas (Merge Tags)

Durante la renderización (Quotes::RenderDocument), PragmaticTours sustituye automáticamente las etiquetas dinámicas por la información viva de la cotización:

Etiquetas de Empresa y Cabecera

Etiqueta Dinámica	Descripción del Dato	Ejemplo
`{{company_name}}`	Nombre comercial registrado de tu agencia	"Panama Trails DMC"
`{{agency_phone}}`	Teléfono de operaciones y atención al cliente	"+507 833-9000"
`{{header_image}}`	Etiqueta `<img>` con el banner subido en base64	`<img src="data:image/png;base64..." class="header-image" />`
`{{agency_header}}`	Cabecera completa con banner de imagen o texto de respaldo	Bloque con banner y código de referencia
`{{agency_footer}}`	Bloque de pie de página con teléfono, email y redes	Pie con iconos vectoriales
`{{social_links}}`	Enlaces SVG interactivos a WhatsApp, Instagram, Facebook	Iconos vectoriales con enlace directo
`{{powered_by}}`	Enlace de atribución del plan gratuito (se omite en planes de pago)	"Power by: https://pragmatictours.com"

Metadatos de la Cotización y Cliente

Etiqueta Dinámica	Descripción del Dato	Ejemplo
`{{quote_number}}`	Número identificador de la cotización	`"QT-2026-0042"`
`{{title}}`	Título del paquete o propuesta	"7 Días: Selva Panameña y San Blas"
`{{issue_date}}`	Fecha de emisión o impresión formateada	"29 de octubre de 2026"
`{{payment_due_date}}`	Fecha límite calculada para liquidación (15 días antes del tour)	"15 de noviembre de 2026"
`{{customer_name}}`	Nombre completo del cliente principal	"Dra. Victoria Bennett"
`{{customer_email}}`	Correo electrónico del cliente	"v.bennett@example.com"
`{{customer_phone}}`	Teléfono de contacto del cliente	"+1 (415) 555-0192"
`{{agent_name}}`	Agente de ventas responsable o intermediario B2B	"Carolina Martínez" o "Reserva Directa"
`{{start_date}}`	Fecha de inicio del tour / llegada	"30 de noviembre de 2026"
`{{end_date}}`	Fecha de finalización / salida	"06 de diciembre de 2026"
`{{duration_days}}`	Duración total formateada	"7 Días"
`{{pax_count}}`	Cantidad de pasajeros de pago	`"12"`
`{{foc_leader_count}}`	Cantidad de tour leaders de cortesía	`"1"`
`{{pax_formatted}}`	Formato combinado de pasajeros y líder	`"12+1"`

Tarifas y Términos Financieros

Etiqueta Dinámica	Descripción del Dato	Ejemplo
`{{currency}}`	Código de la divisa utilizada	`"USD"`
`{{total_estimated_cost}}`	Costo neto operativo total acumulado	"$14,280.00 USD"
`{{quoted_price_per_pax}}`	Tarifa cotizada por persona (base doble)	"$1,750.00 USD"
`{{quoted_price_sgl}}`	Tarifa por persona en habitación individual	"$2,150.00 USD"
`{{quoted_price_dbl}}`	Tarifa por persona en habitación doble compartida	"$1,750.00 USD"
`{{total_quoted_price}}`	Valor total bruto del paquete	"$21,000.00 USD"
`{{deposit_required_amount}}`	Monto de anticipo requerido para confirmar	"$6,300.00 USD"
`{{agent_commission_percentage}}`	Porcentaje de comisión para agencia B2B	`"10.0%"`
`{{agent_commission_amount}}`	Valor monetario de la comisión descontada	"$2,100.00 USD"
`{{net_amount_due}}`	Saldo neto a transferir tras descontar comisión	"$18,900.00 USD"
`{{credit_card_notice}}`	Aviso sobre cargo administrativo para pagos con tarjeta	"Los pagos realizados mediante tarjeta de crédito (Visa/Mastercard) conllevan un cargo administrativo del 4%."
`{{bank_details}}`	Instrucciones de transferencia bancaria formateadas	Beneficiario, banco, cuenta, SWIFT/BIC, IBAN

Tablas Dinámicas y Narrativas Enriquecidas

Etiqueta Dinámica	Componente Enriquecido Generado
`{{itinerary_summary_table}}`	Tabla Resumen de Comidas y Hoteles: Cuadrícula con Número de Día, Desayuno (✓/—), Almuerzo (✓/—), Cena (✓/—), título del servicio del itinerario y nombre del hotel asignado.
`{{hotel_descriptions}}` / `{{hotel_details}}`	Tarjetas de Detalles de Hoteles: Fichas visuales generadas una sola vez debajo de la tabla de Resumen del Programa, mostrando el nombre, dirección y descripción de cada hotel en el idioma de la cotización. Si un hotel no dispone de descripción en el idioma seleccionado, se omite; si ningún hotel tiene descripción en dicho idioma, la sección completa no se muestra.
`{{itinerary_detailed_narrative}}`	Narrativa Detallada de Inclusiones Diarias: Fichas por día con título, descripción del recorrido y lista de viñetas con los servicios marcados con `included_in_proposal`.
`{{pricing_tiers_table}}`	Matriz de Precios por Volumen de Pasajeros: Tabla con tramos de grupo (6–7 pax, 8–9 pax, 10–11 pax, 12–16 pax), categoría de vehículo asignado, tarifa SGL y tarifa DBL compartida.
`{{payment_terms}}`	Cláusulas y calendario de pagos acordados.
`{{cancellation_policy}}`	Escala de penalidades y políticas de reembolso por cancelación.
`{{client_notes}}`	Notas especiales sobre requerimientos alimenticios, médicos o logísticos del grupo.

4. Configuración de Marca y Aspectos Legales de la Cuenta (`/settings/account`)

Además de editar las plantillas HTML, define los activos globales de tu empresa en Configuración → Configuración de la Cuenta → Imagen de Marca de Propuestas y Pre-Facturas:

Banner de Encabezado para Propuestas (proposal_header_image):
Sube una imagen panorámica de alta definición (PNG, JPEG o WebP hasta 5MB).
Dimensiones sugeridas: 1200 × 300 px.
Con tu logotipo sobre una fotografía de impacto que represente tus mejores destinos turísticos.
Banner de Encabezado para Pre-Facturas (pre_invoice_header_image):
Sube una imagen corporativa formal.
Dimensiones sugeridas: 1200 × 200 px.
Con logotipo corporativo, razón social, dirección fiscal, teléfono oficial y número de registro tributario (RUC/CIF/RFC).
Instrucciones Bancarias de Transferencia (bank_details):
Registra las coordenadas de tu cuenta para transferencias internacionales:
- Nombre del Beneficiario: Razón social titular de la cuenta bancaria.
- Banco y Dirección de la Sucursal: Nombre de la entidad bancaria y ciudad.
- Número de Cuenta / IBAN: Código de cuenta local o IBAN internacional.
- Código SWIFT / BIC: Código de identificación bancaria de 8 u 11 caracteres.
- Moneda de Recepción: Divisas aceptadas (USD, EUR, etc.).
Perfiles de Redes Sociales:
Añade los enlaces de tu empresa en WhatsApp Business, Instagram, Facebook, LinkedIn y Sitio Web.
El sistema inserta automáticamente iconos vectoriales SVG con hipervínculos en los pies de página y vistas web.
Marca de Agua según el Plan de Suscripción:
Plan Basecamp (Gratuito): Los documentos incorporan una discreta leyenda "Power by: https://pragmatictours.com" en el pie de página.
Planes Voyage (Pro) y Expedition (Avanzado): 100% Marca Blanca. Todos los documentos, correos y PDFs se generan completamente limpios y libres de sellos del sistema.

5. Estrategias Prácticas para Maximizar el Impacto de tus Propuestas

Para incrementar la tasa de cierre de tus cotizaciones y generar confianza inmediata con viajeros y agencias mayoristas:

Abre con Inspiración y Destino, No Solo con Precios:
Aprovecha el editor de plantillas para ubicar un párrafo de bienvenida cálido justo después del banner de portada: resalta el valor de tus guías locales, la seguridad de tu flota y el soporte 24/7 en destino.
Estructura la Narrativa Diaria con Claridad:
Al redactar las actividades del día, segmenta la descripción en momentos destacados de la Mañana, Tarde y Noche.
Asegúrate de marcar los rubros de valor (ej. lancha privada, cata de café, entradas indígenas) con "Incluir en la Propuesta" para que el viajero perciba la abundancia de servicios incluidos.
Separa de Forma Explícita las Inclusiones y Exclusiones:
Diseña tarjetas comparativas que delimiten qué incluye la tarifa (transporte privado climatizado, desayunos diarios, entradas a parques) y qué queda excluido (boletos aéreos internacionales, propinas voluntarias, bebidas alcohólicas no detalladas).
Brinda Transparencia con la Tabla de Descuento por Volumen:
Al cotizar para familias, grupos de avistamiento de aves o viajes de incentivo, incluye {{pricing_tiers_table}}. Esto demuestra cómo la tarifa por persona disminuye al sumar más integrantes, incentivando a que el cliente invite a más viajeros.
Facilita la Aprobación Financiera B2B con Pre-Facturas Profesionales:
Para agencias mayoristas del exterior, remite el formato de Pre-Factura: muestra con precisión matemática el descuento de su comisión, las coordenadas bancarias y la fecha límite del anticipo, agilizando el trámite en su departamento contable sin cruces de correos innecesarios.

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

El Asistente de 4 Pasos para Plantillas de Tours

Crear o editar una plantilla de tour utiliza un asistente interactivo de 4 pasos optimizado para la eficiencia del despacho y la precisión de la economía unitaria:

Paso 1: Datos Básicos y Ruta (y Galería de Fotos)

Tipo y Categoría: Selecciona Tour de un Día o Paquete Multi-Día.
Tipo de Cumplimiento: Elige Propio / In-House (operado con flota y guías internos) o Revendedor / Proveedor Externo para tours subcontratados.
Ubicación y Zona Operativa: Asigna la ubicación principal o zona operativa (ej., Cancún, Riviera Maya, Tulum).
Guías Predefinidos: Preselecciona los guías preferidos que tendrán prioridad de asignación para este tour.
Filtrado Dinámico por Ubicación: Al seleccionar una ubicación, la lista de guías se filtra automáticamente para mostrar solo a los guías que atienden esa zona. Si ningún guía está asignado a esa ubicación específica, aparece un mensaje de advertencia y se listan todos los guías sin restricciones (movilidad global).
Gestión Rápida desde el Detalle de la Plantilla: Los guías predefinidos también se pueden agregar o remover directamente desde la página de detalle de la plantilla con un selector de 1 clic sin necesidad de volver a abrir el asistente.
Tiempos y Rutas: Nombre, código de tour, duración (horas), hora de recogida predeterminada, dirección de recogida y minutos de tránsito.
Galería de Fotos: Sube múltiples imágenes de alta resolución (JPEG, PNG, WEBP). La primera imagen se utiliza automáticamente como portada de la tarjeta. Las fotos existentes se muestran en una cuadrícula interactiva con eliminación en 1 clic.

Paso 2: Reglas de Escalamiento de Recursos (El Cálculo Operativo)

Define con exactitud qué personal y vehículos se requieren según el manifiesto de pasajeros.
Reglas Estáticas: Cantidad fija (ej., Siempre 1 Guía Líder, independientemente del tamaño del grupo).
Reglas Dinámicas: Proporciones que escalan con los pasajeros (ej., 1 guía por cada 20 pasajeros, 1 autobús por cada 50 pasajeros).
Equipos y Activos: Vincula el equipo requerido (cascos, kayaks, radios) con las reglas de inventario.

Paso 3: Precios, Servicios y Desglose de Costos

Precio Base y Reglas de Idioma: Precio de venta predeterminado por pasajero ($) y umbral mínimo de idioma (Mín. Pax por Idioma).
Costos de Restaurante y Comidas: Activa Incluido para gestionar paradas gastronómicas. Ingresa los costos por pasajero para Desayuno, Almuerzo y Cena, y asigna un proveedor asociado de Restaurante / Banquetero.
Seguro de Pasajeros y Cuentas por Pagar: Activa Incluido para registrar el costo de cobertura por pasajero y vincular un proveedor de Seguros / Corredor. Esta tarifa alimenta directamente los informes automatizados de pagos.
Costeo de Transporte y Sugerencias de Flota: El sistema calcula una Sugerencia de Flota promediando el costo diario de los vehículos coincidentes de tu agencia. Haz clic en "Usar Sugerencia" para autocompletar el campo, o ingresa una Tarifa Plana de Transporte personalizada.
Beneficios y Consumibles del Tour: Asigna amenidades por pasajero (Agua Fría, Cerveza Local, Refrescos, Frutas Frescas, Snacks, Cigarrillos, Toallas Húmedas o beneficios personalizados). Especifica cantidades por pasajero y costos unitarios. Incluye un enlace directo para administrar las tarifas predeterminadas de la agencia.
Lista Categorizada de Inclusiones y Exclusiones: Lista interactiva estandarizada (Alimentos y Bebidas, Transporte, Guías y Personal, Tarifas de Entrada, Equipo, Salud y Seguridad, Otros) que permite marcar elementos como incluidos o excluidos con 1 clic.

Paso 4: Revisión y Cascada de Rentabilidad en Vivo

Antes de guardar, el asistente presenta un desglose financiero completo por pasajero: - Costos Unitarios Detallados: Desayuno + Almuerzo + Cena + Seguro + Amenidades/Consumibles + Transporte Asignado/Pax + Mano de Obra de Personal/Pax. - Simulador de Margen en Vivo: Prueba diferentes escenarios de tamaño de grupo (ej., 5, 15, 30, 50 pasajeros) para evaluar: - Costo Estimado por Pasajero - Ganancia Bruta Estimada por Pasajero ($$ \text{Precio de Venta} - \text{Costo Total} $$) - % de Margen de Ganancia con insignias visuales de salud financiera: - 🟢 Saludable ($\ge 25\%$) - 🟡 Margen Ajustado ($0\% - 24\%$) - 🔴 Pérdida Proyectada ($< 0\%$)

Catálogo de Beneficios y Consumibles (`/perks`)

Administra las tarifas maestras de amenidades de tu agencia en un panel centralizado accesible desde el encabezado del Catálogo de Productos: - Costos Unitarios Predeterminados: Establece costos estándar (ej., $0.50/agua, $1.50/cerveza, $2.00/fruta). Al crear plantillas de tours, estas tarifas se completan automáticamente por defecto. - Agregar Beneficios Personalizados: Crea nuevos artículos con nombres personalizados, categorías (Bebida, Comida, Alcohol, Amenidad, Tabaco, Otro) y tipos de unidad (botella, lata, porción). - Edición Rápida: Modifica tarifas directamente en la tabla y guárdalas con 1 clic.

Paquetes Multi-Día

Para crear un tour que abarque varios días, selecciona Paquete Multi-Día en el Paso 1. El asistente se adapta: 1. Planes de Día: Agrega días y selecciona plantillas de tours de un día para cada fecha, con horarios de recogida o rutas específicas. 2. Alojamiento Nocturno: Asocia hoteles asociados, configuraciones de habitaciones y planes de alimentación para cada noche. 3. Precio Automatizado: Se calcula a partir de la suma de los costos de las plantillas de un día más las tarifas netas de alojamiento.

Cada plan de día genera un tour hijo al programar la operación.

Mantenimiento y Lista de Plantillas

Búsqueda y Filtros: Explora plantillas por nombre o código con paginación optimizada.
Eliminar vs. Deshabilitar: Las plantillas con tours existentes o registros históricos se deshabilitan de forma segura en lugar de borrarse, preservando la integridad de los informes. Puedes reactivarlas en cualquier momento con el botón Habilitar.

8. 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.

9. 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.

10. 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).

Ubicaciones de Servicio

Asigna ubicaciones o zonas operativas específicas que este miembro del equipo atiende (ej., Cancún, Riviera Maya, Tulum): - Filtrado por Ubicación del Tour: Cuando un tour tiene una ubicación asignada, el sistema de autoasignación solo considera a los guías que atienden esa ubicación. - Movilidad Global (Sin Restricción): Si un miembro del equipo no tiene ubicaciones específicas seleccionadas, puede asignarse a tours en cualquier ubicación.

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.

11. 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)). Los Guías Predefinidos configurados en la plantilla del tour se destacan con ⭐ y se priorizan al principio del menú desplegable.
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.

12. 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	Coincidencia de ubicación	Si el tour tiene una ubicación definida, solo son elegibles los guías que atienden esa ubicación (o guías flexibles sin restricciones de ubicación).
2	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.
3	Prioridad de guías predefinidos	Entre los candidatos que cumplen con los requisitos de idioma (o para espacios generales de guía), se da prioridad a los Guías Predefinidos configurados en la plantilla del tour. Un guía predefinido sin el idioma requerido no puede desplazar a un guía necesario para la cobertura de idiomas.
4	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.
5	Continuidad multi-día	Al optimizar tours de varios días, se prioriza al miembro del personal asignado previamente a los días anteriores del tour.
6	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.
7	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.

13. 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.

2.1. Catálogo de Tours y Bot Conversacional de Reservas en Telegram (`telegram_bookings`)

Cuando la función telegram_bookings está activada para la cuenta de tu agencia (disponible en el plan Advanced o como complemento): - Navegación del Catálogo de Tours: Los viajeros envían /catalog o /tours para recibir un menú de botones interactivos (inline keyboard) con los tours activos y precios. - Consultas de Disponibilidad en Tiempo Real: Consultas en lenguaje natural (ej. "¿El tour GAMBOA está disponible el 2026-10-15?") verifican la capacidad del tour, asientos de vehículos y precios en tiempo real. - Manifiesto de Pasajeros e Invitaciones de Calendario .ics: Recopila listas de pasajeros mediante pasos de chat interactivos, crea registros de Booking (source: "telegram"), programa tours en el calendario, añade pasajeros al manifiesto TourPassenger y adjunta automáticamente un archivo de calendario .ics junto a la confirmación instantánea.

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. - booking_confirmation: Enviado automáticamente a los viajeros cuando se confirma una reserva de tour a través de WhatsApp o web. - booking_inquiry: Enviado cuando se recibe una consulta de reserva. - booking_reminder: Programado 24h antes de la recogida para reservas confirmadas.

6. Catálogo Interactivo de Tours y Motor Conversacional de Reservas en WhatsApp (`whatsapp_bookings`)

Cuando la función whatsapp_bookings está activada para la cuenta de tu agencia (disponible como complemento o en el plan Advanced), PragmaticTours transforma tu número oficial de WhatsApp en un asistente automatizado de reservas independiente de las notificaciones de asignación del personal:

Catálogo Interactivo de Tours: Los viajeros o agentes de viajes envían "catálogo" o "tours" para recibir un menú interactivo de WhatsApp que lista tus ofertas de tours activas con precios por pasajero.
Consultas de Disponibilidad en Tiempo Real: Los usuarios pueden hacer preguntas en lenguaje natural (ej. "¿El tour GAMBOA está disponible el 2026-10-15?"). El motor calcula la capacidad en tiempo real, disponibilidad de asientos en vehículos y precios.
Recolección del Manifiesto de Pasajeros: Recopila la información del pasajero principal y la lista completa de pasajeros (nombres, categorías de edad, necesidades especiales) a través de pasos interactivos o Meta WhatsApp Flows nativos.
Programación Automática de Tours y Sincronización de Manifiestos: Al pulsar "Confirmar Reserva", PragmaticTours crea automáticamente el registro de Booking (source: "whatsapp"), programa el tour en el calendario si aún no está presente, añade todos los pasajeros a la lista activa del manifiesto TourPassenger, actualiza pax_count y emite una confirmación de reserva instantánea por WhatsApp con referencia BOOK-xxx.

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.

14. 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.

15. 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.

16. 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.

17. 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.

Qué se incluye

Personal freelance — solo se enumeran trabajadores independientes (empleados y contratistas en nómina quedan excluidos). Muestra el método de compensación (Tarifa fija / Gig o Por hora), la tarifa, las horas trabajadas (duración del tour) y el costo total.
Vehículos — se enumeran los vehículos contratados asignados a tours con su costo por hora, horas utilizadas y costo total. Los vehículos propios de la empresa se excluyen al no generar cuentas por pagar.
Proveedores de Seguros — se incluyen automáticamente aseguradoras y corredores cuando los tours programados incluyen seguro de pasajeros. El cálculo multiplica los pasajeros del manifiesto por la tarifa de seguro por pasajero ($$ \text{Pasajeros} \times \text{Tarifa de Seguro/Pax} $$).

Columnas

Columna	Descripción
Fecha	La fecha del tour.
Tour	El nombre del tour.
Nombre	Nombre del personal freelance, vehículo contratado o proveedor de seguros.
Tipo	Personal (Gig/Por Hora), Vehículo o Seguro.
Tarifa	Tarifa por hora o gig para personal; costo por hora para vehículos; tarifa por pasajero para seguros.
Horas / Unidades	Duración del tour en horas para personal/vehículos, o cantidad de pasajeros (ej. `24 pax`) para seguros.
Total	Monto total a pagar ($$ \text{Tarifa} \times \text{Horas} $$, tarifa plana Gig, o $$ \text{Pax} \times \text{Tarifa de Seguro} $$).
Propietario	Propio, Contratado o Proveedor.

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, vehículo contratado o línea de proveedor de seguros. 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 y tours activos programados. Las asignaciones en borrador o rechazadas y los tours cancelados quedan excluidos para evitar pagos indebidos.

18. 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.

19. 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.

Imagen de Marca de Propuestas y Pre-Facturas

Personaliza los documentos generados por el motor de Cotizaciones: - Banner de Encabezado de Propuesta (proposal_header_image): Sube un banner visual atractivo (PNG, JPG, WEBP) que se mostrará en la parte superior de las propuestas y los correos de notificación. - Banner de Encabezado de Pre-Factura (pre_invoice_header_image): Sube un encabezado comercial formal con datos fiscales y de facturación para pre-facturas y proformas. - Datos de Contacto y Redes Sociales: Configura teléfono, correo público, sitio web y enlaces a Instagram, Facebook y LinkedIn mostrados en los documentos. - Marca de Agua según el Plan: Las agencias en el plan Basecamp (Gratuito) incluyen automáticamente la leyenda "Power by: https://pragmatictours.com" en el pie de página de PDFs, canvas web y correos. Las cuentas en planes Voyage (Pro) o Expedition (Avanzado) cuentan con documentos 100% marca blanca sin marcas de agua.

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
Consulta de Reserva	`booking_inquiry`	Se dispara cuando un viajero envía una consulta de reserva por WhatsApp o widget web.	`{{1}}` Nombre del Cliente `{{2}}` Nombre del Tour `{{3}}` Fecha de Reserva `{{4}}` Cantidad de Pasajeros	Interactivo `📝 Completar Reserva`
Confirmación de Reserva	`booking_confirmation`	Se dispara automáticamente cuando se confirma una reserva de tour vía WhatsApp o despacho de agencia.	`{{1}}` Nombre del Cliente `{{2}}` Nombre del Tour `{{3}}` Fecha y Hora de Recogida `{{4}}` Cantidad de Pasajeros `{{5}}` Dirección de Recogida	Interactivo `Ver Ticket/Voucher`
Recordatorio de Reserva	`booking_reminder`	Programado 24h antes de la recogida para reservas de tour confirmadas.	`{{1}}` Nombre del Cliente `{{2}}` Nombre del Tour `{{3}}` Fecha y Hora `{{4}}` Dirección de Recogida	Ninguno
Respuesta de Chat	`chat_reply`	Se dispara durante intercambios de chat interactivos entre personal/clientes 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.

20. 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, restaurantes/banqueteros, aseguradoras/corredores, hoteles) con datos de contacto, número de WhatsApp, teléfonos de emergencia, tarifas netas por defecto y preferencia de entrega de voucher (WhatsApp o Correo).
Chat Directo por WhatsApp: Los números de teléfono de proveedores incluyen enlaces directos de chat (wa.me) con selector internacional de banderas para mensajería instantánea de despacho.
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.