Dudas de reservas

La función de preguntas de reserva te ayuda a recopilar datos adicionales sobre los viajeros

Información general

La función de preguntas de reserva te permite recopilar datos adicionales sobre los viajeros (e.g., altura, peso, información del documento de viaje, restricciones alimentarias, etc.) de una forma flexible y type-safe.

Ventajas principales

• Flexible: Añade nuevos tipos de datos sin necesidad de versionar la API
• Type-safe: El esquema JSON garantiza que la estructura sea correcta
• Accesible: Posibilidad de consultar los tipos disponibles a través de un punto de acceso del catálogo
• Filtrado: Solo ves las actividades en las que puedes colaborar
• Localizado: Las preguntas están disponibles en varios idiomas

Glosario del documento

• Arquitectura de la solución
  Conceptos básicos, modelos de tipos de datos genéricos, requisitos de las actividades, capacidades de los socios y envío estructurado de respuestas.
• Puntos de conexión de la API
  Los puntos de conexión «Catálogo de tipos de datos», «Filtrado de actividades» y «Comprobación de precios» que muestran preguntas sobre reservas.
• Preguntas condicionales
  Cómo funcionan las preguntas principales y secundarias, y los operadores que controlan la lógica de mostrar u ocultar.
• Flujo de integración
  End-to-end a los pasos desde el descubrimiento hasta el envío de la reserva.
• Ejemplo de tipo de datos
  Un ejemplo de tipo de datos que muestra su definición de esquema y su estructura de respuesta.
• Localización
  Cómo se muestran las preguntas y las opciones en varios idiomas manteniendo los ID constantes.
• Validación
  Client-side y server-side: reglas de validación y formato de la respuesta de error.

Arquitectura de la solución

Conceptos básicos

Modelos de tipos de datos genéricos

Los modelos de tipos de datos reutilizables representan categorías de información (se pueden añadir más cuando sea necesario), e.g. como medidas, selecciones, direcciones y números de teléfono.

>> Más información sobre los modelos de tipos de datos

Para ver el catálogo completo de data-types, llama al GET /experiences/booking-questions/data-types

Requisitos de actividad

Las actividades indican qué tipos de datos necesitan a través de las preguntas de reserva, especificando:

• Identificador único de la pregunta
• Texto de la pregunta (localizado)
• Descripción del texto de la pregunta (localizada)
• Referencia de tipos de datos
• Ya sea que se aplique per-traveler o per-booking
• Restricciones de validación (valores mínimos/máximos, longitudes, etc.)
• A qué entradas se aplica
• Define la pregunta secundaria para una pregunta principal determinada
• Lógica condicional opcional (preguntas que dependen de otras respuestas)

Capacidades de los socios

Para indicar qué tipos de datos admites, tienes que usar el parámetro de filtro « supported_booking_data_types » en los puntos finales de búsqueda y contenido. Esto filtra las actividades para que solo se muestren aquellas que puedes gestionar.

• Para gestionar de forma dinámica cualquier tipo de y, envía supported_booking_data_types=*.
• Si tienes alguna duda sobre las reservas en o, envía un correo a supported_booking_data_types=none.

Envío estructurado de respuestas

Las respuestas están anidadas correctamente:

• Per-traveler respuestas — En el array « booking_question_answers » de cada objeto «traveler».
• Per-booking respuestas — En la matriz « booking_question_answers » a nivel de reserva.

Puntos de conexión de la API

Consigue el catálogo de tipos de datos

Punto final: GET /experiences/booking-questions/data-types

Parámetros de consulta: ?date_updated_start

>> Echa un vistazo al flujo de integración: Paso 1 para saber cómo se usa

Objetivo: Devuelve un catálogo de referencia técnica con todos los modelos de tipos de datos disponibles.

Ejemplo de solicitud:

GET /experiences/booking-questions/data-types

Ejemplo de respuesta:

[
    {
      "date_added": "2026-07-14T11:30:08.104575+02:00",
      "date_updated": "2026-07-14T11:30:08.104575+02:00",
      "description": "Used for collecting any measurement with a numeric value and unit. Common examples include height (in/cm/foot/meter), weight (lb/kg/stone), shoe size (us_men/us_women/eu/uk/cm), helmet size (in/cm), waist size (in/cm), and chest size (in/cm). The allowed_units field specifies which units are valid for this measurement.",
      "name": "Measurement",
      "schema_definition": {
        "properties": {
          "unit": {
            "description": "Unit of measurement - must be one of the allowed_options specified for the question",
            "type": "string"
          },
          "value": {
            "description": "Numeric value as string to preserve precision",
            "pattern": "^[0-9]+(\\.[0-9]+)?$",
            "type": "string"
          }
        },
        "required": [
          "value",
          "unit"
        ],
        "type": "object"
      },
      "type": "measurement"
    },
]

Filtrado de actividades

Parámetro de consulta: supported_booking_data_types

Válido para: los puntos finales de /experiences/activities/content y /experiences/activities/availability

Objetivo: Filtra los resultados para que solo se incluyan las actividades cuyas preguntas obligatorias utilicen los tipos de datos especificados.

Ejemplo:

GET /experiences/activities/content
  ?activity_id=123&activity_id=456
  &language=en-US
  &supported_booking_data_types=measurement
  &supported_booking_data_types=selection
  &supported_booking_data_types=text

• Para gestionar todos los tipos y ver todas las actividades, usa supported_booking_data_types=*. Entonces, te toca encargarte de gestionar todos los tipos de preguntas en «Comprobación de precios» y «Reservas».
• Para cualquier duda que no tenga que ver con las reservas, escribe a supported_booking_data_types=none. Esto te mostrará solo las actividades en las que no haya preguntas sobre la reserva.

Consulta de precios (incluye preguntas sobre la reserva)

Punto final: GET /experiences/activities/{activity_id}/price-check

Objetivo: Comprueba los precios y muestra las preguntas sobre la reserva (si las hay) para la actividad.

Ejemplo de solicitud:

GET /experiences/activities/12345/price-check?token=abc123&tickets=...

Ejemplo de respuesta:

{
  "status": "available",
  "offer_pricing": {
    "total": {
      "value": "150.00",
      "currency": "USD"
    }
  },
  "booking_questions": [
    {
      "id": "height_1",
      "type": "measurement",
      "question": "What is your height?",
      "description": "Required for safety equipment fitting",
      "applies_to": "per_traveler",
      "ticket_ids": ["12346","12345"]
      "allowed_options": [
        { "id": "in", "label": "in" },
        { "id": "cm", "label": "cm" }
      ]
    },
    {
      "id": "weight_1",
      "type": "measurement",
      "question": "What is your weight?",
      "description": "Required for zipline weight limits",
      "applies_to": "per_traveler",
      "ticket_ids": ["12346","12345"]
      "allowed_options": [
        { "id": "lb", "label": "lb" },
        { "id": "kg", "label": "kg" }
      ]
    }
  ],
  "links": {
    "create": {
      "method": "POST",
      "href": "/itineraries/activity"
    }
  }
}

Nota: Si has filtrado las actividades utilizando supported_booking_data_typesen tus búsquedas o solicitudes de contenido anteriores, todas las preguntas que se muestren utilizarán los tipos de datos que admites.

Preguntas condicionales

Las preguntas pueden depender de las respuestas a preguntas anteriores. Esto te viene bien para recopilar información diferente según lo que elijas.

Funcionamiento

• Pregunta principal — Una pregunta (normalmente del tipo « selection ») cuya respuesta determina lo que viene a continuación.
• Preguntas secundarias — Preguntas con un campo « conditional » que hace referencia a la pregunta principal.
• Relación bidireccional — El elemento principal incluye a los secundarios en su matriz children; los secundarios hacen referencia al elemento principal con una lógica condicional completa.

Ejemplo: Selección del método de contacto

Pregunta de un padre:

{
  "id": "contact_method_1",
  "type": "selection",
  "question": "How would you prefer to be contacted?",
  "applies_to": "per_traveler",
  "ticket_ids": ["12346","12345"]
  "children": ["contact_phone_1", "contact_whatsapp_1", "contact_email_1"],
  "allow_multiple": false,
  "allowed_options": [
    { "id": "phone", "label": "Phone Call" },
    { "id": "whatsapp", "label": "WhatsApp" },
    { "id": "email", "label": "Email" },
    { "id": "no_contact", "label": "No Contact" }
  ]
}

Preguntas secundarias condicionales:

[
  {
    "id": "contact_phone_1",
    "type": "phone",
    "question": "What is your phone number?",
    "applies_to": "per_traveler",
    "conditional": {
      "parent_question_id": "contact_method_1",
      "show_when": {
        "operator": "equals",
        "field": "selected",
        "values": ["phone"]
      }
    }
  },
  {
    "id": "contact_whatsapp_1",
    "type": "text",
    "question": "What is your WhatsApp username?",
    "applies_to": "per_traveler",
    "conditional": {
      "parent_question_id": "contact_method_1",
      "show_when": {
        "operator": "equals",
        "field": "selected",
        "values": ["whatsapp"]
      }
    }
  },
  {
    "id": "contact_email_1",
    "type": "email",
    "question": "What is your email address?",
    "applies_to": "per_traveler",
    "conditional": {
      "parent_question_id": "contact_method_1",
      "show_when": {
        "operator": "equals",
        "field": "selected",
        "values": ["email"]
      }
    }
  }
]

Operadores condicionales

Proceso de integración

Paso 1: Fase de análisis

Consulta el catálogo de tipos de datos para saber qué tipos son compatibles:

GET /experiences/booking-questions/data-types?date_updated_start=2026-02-01

Si se indica date_updated_start, solo se devuelven los tipos de datos que se hayan añadido a partir de la fecha indicada.

Paso 2: Buscar con filtros

Filtra las actividades para que solo se muestren aquellas con preguntas compatibles:

GET /experiences/activities/content
  ?activity_id=123&activity_id=456&activity_id=789
  &language=en-US
  &supported_booking_data_types=measurement
  &supported_booking_data_types=selection
  &supported_booking_data_types=text

Esto filtra los resultados para que solo se incluyan las actividades cuyas preguntas obligatorias utilicen los tipos de datos especificados.

Paso 3: Comparar precios

Al consultar los precios, te aparecen preguntas sobre la reserva en la respuesta:

GET /experiences/activities/12345/price-check?token=abc123&tickets=...

La respuesta incluye una matriz « booking_questions » (si la hay). Todas las preguntas utilizan los tipos de datos de tu filtro.

Paso 4: Recopila las respuestas

Crea una interfaz de usuario para recopilar respuestas:

• Genera una entrada adecuada para cada tipo de datos
• Valida client-side utilizando el esquema del catálogo de tipos de datos
• Para las preguntas de « per-traveler », recopila las respuestas de cada viajero
• Si tienes alguna pregunta sobre « per-booking », llama una vez
• Gestionar preguntas condicionales (mostrar o ocultar según las respuestas de las preguntas principales)

Paso 5: Enviar la reserva

Envía las respuestas junto con la solicitud de reserva:

POST /itineraries/activity

{
  "primary_traveler": [
    {
      "given_name": "John",
      "family_name": "Doe",
      "booking_question_answers": [
        {
          "question_id": "height_1",
          "answer": {
            "value": "72",
            "unit": "in"
          }
        },
        {
          "question_id": "weight_1",
          "answer": {
            "value": "180",
            "unit": "lb"
          }
        }
      ]
    }
  ],
  "booking_question_answers": [
    {
      "question_id": "emergency_contact_1",
      "answer": {
        "value": "Jane Doe, +1-555-1234"
      }
    }
  ]
}

Ejemplo de tipo de datos

Tamaño (medidas dimensionales)

Definición del esquema:

{
  "type": "object",
  "required": ["value", "unit"],
  "properties": {
    "value": {
      "type": "string",
      "pattern": "^[0-9]+(\\.[0-9]+)?$"
    },
    "unit": {
      "type": "string"
    }
  }
}

Ejemplo de respuesta:

{
  "value": "72",
  "unit": "in"
}

Localización

Las preguntas admiten varios idiomas gracias al parámetro « language » de Price Check.

Ejemplo en inglés:

GET /experiences/activities/12345/price-check?token=...&language=en-US

{
  "id": "dietary_1",
  "type": "selection",
  "question": "Dietary preferences (optional)",
  "description": "Please share any dietary restrictions or allergies."
  "applies_to": "per_traveler",
  "allow_multiple": false
  "ticket_ids": ["12345", "12346"]
  "options": [
    { "id": "vegetarian", "label": "Vegetarian" },
    { "id": "vegan", "label": "Vegan" }
  ]
}

Ejemplo en español:

La misma pregunta con language=es-ES.

GET /experiences/activities/12345/price-check?token=...&language=es-ES

{
  "id": "dietary_1",
  "type": "selection",
  "question": "Preferencias alimentarias (opcional)",
  "description": "Por favor, indica las restricciones alimentarias o alergias. "
  "applies_to": "per_traveler",
  "allow_multiple": false
  "ticket_ids": ["12345", "12346"]
  "options": [
    { "id": "vegetarian", "label": "Vegetariano" },
    { "id": "vegan", "label": "Vegano" }
  ]
}

Nota: Los ID de las preguntas y de las opciones son los mismos en todos los idiomas para que el envío de respuestas sea coherente.

Validación

Client-side validación

Los socios deben validar las respuestas en client-side utilizando el esquema del catálogo de tipos de datos para asegurarse de que la estructura sea correcta.

Server-side validación

El punto final de reserva comprueba que:

• Todas las preguntas obligatorias tienen respuesta
• La estructura de la respuesta coincide con el esquema del tipo de datos
• Los valores cumplen con las restricciones de validación
• Las preguntas condicionales se responden correctamente
• Per-traveler Se incluyen preguntas para cada viajero
• Per-booking Las preguntas se dan una sola vez

Respuesta de error

{
  "type": "validation_failed",
  "message": "One or more booking question answers are invalid",
  "errors": [
    {
      "type": "missing_required_answer",
      "message": "Required question 'height_1' not answered for traveler 1",
      "fields": [
        {
          "path": "$.travelers[0].booking_question_answers",
          "value": null
        }
      ]
    }
  ]
}