Perguntas da reserva

O recurso de perguntas sobre reservas facilita a coleta de informações adicionais sobre o viajante.

Visão geral

O recurso de perguntas de reserva permite a coleta de dados adicionais do viajante (altura, peso, informações do documento de viagem, restrições alimentares, etc.) de maneira flexível.

Principais benefícios

• **Flexível:**Adicione novos tipos de dados sem versionamento de API
• Type-safe: O esquema JSON garante a estrutura correta
• Detectável: Capacidade de consultar os tipos disponíveis por meio de um endpoint de catálogo
• Filtrado: Você só vê as atividades que pode apoiar
• Localizado: As perguntas são compatíveis com vários idiomas

Glossário de documentos

• Arquitetura da solução
  Conceitos principais, modelos genéricos de tipo de dados, requisitos de atividade, capacidades do parceiro e envio de resposta estruturada.
• Endpoints da API
  O catálogo de tipos de dados, a filtragem de atividades e os endpoints de verificação de preços que expõem perguntas de reserva.
• Perguntas condicionais
  Como funcionam as perguntas pai/filho e os operadores que controlam a lógica de mostrar/ocultar.
• Fluxo de integração
  End-to-end etapas da descoberta até o envio da reserva.
• Exemplo de tipo de dados
  Um exemplo de tipo de dados mostrando sua definição de esquema e estrutura de resposta.
• Localização
  Como as perguntas e opções são retornadas em vários idiomas, mantendo os IDs constantes.
• Validação
  Client-side e server-side regras de validação e formato de resposta de erro.

Arquitetura da solução

Conceitos básicos

Modelos genéricos de tipo de dados

Os modelos de tipo de dados reutilizáveis ​​representam categorias de informações (mais podem ser adicionadas quando necessário), e.g. medição, seleção, endereço e telefone.

>> Saiba mais sobre modelos de tipo de dados

Para obter o catálogo completo de data-types, ligue para GET /experiences/booking-questions/data-types

Requisitos da atividade

As atividades declaram quais tipos de dados exigem por meio de perguntas de reserva, especificando:

• Identificador único em formato de string para a pergunta.
• Texto da pergunta (localizado)
• Descrição do texto da pergunta (localizada)
• Referência de tipo de dados
• Seja qual for a hashtag utilizada, per-traveler ou per-booking
• Restrições de validação (valores mínimo/máximo, comprimentos, etc.)
• A que bilhetes se aplica?
• Define a questão filha para um determinado pai.
• Lógica condicional opcional (perguntas que dependem de outras respostas)

Capacidades do parceiro

Você declara quais tipos de dados são suportados usando o parâmetro de filtro supported_booking_data_typesnos endpoints de pesquisa/conteúdo. Isso filtra as atividades para mostrar apenas aquelas que você pode realizar.

• Para lidar com qualquer tipo dinamicamente, envie supported_booking_data_types=*.
• Para obter suporte para perguntas sobre reservas, envie no.supported_booking_data_types=none

Envio de resposta estruturada

As respostas estão aninhadas adequadamente:

• Per-traveler respostas — No array booking_question_answersem cada objeto viajante.
• Per-booking respostas — No array booking_question_answersno nível de reserva.

Endpoints da API

Obtenha o catálogo de tipos de dados

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

Parâmetros de consulta: ?date_updated_start

>> Consulte o Fluxo de Integração: Etapa 1 para obter instruções de uso.

Finalidade: Retorna um catálogo de referência técnica de todos os modelos de tipo de dados disponíveis.

Exemplo de solicitação:

GET /experiences/booking-questions/data-types

Resposta de exemplo:

[
    {
      "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"
    },
]

Filtragem de atividades

Parâmetro de consulta: supported_booking_data_types

**Aplica-se aos endpoints ** /experiences/activities/contente /experiences/activities/availability

Finalidade: Filtra os resultados para incluir apenas as atividades cujas perguntas obrigatórias usam os tipos de dados especificados.

Exemplo:

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 lidar com todos os tipos e mostrar todas as atividades, use supported_booking_data_types=*. Você será responsável por lidar com todos os tipos de perguntas em Verificação de Preços e Reservas.
• Para lidar com perguntas sobre não reservas, use supported_booking_data_types=none. Isso retornará apenas as atividades que não possuem perguntas de reserva.

Verificação de preços (inclui perguntas sobre reservas)

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

Finalidade: Realiza uma verificação de preços e retorna perguntas de reserva (se houver) para a atividade.

Exemplo de solicitação:

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

Resposta de exemplo:

{
  "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: Se você filtrou atividades usando supported_booking_data_typesem suas chamadas de pesquisa/conteúdo anteriores, todas as perguntas retornadas usarão tipos de dados que você suporta.

Perguntas condicionais

As perguntas podem ser condicionais, baseadas nas respostas às perguntas anteriores. Isso é útil para coletar informações diferentes com base nas escolhas do usuário.

Como funciona

• Pergunta principal — Uma pergunta (normalmente do tipo selection) cuja resposta determina o que se segue.
• Perguntas filhas — Perguntas com um campo conditionalque faz referência à pergunta pai.
• Relação bidirecional — O pai lista os filhos em seu array; os filhos referenciam o pai com lógica condicional completa.children

Exemplo: Seleção do método de contato

Pergunta do pai/mãe:

{
  "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" }
  ]
}

Perguntas condicionais infantis:

[
  {
    "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 condicionais

Fluxo de integração

Etapa 1: Fase de descoberta

Consulte o catálogo de tipos de dados para determinar quais tipos são suportados:

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

Sedate_updated_start Se a data fornecida for verdadeira, somente os tipos de dados adicionados na data especificada ou posteriormente serão retornados.

Etapa 2: Pesquisar com filtros

Filtrar atividades para exibir apenas aquelas com perguntas compatíveis:

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

Este filtro exibe os resultados para incluir apenas as atividades cujas perguntas obrigatórias utilizam os tipos de dados especificados.

Etapa 3: Verificação de preços

Durante a verificação de preços, você receberá perguntas sobre a reserva na resposta:

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

A resposta inclui umbooking_questions matriz (se houver). Todas as perguntas utilizam tipos de dados do seu filtro.

Etapa 4: Recolher as respostas

Criar interface de usuário para coletar respostas:

• Exiba uma entrada apropriada para cada tipo de dado.
• Valide client-side usando o esquema do catálogo de tipos de dados.
• Para as perguntas com a hashtag per-traveler, colete as respostas para cada viajante.
• Para perguntas sobre per-booking, colete uma vez
• Lidar com perguntas condicionais (mostrar/ocultar com base nas respostas do pai)

Etapa 5: Enviar reserva

Envie as respostas juntamente com o pedido 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"
      }
    }
  ]
}

Exemplo de tipo de dados

Tamanho (medidas dimensionais)

Definição do esquema:

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

Exemplo de resposta:

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

Localização

As perguntas suportam vários idiomas através do parâmetro language na Verificação de Preços.

Exemplo em 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" }
  ]
}

Exemplo em espanhol:

A mesma pergunta com 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: Os IDs das perguntas e os IDs das opções permanecem constantes em todos os idiomas para garantir o envio consistente de respostas.

Validação

Validação Client-side

Os parceiros devem validar as respostas client-side usando o esquema do catálogo de tipos de dados para garantir a estrutura correta.

Validação Server-side

O endpoint de reservas valida se:

• Todas as perguntas obrigatórias têm respostas.
• A estrutura da resposta corresponde ao esquema do tipo de dados.
• Os valores atendem às restrições de validação.
• As perguntas condicionais são respondidas adequadamente.
• As perguntas Per-traveler são fornecidas para cada viajante.
• As perguntas Per-booking são fornecidas uma vez

Resposta de erro

{
  "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
        }
      ]
    }
  ]
}