API Civitatis (2.0.2)

El objetivo de este documento es proporcionar a agentes externos información relativa al funcionamiento del API, con el fin de evaluar y desarrollar la integración en su sitio web.

Civitatis provee de un interfaz de programación de aplicaciones (API) que proporciona acceso a información y funcionalidad relacionada con la representación y reserva de los productos que ofrece. A continuación se detalla el flujo completo de reserva y los recursos disponibles.

Se listan los posibles códigos de respuesta a continuación

Este código de respuesta indica que la solicitud no está autorizada. Puede deberse a problemas de autenticación con el token. Se recomienda verificar la validez y vigencia del token utilizado en la solicitud.

Cuando se recibe este código, significa que la solicitud ha sido bloqueada por el WAF ( Firewall de Aplicaciones Web ) debido a su naturaleza maliciosa o sospechosa.

Este código indica que la solicitud ha sido bloqueada por el CDN al superar el límite máximo de peticiones por segundo. Actualmente, el límite está configurado en 20 peticiones por segundo durante 1 minuto, es decir, 1200 peticiones por minuto.

En el atributo "cancelPolicies", ubicado en el endpoint de actividades, se definen las políticas asociadas a la cancelación de reservas. Aquí se especifican las penalizaciones y reembolsos en función del tiempo restante antes de la realización de la actividad.

A continuación, presentamos algunos ejemplos para facilitar la interpretación de esta información:

"cancelPolicies": [
  {
    "hours": 48,
    "penalty": 0,
    "type": "percent"
  }
] 

Esto significa que antes de 48 horas de la realización de la actividad se puede cancelar gratis, sin penalización

  "cancelPolicies": [
    {
      "hours": 120,
      "penalty": 25,
      "type": "percent"
    },
    {
      "hours": 240,
      "penalty": 15,
      "type": "percent"
    },
    {
      "hours": 504,
      "penalty": 0,
      "type": "percent"
    }
  ],

Por lo que sí son 504 horas antes del inicio de la actividad el reembolso es del 100%, 240 horas antes, la penalización de 15% (reembolso 85%), 120 horas antes sería el 25% de penalización (75% reembolso). Si la reserva se produce en menos de 120 horas la reserva no tiene reembolso.

"cancelPolicies": [
  {
    "hours": 0,
    "penalty": 100,
    "type": "percent"
  }
],

Esto quiere decir que no es reembolsable.

Las políticas de cancelación pueden estar basadas en dos tipos de penalizaciones: amount y percent.

Las penalizaciones de tipo percent se calculan como un porcentaje del precio total de la actividad; por ejemplo, una penalización del 25% significa que se descontará ese porcentaje del precio total, al realizar la cancelación.

En los casos en que el atributo "type" sea de tipo amount, el valor del atributo "penalty" indicará el montó a penalizar, por persona. Siempre se penalizará por persona independientemente de la categoría (adulto, niño, bebé). Se aplicará la misma penalización tanto para adultos como para niños, aunque el precio varíe. Tras la cancelación, se multiplicará la cantidad reflejada en el atributo "penalty" por la cantidad de personas para las cuales se haya hecho la reserva.

"cancelPolicies": [
    {
        "hours": 168,
        "penalty": 100,
        "type": "amount"
    }
]

En este ejemplo, si cancelas con más de 7 días de antelación tendrás una penalización de 100 € por pasajero. Si cancelas con menos tiempo, llegas tarde o no te presentas, no se ofrecerá ningún reembolso.

También puede darse el caso en la que la actividad cuente con una política de cancelación mixta. Es decir, que tenga penalización de tipo amount y de tipo percent. Las políticas de cancelación mixtas combinan penalizaciones tanto de tipo porcentaje como de monto fijo (en una cantidad específica de dinero). Cómo en los casos de penalización de tipo amount y percent, la penalización varía dependiendo de la antelación con la que se realice la cancelación.

"cancelPolicies": [
   {
       "hours": 336,
       "penalty": 60,
       "type": "percent"
   },
   {
       "hours": 504,
       "penalty": 40,
       "type": "percent"
   },
   {
       "hours": 720,
       "penalty": 200,
       "type": "amount"
   }
]

En este caso se combinan los dos tipos de penalización. Si cancelas con una antelación mayor a 30 días, se penaliza con 200 € por persona. Si cancelas entre 30 días y los 21 días de anticipación, se penaliza con el 40% del valor de la reserva. Si cancelas entre los 21 días a los 14 días de anticipación, se penaliza con el 60% del valor de la actividad. Y si cancelas entre los 14 dias hasta el día del disfrute de la actividad la reserva no tiene reembolso.

La categoría de una actividad se refiere a la clasificación principal o general a la que pertenece. Es una etiqueta amplia que agrupa actividades similares por sus características fundamentales. Puede obtener el detalle del endpoint para obtener el listado aquí

La subcategoría proporciona una clasificación más específica dentro de una categoría principal. Representa una división más detallada de las actividades. Puede obtener el detalle del endpoint para obtener el listado aquí

El atributo amountType aparece en varias respuestas de peticiones, durante la creación del carrito, o en la petición de actividades. Este valor puede ser NET o PVP, indicando que los montos mostrados de las actividades serán precio neto o precio PVP. Esta configuración se establece durante la creación del usuario.

Al momento de crear un carrito, el atributo prefix hace referencia al código numérico de teléfono del país. Los valores aceptados para este campo pueden obtenerse consultando el endpoint correspondiente al país (click aquí), atributo prefix

El wallet permitirá cargar saldo para así poder realizar reservas con este saldo disponible de una forma segura. Se puede obtener su key (click aquí), la cual se usará para realizar la confirmación de la reserva.

El objeto Advance, de la respuesta de GET activities/{id}, indica el tiempo de antelación para poder reservar una actividad. Las propiedades days, días de antelación, y hour, hora límite para reservar, van a par, por lo que si vienen en null, se debe extraer la información de la otra propiedad del objeto, minutes before, que indica la cantidad de minutos de antelación para reservar la actividad. (detalles aquí):

Por ejemplo:

¿Cuándo reservar? Puedes reservar hasta las 19:00 horas del día anterior siempre que haya disponibilidad.

"advance": 
  {
    "days": 1,
    "hour": 19:00,
    "minutes_before": null
  }

¿Cuándo reservar? Puedes reservar hasta cinco días antes siempre que haya disponibilidad.

"advance":
{
  "days": null,
  "hour": null,
  "minutes_before": 7200
}

Cada actividad puede tener restricciones específicas en cuanto al número mínimo y máximo de participantes. Estos parámetros determinan cómo y cuándo se puede realizar una reserva. Puedes consultar los siguientes campos en los detalles de la actividad realizando una petición al endpoint de la actividad. Por ejemplo:

GET {{url}}/v2/activities/{activityId}

• minimumPaxPerBooking (integer): Número mínimo de personas requerido para realizar una reserva. Este campo es bloqueante para la creación del carrito con la cantidad de participantes. Si intentas reservar con una cantidad inferior, el sistema no permitirá la creación del carrito.

• minimumPaxPerActivity (integer): Cantidad mínima de personas necesarias para llevar a cabo la actividad. Este campo es informativo y te indica cuántas personas se requieren en total para que la actividad se realice, independientemente de tu reserva individual.

• maximumPaxPerActivity (integer o null): Número máximo de personas permitidas para una reserva. Si es nulo, no hay límite establecido. Este campo es bloqueante para la creación del carrito con la cantidad de participantes. Si intentas reservar con una cantidad que excede este límite, la reserva será rechazada.

Ejemplo de uso:

Si una actividad tiene:

• minimumPaxPerBooking = 2
• minimumPaxPerActivity = 5
• maximumPaxPerActivity = 10

Significa que:

• No puedes hacer una reserva para menos de 2 personas.
• Se requiere de al menos cinco participantes para desarrollar la actividad, ese mismo día y hora. De no alcanzar el mínimo, el proveedor podría cancelar la actividad y proporcionar una alternativa. Éste es un campo informativo
• No puedes reservar para más de 10 personas en una sola reserva.

Puedes encontrar más información sobre la estructura de la respuesta de este endpoint en la documentación.

A continuación, presentamos una serie de escenarios comunes para la integración con la API de actividades. Estos ejemplos ofrecen consejos prácticos para implementar flujos de reserva y manejo de datos de manera eficiente. Para todos los casos, recomendamos hacer una petición al endpoint de actividades con disponibilidad infinita para obtener una lista de actividades aptas para probar los casos de uso.

• Busca una actividad en el endpoint recomendado (disponibilidad infinita) y selecciona una que tenga los atributos "hasAdditionalQuestions": false y "hasPassengersQuestions": false.
• Verifica la disponibilidad de la actividad antes de realizar la reserva utilizando los endpoints de calendario.
• Asegúrate de proporcionar los detalles correctos en la creación del carrito, como la fecha, tarifa y cantidad de participantes.
• Una vez confirmado el pago, utiliza el endpoint correspondiente para obtener el voucher.
• En caso de que quieras probar la cancelación, cancela la reserva mediante el endpoint adecuado, revisando posibles penalizaciones aplicables.
• Guarda o registra el identificador del carrito y de los items reservados para seguimiento interno.

• Busca una actividad en el endpoint recomendado (disponibilidad infinita) y selecciona una que tenga los atributos "hasAdditionalQuestions": true y/o "hasPassengersQuestions": true.
• Sigue el mismo flujo que hemos recomendado en el caso anterior, hasta la creación del carrito.
• Tras la creación del carrito, realiza una solicitud GET al endpoint de checkout para obtener las preguntas adicionales.
• Completa el proceso de checkout enviando la información requerida mediante un PUT al endpoint de checkout.
• Verifica que todas las respuestas requeridas sean válidas antes de enviar la solicitud.
• Confirma el pago y guarda el identificador.
• Puedes obtener más información sobre las preguntas adicionales en la documentación.

• Busca una actividad en el endpoint recomendado (disponibilidad infinita) y selecciona una que tenga el atributo "isCategoryPaxGroup": true.
• Especifica correctamente el número de participantes dentro del rango permitido para la categoría seleccionada.
• Sigue el flujo recomendado en el primer caso.
• Obten más información sobre las actividades por grupos de personas en la documentación sobre las actividades por grupos de personas isCategoryPaxGroup: true.

• Haz una petición al endpoint de actividades por destino y selecciona una actividad que tenga valores de los atributos minimumPaxPerBooking y minimumPaxPerActivity, mayores a 0.
• Debes cerciorarte que se respeten el número minimo y máximo de personas a participar en la actividad al crear el carrito en el endpoint /v2/cart. Estos campos son bloqueantes, y si no se cumplen, la solicitud será rechazada.
• Es recomendable que se controlen estos errores desde el desarrollo de la integración para que se adapte al usuario del sitio integrado al API.
• Obtén más información sobre las restricciones de mínimo y máximo de participantes en la documentación sobre restricciones de participantes.

• Consulta los detalles de una actividad a través de actividades por destino, por ejemplo, y selecciona alguna actividad que tenga el atributo "isFreeTour": true.
• Sigue el flujo creando el carrito, haciendo un GET checkout para obtener las preguntas adicionales y haciendo el PUT checkout introducir los datos.
• Ten en cuenta que, al tratarse de un freeTour, la reserva se confirmará automáticamente al completar el checkout.
• Obtén el voucher directamente como parte de la respuesta del PUT checkout sin necesidad de realizar un paso adicional de confirmación.
• Obten más información sobre las actividades de tipo freeTour en la documentación.

• Reservar una actividad cuya disponibilidad se base en días completos, en lugar de horarios específicos. Podrás encontrarlas haciendo una petición al endpoint de calendarios por destino, por ejemplo, y selecciona una actividad que tenga el atributo time:"", con el valor de un string vacío.
• En caso de que el campo "time" en la respuesta del calendario aparezca como un string vacío (""), asegúrate de crear el carrito utilizando este mismo valor. Esto aplica para actividades que no tienen una hora específica de inicio, como entradas a museos o actividades que pueden disfrutarse a lo largo del día.
• Obtén más información sobre la creación del cart en la documentación

• Busca una actividad a través de actividades por destino, por ejemplo, y selecciona una que tenga el atributo hasDynamicPrice: true.
• Realiza una solicitud al endpoint de precios dinámicos, enviando la fecha seleccionada para obtener el precio más actualizado de la actividad.
• Asegúrate de usar el precio retornado en el proceso de creación del carrito para evitar discrepancias entre el precio mostrado y el precio final.
• Obtén más información sobre las actividades con precios dinámicos en la documentación.

• Busca una actividad en el endpoint recomendado (disponibilidad infinita) y selecciona una que tenga el atributo "hasOneRate": true
• Consulta la disponibilidad en el calendario. Verás que la actividad tiene un solo "rate".
• Al crear el carrito, no será necesario elegir entre múltiples tarifas, ya que la actividad cuenta con una única opción de tarifa.
• Sigue el flujo recomendado en el primer caso.

• Busca una actividad en el endpoint recomendado (disponibilidad infinita) que tenga el atributo hasOneRate: false. Esto indica que la actividad cuenta con múltiples "rates" disponibles para seleccionar.
• Verifica la disponibilidad de la actividad utilizando los endpoints de calendario para consultar fechas y horarios disponibles.
• Examina las opciones en el array "rates" proporcionado en la respuesta del endpoint. Cada tarifa tiene categorías específicas que puedes seleccionar.
• Durante las pruebas, selecciona un "rate" diferente al primero del array para confirmar que puedes manejar múltiples opciones.
• Sigue el flujo recomendado en el primer caso.

• Busca una actividad con el atributo "quotaAvailable": false. Podrás encontrarlas haciendo una petición al endpoint de calendarios por destino, por ejemplo.
• ¿Qué significa quotaAvailable: false? Este atributo Legacy indica que puedes realizar la reserva independientemente de los valores de availability o quota. No es necesario verificar estos campos para determinar la disponibilidad.
• Sigue el flujo estándar para la reserva.
• Este caso es útil para entender cómo manejar integraciones Legacy.
• Puedes obtener más detalles sobre el significado de quotaAvailable en la documentación de disponibilidad.

Realiza una búsqueda detallada de actividades mediante diferentes criterios como destino, zona o coordenadas geográficas. A continuación, se presentan ejemplos de URLs para esta operación:

• Búsqueda por destino (detalles aquí):

  • {url}/v2/destinations/{destinationId}/activities

• Detalles de una actividad específica (detalles aquí):

  • {url}/v2/activities/{activityId}

• Búsqueda por coordenadas (detalles aquí):

  • {url}/v2/findByCoord

• Búsqueda por zona (detalles aquí):

  • {url}/v2/zones/{zoneId}/activities

La respuesta incluirá una lista de actividades que coincidan con los criterios de búsqueda, proporcionando detalles detallados sobre la misma.

Una vez identificadas las actividades de interés, es esencial verificar su disponibilidad. El Calendario V2 es la única fuente de verdad para disponibilidad, horarios y modalidades activas.

Source of Truth (disponibilidad y modalidades)

• GET {url}/v2/activities/{activityId} se utiliza solo para información estática (descripción, políticas y estructura de tarifas).
• GET/POST {url}/v2/calendar/activities es la fuente de verdad para disponibilidad, horarios y modalidades activas (rates).

Endpoints de Calendario V2 (Recomendados)

• Obtener calendario de una actividad específica:

  • GET {url}/v2/calendar/activities/{activityId}

  Este endpoint te permite obtener la disponibilidad detallada de una actividad específica mediante su activityId. Detalles aquí.

• Obtener calendario de actividades por destino, zona o coordenadas:

  • POST {url}/v2/calendar/activities

  En este endpoint, puedes enviar en el cuerpo de la solicitud (payload) uno de los siguientes parámetros para filtrar las actividades. Detalles aquí:

  • Por destinationId:

    {
      "destinationId": 1
    }
    

  • Por zoneId:

    {
      "zoneId": 1
    }
    

  • Por coordenadas:

    {
      "coordinate": {
        "latitude": "22.2951073",
        "longitude": "114.169665",
        "distance": "17"
      }
    }
    

  Este endpoint unificado permite obtener la disponibilidad de actividades filtrando por destino, zona o coordenadas geográficas. Proporciona una respuesta más completa y eficiente, facilitando la integración y reduciendo el número de llamadas necesarias.

Nota importante: quotaAvailable es un atributo exclusivo del Calendario Legacy (obsoleto) y no aplica al Calendario V2.

Legacy (obsoleto)

• Búsqueda de disponibilidad por destino (detalles aquí):

  • {url}/v2/destinations/{destinationId}/calendar

• Búsqueda de disponibilidad por actividad específica (detalles aquí):

  • {url}/v2/activities/{activityId}/calendar

• Búsqueda de disponibilidad por coordenadas (detalles aquí):

  • {url}/v2/findByCoord/calendar

• Búsqueda de disponibilidad por zona (detalles aquí):

  • {url}/v2/zones/{zoneId}/calendar

La respuesta proporcionará información detallada sobre la disponibilidad de las actividades, incluyendo calendarios y detalles específicos para facilitar la toma de decisiones del usuario.

Actividades con Precios Dinámicos

Cuando una actividad tiene el atributo hasDynamicPrice configurado en true, significa que los precios de dicha actividad pueden variar en función de factores como la fecha, la demanda o eventos especiales. Para obtener el precio exacto de la actividad en una fecha específica, es imprescindible realizar una consulta al siguiente endpoint de precios dinámicos.

Este proceso asegura que se presente el precio más actualizado en función de la fecha seleccionada por el usuario. No realizar esta consulta podría mostrar un precio incorrecto o desactualizado, lo que puede generar discrepancias en la oferta final.

Pasos a seguir:

• Verificar si el atributo hasDynamicPrice está establecido en true para la actividad correspondiente.
• Realizar una solicitud GET al endpoint mencionado, enviando la fecha obtenida a través del calendario, en la que se desea obtener el precio.
• Utilizar el precio retornado por el endpoint para presentar la información al usuario o para la gestión interna de la actividad.

Notas importantes:

• El Calendario V2 no gestiona precios dinámicos; estos siempre deben consultarse en /activities/{id}/dynamic-prices.
• No es posible probar precios dinámicos en QA; las pruebas deben realizarse en Producción.

Recomendación adicional:

Al momento de generar el carrito, es altamente recomendable verificar el precio en el resumen del carrito. Esto garantiza que el precio final a aplicar sea el más actualizado y evita posibles incongruencias entre el precio mostrado inicialmente y el precio final de la reserva.

Información adicional sobre la disponibilidad de actividades (Calendario V2)

En el Calendario V2, la disponibilidad final se obtiene combinando los cupos de hour.quota y rate.quota.

Interpretación de la disponibilidad (modelo actual)

1.- hour.quota > 0 1.1 rate.quota = -1 --> Dispo = hour.quota
1.2 rate.quota = 0 --> Dispo = 0
1.3 rate.quota > 0 --> Dispo = rate.quota 2.- hour.quota = 0 2.1 rate.quota = -1 --> Dispo = 0
2.2 rate.quota = 0 --> Dispo = 0
2.3 rate.quota > 0 --> Dispo = rate.quota (inconsistencia de datos) 3.- hour.quota = -1 3.1 rate.quota = -1 --> Dispo = Infinita
3.2 rate.quota = 0 --> Dispo = 0
3.3 rate.quota > 0 --> Dispo = rate.quota

Consideraciones

• hour.quota indica el cupo total del horario.
• rate.quota indica el cupo específico de la modalidad.
• -1 representa disponibilidad ilimitada.
• El caso hour.quota = 0 con rate.quota > 0 se considera una inconsistencia de datos.

Estructura real del JSON del Calendario V2

El Calendario V2 devuelve dos bloques principales:

• schedule: indica las fechas disponibles y qué configuraciones de tarifas (baseRatesId) aplican en cada fecha.
• baseRates: contiene la información completa de horarios, modalidades (rates) y cupos (quota).

{
  "activityId": "373",
  "currency": "COP",
  "timeZone": "Europe/Rome",
  "hasHours": true,
  "schedule": [ ... ],
  "baseRates": { ... }
}

Notas clave sobre baseRates

• baseRates es un objeto dinámico: cada clave es un baseRateId interno (por ejemplo: property1, aBcDeF1, xyz123).
• No existe un campo literal llamado properties.
• Cada entrada en baseRates representa una configuración de tarifas distinta.
• El campo baseRateId es el identificador de referencia; la disponibilidad nunca debe inferirse del nombre de la clave.

Relación entre schedule y baseRates Para una fecha concreta:

• se consulta schedule
• se obtiene el listado de baseRatesId
• se navega a baseRates[baseRateId]
• se consultan los hours
• se valida la disponibilidad con hour.quota y rate.quota

Navegación correcta para validar disponibilidad

schedule
 → baseRatesId
   → baseRates
     → hours
       → rates
         → quota

Calendario Legacy (obsoleto)

En la respuesta a la petición de los endpoints Legacy, la disponibilidad se consulta a través de los campos availability del objeto schedule, y quotaAvailable y quota, del objeto times, también de schedule.

• availability (entero): Este atributo muestra la disponibilidad de la actividad. Si quotaAvailable es true, el valor de availability debe ser considerado para verificar la disponibilidad. Si quotaAvailable es false, se podrá realizar la reserva sin importar el valor de este campo.
• quotaAvailable (booleano): Este atributo indica si se puede realizar una reserva. Si su valor es true, se deben tener en cuenta los atributos availability y quota para verificar la disponibilidad. Si es false, se podrá realizar la reserva sin considerar el valor de availability.
• quota (entero): Este atributo indica la cantidad de plazas disponibles para la actividad en un horario específico. Si quotaAvailable es true, el valor de quota debe ser considerado para verificar la disponibilidad.

Ejemplo de quotaAvailable true (Legacy):

"activityId": "556",
"currency": "USD",
"timeZone": "Europe/Istanbul",
"hasHours": true,
"schedule": [
    {
        "date": "2024-08-22",
        "availability": 10,
        "percentageDiscount": 0,
        "times": [
            {
                "time": "11:30",
                "quota": 10,
                "quotaAvailable": true
            }
        ]

Ejemplo de quotaAvailable false (Legacy):

"activityId": "556",
"currency": "USD",
"timeZone": "Europe/Istanbul",
"hasHours": true,
"schedule": [
    {
        "date": "2024-08-24",
        "availability": -1,
        "percentageDiscount": 0,
        "times": [
            {
                "time": "11:30",
                "quota": -1,
                "quotaAvailable": false
            }
        ]

• Ventajas de utilizar el nuevo sistema de calendario:

  La nueva versión del sistema de calendario introduce mejoras significativas en términos de flexibilidad, disponibilidad y administración de tarifas. A continuación, se presentan sus principales beneficios:

  • Soporte para múltiples horarios en un mismo día: Permite definir múltiples franjas horarias dentro de un solo día, facilitando la organización de actividades con distintos horarios.
  • Gestión avanzada de tarifas dinámicas: Posibilidad de establecer tarifas variables según demanda, horarios o disponibilidad.
  • Manejo explícito de zona horaria: Se incluye el campo timeZone, asegurando consistencia en las reservas independientemente del huso horario del usuario.
  • Disponibilidad granular por cuota (quota): Permite un control más detallado sobre la cantidad de plazas disponibles en cada horario.
  • Compatibilidad con múltiples monedas (currency): Mejora la gestión de precios internacionales mediante la definición explícita de la divisa utilizada en cada actividad.

• Comparación entre Calendario y Calendario V2:

  A continuación, se detallan las diferencias clave entre el sistema tradicional de calendario y la nueva versión recomendada.

  Característica	Calendario (V1)	Calendario V2
  Estructura	Lista simple de fechas y horarios.	Maneja tarifas dinámicas y horarios personalizados.
  Respuesta optimizada	Respuesta estándar.	Respuesta más ligera y eficiente en el consumo de datos.
  Suplementos individuales	No se maneja.	Se incluyen suplementos individuales en la estructura.
  Modelo de disponibilidad	availability + quotaAvailable (Legacy).	quota anidado en hours y rates.
  Disponibilidad (quota)	Cantidad fija de asientos.	Gestión granular de plazas por horario.
  Tarifas (baseRates)	Lista de precios estática.	Tarifas dinámicas con baseRates.
  Soporte para tarifas múltiples	No.	Sí, maneja baseRatesId para múltiples configuraciones.
  Gestión de cuotas por modalidad (rates)	No disponible.	Permite definir disponibilidad específica por modalidad (rates).
  Paginación	No se maneja.	Se incluye paginación para mejorar el rendimiento en grandes volúmenes de datos.

  Para garantizar un mejor rendimiento y nuevas funcionalidades, todas las futuras mejoras y optimizaciones se implementarán exclusivamente en el Calendario V2. Los endpoints Legacy se mantienen únicamente por compatibilidad con integraciones existentes.

Una vez que el usuario ha seleccionado una actividad específica, se agrega al carrito mediante una solicitud de creación de carrito. La respuesta incluirá detalles sobre la actividad agregada al carrito, así como información sobre el estado actual del carrito y los costos asociados. Puede encontrar mayor información aquí.

Obtiene información preliminar sobre la reserva actual, incluyendo detalles de datos del usuario, preguntas de la actividad o preguntas del pasajero que se necesitarán responder en el paso siguiente, costos estimados y cualquier otro dato relevante para el usuario. Para más detalles, consulta aquí.

Nota importante

En el caso de las actividades de tipo freeTour, la reserva se confirmará automáticamente después del proceso de checkout que se menciona anteriormente y devolverá la respuesta con el tipo "Root type for voucher" en el siguiente endpoint.

Si la actividad no es de tipo freeTour, se devolverá la información del carrito con la respuesta de tipo "Cart", en el referido endpoint y se deberá realizar el proceso de confirmación, como detallamos más adelante.

Puedes identificar las actividades de tipo freeTour con el atributo isFreeTour en la información de las actividades, en el siguiente endpoint

Sobre las actividades por grupos de personas isCategoryPaxGroup: true

Cuando una actividad está marcada como una actividad por grupos de personas, utilizando la propiedad isCategoryPaxGroup: true, se define un rango específico de personas que pueden participar en dicha actividad. Este rango se especifica a través de las propiedades minimum y maximum, que están incluidas dentro del objeto group para cada categoría.

• minimum Define el número mínimo de personas que deben participar en la actividad dentro de esa categoría específica.
• maximum Define el número máximo de personas permitidas en la actividad dentro de esa categoría.

"rates": [
    {
        "id": 0,
        "text": "Tour privado de 4 horas",
        "categories": [
            {
                "id": 0,
                "text": "Hasta 5 personas",
                "canBookAlone": true,
                "group": {
                    "minimum": 1,
                    "maximum": 5
                }
            },
            {
                "id": 1,
                "text": "Hasta 10 personas",
                "canBookAlone": true,
                "group": {
                    "minimum": 1,
                    "maximum": 10
                }
            },
            {
                "id": 2,
                "text": "Hasta 15 personas",
                "canBookAlone": true,
                "group": {
                    "minimum": 1,
                    "maximum": 15
                }
            }
        ]
    }
]

Cuando la actividad no es por grupos de personas (isCategoryPaxGroup: false), el campo group vendrá como un objeto vacío [].

"rates": [
    {
        "id": 0,
        "text": "Tour en español",
        "categories": [
            {
                "id": 0,
                "text": "Adultos",
                "canBookAlone": true,
                "group": []
            },
            {
                "id": 1,
                "text": "Menores de 11 años",
                "canBookAlone": false,
                "group": []
            }
        ]
    }
]

Si la actividad es isCategoryPaxGroup: true, el usuario podrá integrar el campo numberOfPersons en el payload del endpoint /v2/cart para establecer el número exacto de personas a participar en la actividad por grupos. El campo deberá tener un entero entre el rango de minimum y maximum de la categoría seleccionada.

Ejemplo: Para la actividad, 183221, vemos que la categoría con id 1 tiene un rango de 1 a 4 personas.

                {
                "id": 1,
                "text": "Hasta 4 personas",
                "canBookAlone": true,
                "group": {
                    "minimum": 1,
                    "maximum": 4
                }

Por lo tanto, el campo numberOfPersons, del payload del endpoint /v2/cart debe tener un valor entre 1 y 4.

      {
    "activityId": 183221,
    "date": "2024-09-13",
    "currency": "USD",
    "rate": {
      "id": "0",
      "categories": [
        {
          "id": "1",
          "quantity": 1,
          "numberOfPersons": 3
        }
      ]
    },
    "time": "09:00"
  }

• En actividades regulares: quantity representa la cantidad de personas para las que se está realizando la reserva dentro de una tarifa específica (por ejemplo, adultos o niños).Es decir, se indica cuántas personas se reservan bajo cada categoría de precio.

  Ejemplo: Actividad regular.

     {
      "activityId": 123456,
      "date": "2024-06-08",
      "currency": "EUR",
      "time": "10:00",
      "rate": {
      "id": 0,
      "categories": [
      {
         "id": 1,          // Tarifa adulto
         "quantity": 2     // 2 adultos
      },
      {
         "id": 2,          // Tarifa niño
         "quantity": 1     // 1 niño
      }
     ]
    }
   }
  

• En actividades grupales: quantity va como numero entero siendo 1 el valor predeterminado para cada grupo y aunque se puede cambiar, siempre se cobra por un solo grupo,No importa si son adultos o niños, se cobra por grupo. numberOfPersons, que indica cuántas personas participarán en ese grupo. Este valor no afecta al precio, debe estar dentro del rango permitido por la categoría group.minimum y group.maximum.

  Ejemplo 2: Actividad Grupal

  { 
   "activityId": 175180,
   "date": "2024-06-08",
   "currency": "EUR",
   "time": "",
   "rate": {
   "id": 0,
   "categories": [
   {
     "id": 0,
     "quantity": 1, 
     "numberOfPersons": 6 //Número de personas dentro del grupo
    }
  ]
   }
  }
  

  Consideraciones adicionales

  • Si el valor de numberOfPersons está fuera del rango permitido de group.minimum y group.maximum, la reserva será rechazada.
  • Aunque quantity podría aceptar valores mayores a 1 se cobrara solo por un grupo.
  • Es importante consultar los campos group.minimum y group.maximum antes de enviar una reserva.

Durante este paso, se ingresa la información adicional necesaria para confirmar la reserva. Esto incluye responder preguntas específicas sobre la actividad o proporcionar detalles adicionales sobre los pasajeros. Para obtener más detalles sobre este proceso, haz clic aquí.

En caso de rellenar datos adicionales de los pasajeros

• Para el ID del atributo passengers, por ejemplo, "passenger-1-0-663e2.206", el valor 0 se usa para agrupar al pasajero (es incremental en el caso de tener varios pasajeros). Esto significa que los ID "passenger-1-0-663e2.206" y "passenger-2-0-663e2.206" se refieren al mismo pasajero y a su vez el id "passenger-1-1-663e2.206" y "passenger-2-1-663e2.206" al otro pasajero. Para obtener más detalles sobre este proceso, haz clic aquí.

Antes de confirmar la reserva, obtendremos información esencial del Wallet asociado a la agencia, como su identificador único. Este Wallet Key se utiliza para identificar de manera segura la transacción durante el proceso de creación de la reserva.

Para ver más detalles haz clic aquí.

La reserva se crea oficialmente mediante una solicitud que incluye el Wallet Key obtenido anteriormente. La respuesta confirma la creación exitosa de la reserva y proporciona detalles finales, como números de confirmación y cualquier información adicional necesaria.

Para más información sobre la creación de la reserva, haz clic aquí.

Para obtener un listado de actividades con disponibilidad en el entorno de sandbox, puedes utilizar el siguiente endpoint: Obtener disponibilidad infinita de actividades (disponible para sandbox).

• hasCalendarHours: Si es false quiere decir que la actividad no tiene una hora específica para reservar. Podrías reservar dejando la propiedad time del payload del método POST del endpoint /v2/cart con un string vacío.

"activityId": 175180,
"date": "2024-06-08",
"currency": "EUR",
"time": "",
"rate": {
    "id": 0,
    "categories": [
        {
            "id": 0,
            "quantity": 1
        }

• isCategoryPaxGroup: Indica si la actividad tiene tipos de entradas por grupos de personas. Si es true, la propiedad text de los elementos del objeto categories de la respuesta de activities/{activityId}, mostrará las categorías por grupos de personas.

"rates": [
    {
        "id": 0,
        "text": "Tour privado de 4 horas",
        "categories": [
            {
                "id": 0,
                "text": "Hasta 5 personas",
                "canBookAlone": true,
                "group": {
                    "minimum": 1,
                    "maximum": 5
                }
            },
            {
                "id": 1,
                "text": "Hasta 10 personas",
                "canBookAlone": true,
                "group": {
                    "minimum": 1,
                    "maximum": 10
                }
            },
            {
                "id": 2,
                "text": "Hasta 15 personas",
                "canBookAlone": true,
                "group": {
                    "minimum": 1,
                    "maximum": 15
                }
            }
        ]
    }
]

• hasAdditionalQuestions: Indica si una actividad tiene preguntas adicionales. Si es true, el array booking de la respuesta de activities/{activityId}/checkoutData tendrá varios elementos de pregunta.

"booking": [{...},
                {
                    "id": "preguntaTitulo_0-663cc3e9519df6.37779825",
                    "label": "Onde voc\u00ea quer come\u00e7ar o tour?",
                    "type": "select",
                    "required": true,
                    "regex": null,
                    "options": [
                        {
                            "id": 0,
                            "text": "Porta do templo Wat Phra Singh (15:45 horas)."
                        },
                        {
                            "id": 1,
                            "text": "Porta do zool\u00f3gico de Chiang Mai (16:05 horas)."
                        }
                    ],
                    "value": "",
                    "uuid": null,
                    "labelTranslated": "Onde voc\u00ea quer come\u00e7ar o tour?"
                },
                {...}
            ],

• hasPassengersQuestions: Indica si una actividad requiere los datos de los pasajeros. Si es true, la respuesta de activities/{activityId}/checkoutData tendrá la propiedad "passengers".

"booking": [{...},{...},{...} ],
"passengers": [
                {
                    "id": "passenger-1-0-663cc3e9519df6.37779825",
                    "label": "Nombre",
                    "type": "text",
                    "required": true,
                    "regex": null,
                    "options": null,
                    "value": "",
                    "uuid": null
                },
                {
                    "id": "passenger-2-0-663cc3e9519df6.37779825",
                    "label": "Apellidos",
                    "type": "text",
                    "required": true,
                    "regex": null,
                    "options": null,
                    "value": "",
                    "uuid": null
                },
                {
                    "id": "passenger-13-0-663cc3e9519df6.37779825",
                    "label": "Fecha nacimiento",
                    "type": "date",
                    "required": true,
                    "regex": null,
                    "options": null,
                    "value": "",
                    "uuid": null
                },
      

• hasOneRate: Indica si una actividad tiene una única tarifa. Si es true, el array rate de la respuesta activities/{id} tendrá un solo elemento y si es false, tendrá más de un elemento.

 "rates": [
    {
        "id": 0,
        "text": "Tour sin vuelo de regreso",
        "categories": [
            {
                "id": 0,
                "text": "Adultos",
                "canBookAlone": true
            },
            {
                "id": 1,
                "text": "Niños de 7 a 12 años",
                "canBookAlone": false
            },
            {
                "id": 2,
                "text": "Menores de 7 años",
                "canBookAlone": false
            }
        ]
    },
    {
        "id": 1,
        "text": "Tour con vuelo de regreso",
        "categories": [{...}, {...}, {...}]   
    }
]

Encuentra más información sobre el endpoint GET infinite-availability aquí.

Prioriza el uso de coordenadas para evitar ambigüedades y mejorar la precisión en la disponibilidad de traslados. El endpoint recomendado es:

• POST {url}/v2/transfers/destinations/{destinationId}/vehicles (detalles aquí)

En este endpoint puedes enviar coordenadas de origen y destino. La información obtenida acerca del vehículo es esencial para llevar a cabo la reserva.

Legacy (compatibilidad):

• Los endpoints basados en zonas se mantienen solo por compatibilidad con integraciones existentes: /v2/transfers/{cityId}/zones/{zoneFrom}/{zoneTo}/vehicles y /v2/transfers/{cityId}/zones.

Round trip (ida y vuelta):

• La disponibilidad de un traslado ida y vuelta requiere dos llamadas independientes (una por cada trayecto).

Coordenadas disponibles en sandbox (ejemplo):

{
  "fromCoordinate": {
    "latitude": 41.390205,
    "longitude": 2.154007
  },
  "toCoordinate": {
    "latitude": 41.720233,
    "longitude": 2.933432
  },
  "filters": {
    "pax": 3,
    "date": "2026-02-24",
    "time": "10:00",
    "currency": "EUR"
  }
}

Una vez que el usuario ha seleccionado un traslado específico, se añade al carrito mediante una solicitud de creación de carrito. La respuesta incluirá detalles sobre el traslado agregado, así como información acerca del estado actual del carrito y los costos asociados. Puedes encontrar más información aquí.

Al crear el carrito, en el atributo time es importante indicar la hora del vuelo/tren cuando el destino es de tipo "Airport", "Port", "Train".

  {
      "id": 3,
      "label": "Porto per navi da crociera",
      "type": "Port",
      "iata": "",
      "minAdvance": 24
  },

Obtén información preliminar sobre la reserva actual, que incluye detalles del usuario, preguntas específicas sobre el traslado o del pasajero que necesitarán respuesta en el siguiente paso, costos estimados y cualquier otro dato relevante. Para obtener detalles adicionales, consulta aquí.

Durante este paso, se introduce la información adicional necesaria para confirmar la reserva. Esto implica responder preguntas específicas sobre el traslado o proporcionar detalles adicionales sobre los pasajeros. Para más detalles sobre este proceso, haz clic aquí.

Nombre del hotel:

• Cuando el traslado requiera nombre de hotel, debe enviarse como respuesta a la pregunta adicional correspondiente (por ejemplo, "Hotel de recogida" o "Hotel de destino") en el payload del checkout.

Antes de confirmar la reserva, se obtiene información esencial del Wallet asociado a la agencia, como su identificador único. Este Wallet Key se utiliza para identificar de manera segura la transacción durante el proceso de creación de la reserva.

Para ver más detalles haz clic aquí.

La reserva se crea oficialmente mediante una solicitud que incluye el Wallet Key obtenido anteriormente. La respuesta confirma la creación exitosa de la reserva y proporciona detalles finales, como números de confirmación y cualquier información adicional necesaria.

Para más información sobre la creación de la reserva, haz clic aquí.

Para validar la integración de traslados, sigue este checklist mínimo:

• Búsqueda de vehículos con coordenadas (origen/destino).
• Reserva de un trayecto ida y otro de vuelta (dos llamadas).
• Creación del carrito, respuesta de preguntas adicionales (incluyendo hotel si aplica) y confirmación.
• Validación de la respuesta final de la reserva y del voucher si aplica.

1. ¿Cómo manejo los errores de autenticación al consumir la API de Civitatis?

   Respuesta: Si recibes un código de respuesta 401 Unauthorized, significa que la solicitud no está autorizada. Esto puede deberse a problemas de autenticación con el token. Verifica la validez y vigencia del token utilizado en la solicitud y asegúrate de que estás enviando las credenciales correctas.

2. ¿Qué significa el código de error 406 Not Acceptable?

   Respuesta: El código 406 Not Acceptable indica que la solicitud ha sido bloqueada por el WAF (Firewall de Aplicaciones Web) debido a su naturaleza maliciosa o sospechosa. Asegúrate de que tu solicitud cumple con los parámetros y formatos esperados por la API y que no contiene contenido malicioso.

3. ¿Cómo puedo evitar el error 429 Too Many Requests?

   Respuesta: El error 429 Too Many Requests ocurre cuando se supera el límite máximo de peticiones por segundo, que actualmente es de 20 peticiones por segundo durante 1 minuto (1200 peticiones por minuto). Para evitar este error, implementa mecanismos de control de flujo en tu aplicación para limitar el número de solicitudes que envías a la API.

4. ¿Cómo funcionan las políticas de cancelación en las actividades?

   Respuesta: Las políticas de cancelación se definen en el atributo cancelPolicies de la actividad. Incluyen penalizaciones y reembolsos en función del tiempo restante antes de la realización de la actividad. Las penalizaciones pueden ser de tipo percent (porcentaje) o amount (monto fijo por persona). Es importante revisar estas políticas para informar adecuadamente a los usuarios sobre las condiciones de cancelación.

5. ¿Qué son las categorías y subcategorías en una actividad?

   Respuesta: La categoría es la clasificación principal o general a la que pertenece una actividad, agrupando actividades similares por sus características fundamentales. La subcategoría proporciona una clasificación más específica dentro de una categoría principal, representando una división más detallada de las actividades. Puedes obtener el listado de categorías y subcategorías mediante los endpoints correspondientes.

6. ¿Qué es el "amountType" y cómo afecta a los precios?

   Respuesta: El atributo amountType indica si los montos mostrados de las actividades son precio neto (NET) o precio de venta al público (PVP). Esta configuración se establece durante la creación del usuario y afecta cómo se muestran y calculan los precios en la API.

7. ¿Cómo se utiliza el "wallet" para realizar reservas?

   Respuesta: El wallet permite cargar saldo para realizar reservas de forma segura. Debes obtener la wallet key mediante el endpoint correspondiente y utilizarla al confirmar la reserva. Esto asegura que la transacción se realice de manera segura y autorizada.

8. ¿Qué es el objeto "advance" y cómo afecta a las reservas?

   Respuesta: El objeto advance, de la respuesta de GET activities/{id}, indica el tiempo de antelación necesario para poder reservar una actividad. Puede especificar días y hora límite para reservar o minutos de antelación. Por ejemplo, si advance indica 1 día y hora 19:00, significa que puedes reservar hasta las 19:00 horas del día anterior a la actividad.

9. ¿Cómo valido las preguntas de tipo fecha?

   Respuesta: Las respuestas a preguntas de tipo date deben tener alguno de los siguientes formatos: Y-m-d, Y/m/d, d-m-Y, d/m/Y. Si la fecha no cumple con alguno de estos formatos, se mostrará un mensaje de error indicando que el formato es incorrecto. En particular, cuando obtenemos los datos para reservar a través de la petición GET Checkout podríamos recibir preguntas de tipo date. Por ejemplo.

      {
          "id": "passenger-6-0-668d0622e21af0.78717589",
          "label": "Fecha caducidad pasaporte",
          "type": "date",
          "required": true,
          "regex": null,
          "options": null,
          "value": "",
          "uuid": null
     }
   

   Las respuestas de tipo date, a completarse en el siguiente endpoint, deben tener alguno de los siguientes formatos:

   ['Y-m-d', 'Y/m/d', 'd-m-Y', 'd/m/Y']
   

   En caso de que la fecha no cumpla con el formato, se mostrará un mensaje de error.

   {"error":"The parameter id 'passenger-6-0-668d0622e21af0.78717589' of type date doesn't have a correct format, current value: '18\/05\/1993 0:00:00'."}
   

10. ¿Cuál es el flujo de trabajo para reservar actividades?

    Respuesta: El flujo general para reservar actividades es:

    • Buscar actividades mediante los endpoints de búsqueda por destino, zona o coordenadas.
    • Obtener disponibilidad de las actividades.
    • Crear un carrito y agregar las actividades seleccionadas.
    • Obtener los datos de la reserva, incluyendo preguntas adicionales si las hay.
    • Rellenar los datos adicionales de la reserva.
    • Obtener la wallet key para confirmar la reserva.
    • Confirmar la reserva utilizando la wallet key.

11. ¿Cómo busco actividades y su disponibilidad?

    Respuesta:: Para obtener la disponibilidad, se recomienda utilizar los endpoints de calendario v2, ya que ofrecen mejoras significativas y serán mantenidos en futuras versiones:

    • Obtener calendario de una actividad específica:

      GET /v2/calendar/activities/{activityId}

    • Obtener calendario de actividades por destino, zona o coordenadas:

      POST /v2/calendar/activities

      En este endpoint, puedes enviar en el cuerpo de la solicitud uno de los siguientes parámetros:

      • Por Destino:

        {
          "destinationId": 1
        }
        

      • Por Zona:

        {
          "zoneId": 1
        }
        

      • Por Coordenadas:

        {
          "coordinate": {
            "latitude": "22.2951073",
            "longitude": "114.169665",
            "distance": "17"
          }
        }
        

    Estos endpoints unifican y mejoran las funcionalidades anteriores, permitiendo obtener la disponibilidad de actividades de manera más eficiente y con menos solicitudes.

    Nota: Los endpoints de calendario antiguos (legacy) aún están disponibles para mantener la compatibilidad con integraciones existentes, pero no se recomienda su uso en nuevos desarrollos:

    • Disponibilidad por destino: /v2/destinations/{destinationId}/calendar
    • Disponibilidad por actividad: /v2/activities/{activityId}/calendar
    • Disponibilidad por coordenadas: /v2/findByCoord/calendar

12. ¿Cómo manejo actividades con precios dinámicos?

    Respuesta: Si una actividad tiene el atributo hasDynamicPrice configurado en true, significa que los precios pueden variar según la fecha, demanda u otros factores. Debes consultar el endpoint de precios dinámicos para obtener el precio exacto en una fecha específica. Además, es recomendable verificar el precio en el resumen del carrito antes de confirmar la reserva.

    • El Calendario V2 no gestiona precios dinámicos.
    • No es posible probar precios dinámicos en QA; las pruebas deben realizarse en Producción.

13. ¿Qué significan los atributos "availability", "quotaAvailable" y "quota" en la disponibilidad de actividades?

    Respuesta:

• En Calendario V2, la disponibilidad se calcula combinando hour.quota (cupo total del horario) y rate.quota (cupo específico de la modalidad).
• -1 indica disponibilidad ilimitada.
• availability y quotaAvailable son atributos Legacy y no aplican al Calendario V2.

14. ¿Cómo creo un carrito y agrego actividades?

    Respuesta: Para crear un carrito y agregar actividades, utiliza el endpoint /v2/cart con el método POST, proporcionando la información de la actividad seleccionada, incluyendo activityId, date, currency, rate, categories y time si aplica. La respuesta incluirá detalles del carrito y la actividad agregada.

15. ¿Cómo obtengo y envío datos adicionales necesarios para la reserva?

    Respuesta: Después de crear el carrito, obtén los datos adicionales necesarios mediante el endpoint GET /cart/{cartId}/checkout. Allí recibirás preguntas adicionales y datos de pasajeros que debes completar. Envía las respuestas mediante el endpoint PUT /cart/{cartId}/checkout, asegurándote de proporcionar los IDs y valores requeridos.

16. ¿Cómo confirmo una reserva?

    Respuesta: Para confirmar una reserva, necesitas obtener la wallet key mediante el endpoint de obtención del wallet. Luego, envía una solicitud a POST /cart/{cartId}/confirm para crear la reserva, incluyendo la wallet key y los datos necesarios. La respuesta confirmará la creación exitosa de la reserva y proporcionará detalles finales.

17. ¿Cómo funcionan las actividades de tipo "freeTour"?

    Respuesta: Las actividades de tipo freeTour se confirman automáticamente después del proceso de checkout. No requieren el paso adicional de confirmación de la reserva. Puedes identificar estas actividades mediante el atributo isFreeTour en la información de la actividad.

18. ¿Cómo reservo actividades para grupos de personas?

    Respuesta: Si una actividad tiene isCategoryPaxGroup en true, significa que es para grupos de personas. En este caso, debes utilizar el campo numberOfPersons al crear el carrito en el endpoint correspondiente, indicando el número exacto de personas dentro del rango mínimo y máximo especificado en la categoría seleccionada.

19. ¿Cuál es la diferencia entre "quota" y "numberOfPersons"?

    Respuesta: quota es la disponibilidad real obtenida del Calendario V2 (cupos por horario y modalidad). numberOfPersons es el número exacto de personas que debes enviar al crear el carrito solo si la actividad es por grupos (isCategoryPaxGroup: true). Este valor debe estar dentro del rango mínimo y máximo de la categoría seleccionada.

20. ¿Cómo obtengo disponibilidad en el entorno sandbox?

    Respuesta: Para obtener disponibilidad en el entorno sandbox, puedes utilizar el endpoint de disponibilidad infinita: /v2/activities/infinite-availability. Este endpoint está diseñado para pruebas en el entorno sandbox y proporciona actividades con disponibilidad garantizada.

21. ¿Cuál es el flujo de trabajo para reservar traslados?

    Respuesta: El flujo general para reservar traslados es:

    • Buscar vehículos disponibles utilizando coordenadas de origen y destino.
    • Crear un carrito y agregar el traslado seleccionado.
    • Obtener los datos de la reserva, incluyendo preguntas adicionales si las hay.
    • Rellenar los datos adicionales de la reserva.
    • Obtener la wallet key para confirmar la reserva.
    • Confirmar la reserva utilizando la wallet key.
    • Para ida y vuelta, realiza el flujo dos veces (una por cada trayecto).

22. ¿Cómo busco vehículos disponibles para traslados?

    Respuesta: Se recomienda buscar vehículos disponibles mediante el endpoint que acepta coordenadas de origen y destino: /v2/transfers/destinations/{destinationId}/vehicles. Los endpoints basados en zonas (/v2/transfers/{cityId}/zones/...) se mantienen solo por compatibilidad con integraciones existentes.

23. ¿Cómo indico la hora de recogida en una reserva de traslado?

    Respuesta: Al crear el carrito para un traslado, debes indicar la hora en el atributo time. Es importante especificar la hora del vuelo o tren cuando el destino es de tipo Airport, Port o Train.

24. ¿Cómo relleno los datos adicionales para una reserva de traslado?

    Respuesta: Al obtener los datos de la reserva mediante el endpoint de checkout, recibirás preguntas adicionales específicas para el traslado. Debes completar estas preguntas y enviar las respuestas mediante el endpoint correspondiente, asegurándote de proporcionar los IDs y valores requeridos. Cuando se solicite, el nombre del hotel debe enviarse como respuesta a la pregunta adicional correspondiente.

25. ¿Cómo obtengo y utilizo la "wallet key" para confirmar una reserva?

    Respuesta: La wallet key se obtiene mediante el endpoint de obtención del wallet para obtener información del wallet asociado a tu agencia. Una vez obtenida, utilizas la wallet key en la solicitud de creación de la reserva, lo que permite identificar de manera segura la transacción.

26. ¿Cómo puedo evitar errores de validación al enviar datos en la API?

    Respuesta:

    • Asegúrate de utilizar los formatos correctos para fechas, horas y otros tipos de datos.
    • Verifica que los IDs y valores enviados correspondan a los proporcionados por la API.
    • Consulta los detalles de cada endpoint para conocer los campos requeridos y sus formatos.
    • Maneja adecuadamente las respuestas de error de la API para corregir cualquier problema en los datos enviados.

27. ¿Cómo puedo conocer el número máximo y mínimo de participantes permitidos en una actividad?

    Respuesta: Cada actividad puede tener restricciones específicas en cuanto al número mínimo y máximo de participantes. Estos parámetros determinan cómo y cuándo se puede realizar una reserva. Puedes consultar los siguientes campos en los detalles de la actividad realizando una petición al endpoint de la actividad. Por ejemplo:

    GET {{url}}/v2/activities/{activityId}

    • minimumPaxPerBooking (integer): Número mínimo de personas requerido para realizar una reserva. Este campo es bloqueante para la creación del carrito con la cantidad de participantes. Si intentas reservar con una cantidad inferior, el sistema no permitirá la creación del carrito.

    • minimumPaxPerActivity (integer): Cantidad mínima de personas necesarias para llevar a cabo la actividad. Este campo es informativo y te indica cuántas personas se requieren en total para que la actividad se realice, independientemente de tu reserva individual.

    • maximumPaxPerActivity (integer o null): Número máximo de personas permitidas para una reserva. Si es nulo, no hay límite establecido. Este campo es bloqueante para la creación del carrito con la cantidad de participantes. Si intentas reservar con una cantidad que excede este límite, la reserva será rechazada.

    Ejemplo de uso:

    Si una actividad tiene:

    • minimumPaxPerBooking = 2
    • minimumPaxPerActivity = 5
    • maximumPaxPerActivity = 10

    Significa que:

    • No puedes hacer una reserva para menos de 2 personas.
    • La actividad se realizará si hay al menos 5 participantes. (Este campo es informativo)
    • No puedes reservar para más de 10 personas en una sola reserva.

    Puedes encontrar más información sobre la estructura de la respuesta de este endpoint en la documentación.

28. ¿Cómo puedo filtrar las actividades por categorías y subcategorías?

    Respuesta: Para filtrar las actividades por categorías y subcategorías, puedes utilizar los parámetros category y subCategory en los siguientes endpoints:

• {{url}}/v2/destinations/{id}/activities

• {{url}}/v2/zones/{zoneId}/activities

• {{url}}/v2/findByCoord

• {{url}}/v2/findByCoord/calendar

• {{url}}/v2/zones/{id}/calendar

• {{url}}/v2/activities/infinite-availability

  Estos parámetros te permiten obtener actividades específicas dentro de una categoría o subcategoría determinada.

29. ¿Qué tipos de datos pueden almacenarse en caché y por cuánto tiempo?

    Respuesta: Existen ciertos datos dentro de la API que pueden beneficiarse del almacenamiento en caché, permitiendo mejorar el rendimiento sin comprometer la precisión de la información. Entre estos datos se incluyen:

    • Detalles de actividades (nombre, descripción, imágenes, ubicación, políticas generales, etc).
    • Disponibilidad de actividades (fechas en las que una actividad está disponible).
    • Configuraciones generales (políticas de cancelación, requisitos especiales, restricciones).
    • Listado de destinos (ciudades o lugares donde se ofrecen actividades).
    • Categorías de actividades (tipos de experiencias disponibles).
    • Idiomas disponibles (en qué idiomas se puede realizar una actividad).
    • Monedas aceptadas (qué divisas están disponibles para el pago).

    Se recomienda que el almacenamiento en caché de estos datos tenga una duración máxima de 4 horas, dependiendo de la naturaleza de la información, siendo los detalles de las actividades y la disponibilidad los datos que suelen variar más. Esto permite optimizar el rendimiento sin riesgo de trabajar con datos obsoletos. En caso de cambios frecuentes en un tipo de dato específico, se sugiere considerar una menor duración en el caché y aplicar mecanismos de invalidación adecuados.