Integración con Cotizarg: Sincronización de catálogo en tiempo real

Cotizarg es una plataforma especializada en el armado de cotizaciones, presupuestos personalizados y planes de financiación en cuotas para agencias de viajes. Con la integración nativa entre Turisuite y Cotizarg, tu agencia elimina por completo la carga duplicada de tarifas, el control manual de disponibilidad y las discrepancias de precios al cotizar.

Turisuite actúa como la fuente única de verdad (Single Source of Truth) de tu operación: tus excursiones activas, sus tarifas actualizadas de adultos y menores, el calendario operativo, los cupos disponibles día a día y las reglas de descuentos por cantidad de pasajeros se transmiten en tiempo real a Cotizarg.

---

¿Cómo funciona la arquitectura de la integración?

La relación entre ambas plataformas es bidireccional y cubre dos momentos clave del proceso comercial de una agencia:

• 1. Turisuite → Cotizarg (Lectura de catálogo en tiempo real): Cuando un asesor comercial abre el formulario de nuevo presupuesto en Cotizarg, el sistema consulta automáticamente a Turisuite para traer las excursiones vigentes con sus precios y cupos actualizados al instante.
• 2. Cotizarg → Turisuite (Importación de planes de pago): Cuando el pasajero acepta un presupuesto financiado en cuotas, el operador de la agencia puede importar ese plan directamente al módulo de Reservas Manuales (POS) de Turisuite para bloquear los lugares en el calendario y emitir vouchers con código QR de seguimiento.

---

1. Configuración inicial para tu agencia

Para habilitar la sincronización entre Turisuite y Cotizarg, cada agencia cuenta con credenciales exclusivas que garantizan la privacidad y el aislamiento total de sus datos:

A. API Key de la agencia (x-api-key)

Es una clave criptográfica única que identifica a tu agencia frente al endpoint de catálogo de Turisuite. Se configura en los ajustes de empresa dentro de Cotizarg.

• Garantiza que solo los asesores de tu propia agencia puedan consultar tus excursiones y cupos.
• Permite la comunicación segura servidor a servidor sin necesidad de iniciar sesión manualmente en cada consulta.

B. Slug público de Turisuite (turisuite_slug)

Es el identificador web de tu agencia (por ejemplo, si la web de tu agencia es patagonia-viajes.turisuite.com, tu slug es patagonia-viajes).

• Cotizarg utiliza este slug para generar automáticamente enlaces directos a las fichas públicas de las excursiones (https://<slug>.turisuite.com/excursion/<id>) dentro de los presupuestos y propuestas que envíes a tus clientes.

---

2. Qué datos se sincronizan en tiempo real

La sincronización se realiza mediante una Edge Function dedicada (partner-catalog). Cada vez que se inicia un presupuesto en Cotizarg, se consultan los siguientes datos:

A. Tarifas y monedas

• Precios diferenciados: Se obtienen los valores actualizados de price_adult (adultos) y price_child (menores). Si una excursión no admite menores o tiene tarifa cero, queda reflejado de manera exacta.
• Soporte multimoneda (ARS / USD): Si una excursión está cargada en dólares estadounidenses en Turisuite, Cotizarg respeta la divisa original y aplica el tipo de cambio pactado en la cotización, evitando desfasajes por fluctuaciones cambiarias imprevistas.
• Redondeo inteligente: Se respeta la configuración de redondeo a miles configurada en la agencia.

B. Calendario operativo y control de cupos (remaining_pax)

Cotizarg consulta la disponibilidad día por día para una ventana de 60 días hacia adelante (configurable según la fecha de viaje):

• Fechas operativas: Solo se habilitan para selección en el calendario de Cotizarg aquellos días en que la excursión efectivamente opera (según esté configurada con frecuencia diaria, días semanales específicos o fechas puntuales de temporada). Las fechas en que la excursión no opera aparecen deshabilitadas automáticamente.
• Cupos restantes reales: Si una salida tiene capacidad máxima (por ejemplo, 20 pasajeros) y ya cuenta con 14 lugares reservados en Turisuite, Cotizarg solo permite cotizar hasta un máximo de 6 pasajeros (remaining_pax: 6).
• Salidas agotadas: Las fechas con remaining_pax: 0 se marcan como agotadas y no pueden ser seleccionadas para un nuevo presupuesto.
• Capacidad ilimitada: Si la excursión no tiene un tope de pasajeros configurado, se informa como cupo abierto sin restricción.

C. Reglas de descuentos por volumen (Smart Yield / PAX)

Turisuite cuenta con un potente motor de descuentos según la cantidad de pasajeros del grupo. Cotizarg replica con exactitud la lógica comercial de Turisuite:

• Prioridad jerárquica: Si una excursión tiene reglas de descuento propias, estas tienen prioridad sobre las reglas generales de la agencia.
• Regla ganadora: Si un grupo viaja con 6 pasajeros y existen escalones de descuento para 4 pax (10%) y 6 pax (15%), el sistema aplica automáticamente el 15% (el escalón de min_pax más alto alcanzado por el grupo).
• Separación de conceptos: En Cotizarg se genera una línea clara de desglose para que el cliente final entienda el beneficio por volumen aplicado en su presupuesto.

D. Validación de códigos promocionales (action=validate-code)

Si el cliente cuenta con un cupón de descuento o código promocional:

• El asesor puede ingresar el código directamente en Cotizarg.
• El sistema valida en milisegundos con Turisuite si el código existe, si está vigente para la agencia y si aplica a la excursión seleccionada.
• Regla de no acumulación: Siguiendo la política comercial de Turisuite, si una cotización califica tanto para un descuento por cantidad de pasajeros como para un código promocional, se aplica el beneficio que otorgue el porcentaje más alto, protegiendo el margen de la agencia.
• Seguridad y confidencialidad: La validación no expone comisiones de colaboradores ni identificadores internos sensibles.

---

3. Protección de presupuestos históricos: Sistema de Snapshots

Una preocupación habitual en las agencias es: ¿Qué ocurre si cambio el nombre de una excursión o actualizo su descripción mientras un cliente tiene un presupuesto abierto en Cotizarg?

Para garantizar estabilidad total:

1. Al agregar una excursión a una cotización, Cotizarg guarda un snapshot estático con el nombre de la excursión (turisuite_excursion_name) y su identificador (turisuite_excursion_id).
2. Si más adelante modificás el título de la excursión en Turisuite, los presupuestos ya emitidos, los comprobantes y los links enviados a clientes anteriores no se rompen ni sufren alteraciones imprevistas.
3. El enlace público al detalle de la excursión se mantiene consistente a través del ID único de la experiencia.

---

4. Anulación automática y chequeo de estado de reservas

La integración no solo ayuda a cotizar, sino también a mantener ordenada la operación ante imprevistos:

A. Anulación automática de reservas (cancel-booking-plan)

Si un pasajero decide cancelar un plan de pago o anular una cotización ya pactada en Cotizarg:

• Cotizarg envía una solicitud segura a Turisuite para anular las reservas vinculadas a ese plan.
• Turisuite localiza automáticamente las reservas en estado pagando_plan, a_confirmar o pendiente y las pasa a estado cancelado.
• Liberación inmediata de cupo: Al cancelarse la reserva, los lugares bloqueados se liberan al instante en el calendario de Turisuite para que queden disponibles para otros clientes.
• Registro de auditoría: Se añade automáticamente una nota en el historial interno de la reserva:

  [DD/MM/AAAA HH:MM:SS] Reserva cancelada automáticamente por anulación del plan en Cotizarg.

• Protección de reservas pagadas: Si una reserva asociada al plan ya fue marcada como pagado o aprobada, Turisuite no la cancela automáticamente, sino que devuelve una advertencia para que el administrador revise la situación de forma manual y evite errores contables.

B. Consulta de estado consolidado (check-booking-status)

Cotizarg puede consultar en cualquier momento el estado real de las reservas asociadas a un plan dentro de Turisuite:

• La función devuelve { exists, status, booking_count, booking_id, booking_ids }.
• Si el plan todavía no fue creado en Turisuite, Cotizarg mantiene disponible el botón “Crear Reserva en Turisuite”.
• Si el plan ya fue importado, Cotizarg detecta el identificador y activa el botón “Ver Reserva en Turisuite”, que redirige directamente a la reserva y abre su modal de detalles de forma automática.
• Si todas las reservas del plan ya fueron abonadas y confirmadas, Cotizarg lo refleja con estado pagado.
• Si el plan sigue en curso de pago, figura como pagando_plan.
• Si las reservas fueron canceladas en Turisuite, Cotizarg advierte de inmediato al agente comercial.

---

Buenas prácticas para tu agencia

[!TIP] Mantené tu calendario operativo al día en Turisuite: Como Cotizarg consulta los cupos en vivo al crear cada presupuesto, asegurar que tus salidas tengan su capacidad máxima (max_pax) bien configurada evitará cualquier riesgo de sobreventa.

[!NOTE] ¿Qué pasa con la importación a Turisuite? Una vez que el cliente aprueba el presupuesto en Cotizarg y comienza a abonar sus cuotas, podés ingresar al panel de Turisuite e importar el plan en un solo clic. Te invitamos a leer la guía detallada: Cómo importar y gestionar Planes de Pago de Cotizarg en Turisuite.