Promotions

Sintaxis

En el mensaje Promotions se utiliza la siguiente sintaxis: 
<?xml version="1.0" encoding="UTF-8"?>
<Promotions partner="partner_account_name"
            id="message_ID"
            timestamp="timestamp">
  <HotelPromotions hotel_id="HotelID" action="[overlay]">
    <Promotion id="PromotionID" action="[delete]">
      <RoomTypes>
        <RoomType id="RoomID_1"/>
        <RoomType id="RoomID_2"/>
      </RoomTypes>
      <RatePlans>
        <RatePlan id="PackageID_1"/>
        <RatePlan id="PackageID_2"/>
      </RatePlans>
      <BookingDates>
        <DateRange start="YYYY-MM-DD" end="YYYY-MM-DD" days_of_week="MTWHFSU_or_subset"/>
        <DateRange start="YYYY-MM-DD" end="YYYY-MM-DD" days_of_week="MTWHFSU_or_subset"/>
      </BookingDates>
      <CheckinDates>
        <DateRange start="YYYY-MM-DD" end="YYYY-MM-DD" days_of_week="MTWHFSU_or_subset"/>
      </CheckinDates>
      <CheckoutDates>
        <DateRange start="YYYY-MM-DD" end="YYYY-MM-DD" days_of_week="MTWHFSU_or_subset"/>
      </CheckoutDates>
      <BookingWindow min="integer" max="integer"/>
      <LengthOfStay min="integer" max="integer"/>
      <!-- Specify only one of percentage, fixed_amount, or fixed_amount_per_night;
           applied_nights is only used with percentage or fixed_amount_per_night -->
      <Discount percentage="float" fixed_amount="float" fixed_amount_per_night="float"
        applied_nights="integer_1_to_99"/>
      <MinimumAmount before_discount="integer"/>
      <Devices>
        <Device type="[desktop|tablet|mobile]"/>
      </Devices>
      <UserCountries>
        <Country code="country_code"/>
      </UserCountries>
    </Promotion>
  </HotelPromotions>
</Promotions>

Elementos y atributos

El mensaje Promotions incluye los siguientes elementos y atributos:
Elemento/@Atributo Repeticiones Tipo Descripción
Promotions 1 Complex element Elemento raíz de un mensaje de promoción.
Promotions/@partner 1 String Cuenta de partner de este mensaje. El valor de esta cadena es "Clave del partner", que aparece en la página Configuración de la cuenta de Hotel Center.

Nota: Si tienes un backend que proporciona feeds para varias cuentas, este valor debe coincidir con el del atributo ID que se especifica en el elemento <RequestorID> de tus mensajes <OTA_HotelRateAmountNotifRQ> y <OTA_HotelAvailNotifRQ> de la misma cuenta.
Promotions/@id 1 String Identificador único de la solicitud. Este valor se devuelve en la respuesta, así como en los mensajes de error y advertencia. Los caracteres permitidos son: a-z, A-Z, 0-9, _ (guion bajo) y - (guion).
Promotions/@timestamp 1 DateTime Fecha y hora de creación de este mensaje.
Promotions/HotelPromotions 0..n HotelPromotions Promociones de una propiedad. Cada una se aplica a una sola propiedad.
Promotions/HotelPromotions/@hotel_id 1 String Identificador único de la propiedad. Este valor debe coincidir con el ID de hotel especificado en la cadena <id> del elemento <listing> del feed de lista de hoteles. El ID de hotel también aparece en Hotel Center.
Promotions/HotelPromotions/@action 0..1 Enum

Si se especifica, el valor debe ser "overlay". Cuando es así, todas las promociones almacenadas se eliminan antes de que se almacenen las que se han especificado en el mensaje actual.

Si no se especifica, se aplica una de las siguientes acciones a cada promoción especificada en ese mensaje:

  • Se añade (si ninguna de las promociones almacenadas tiene el mismo id)
  • Se actualiza (si la promoción almacenada tiene el mismo id)
  • Se elimina (si la promoción almacenada tiene el mismo id y el valor del atributo action de la promoción especificada en el mensaje es "delete").
Promotions/HotelPromotions/Promotion 0..10 Promotion

Promoción única de una propiedad. Ten en cuenta que si action="overlay" y no se especifica un elemento <Promotion>, se eliminan todas las promociones de la propiedad.

Nota: Si necesitas usar más de diez promociones, ponte en contacto con tu Administrador técnico de cuentas (TAM).
Promotions/HotelPromotions/Promotion/@id 1 String Identificador único de la promoción. Admite un máximo de 40 caracteres. Los caracteres admitidos son a-z, A-Z, 0-9, _ (guion bajo), - (guion) y . (punto).
Promotions/HotelPromotions/Promotion/@action 0..1 Enum

Si se especifica, el valor debe ser "delete". Si no se especifica y no se almacena una promoción con el mismo id, entonces esta promoción se almacena. De lo contrario, si no se especifica y se almacena una promoción con el mismo id, se actualizará la promoción disponible.

Si se especifica el valor "delete", se elimina la promoción almacenada con el mismo id. Cuando utilices "delete", no incluyas ningún elemento secundario en <Promotion>. Tampoco se permite usar "delete" junto con <HotelPromotions action="overlay"/>.

Promotions/HotelPromotions/Promotion/RoomTypes 0..1 RoomTypes Contenedor para una lista de tipos de habitación a las que se aplica la promoción. La promoción se aplica a cada <RoomType> especificado. Si no se especifica <RoomTypes>, la promoción se aplica a todas las habitaciones.
Promotions/HotelPromotions/Promotion/RoomTypes/RoomType 1..n RoomType Especifica el tipo de habitación, que se define en un elemento <RoomData> de un mensaje Transaction (Property Data), y se hace referencia a él mediante el valor <RoomID>. También se hace referencia al valor de <RoomID> mediante el atributo InvTypeCode de los mensajes OTA_HotelRateAmountNotifRQ.
Promotions/HotelPromotions/Promotion/RoomTypes/RoomType /@id 1 String Identificador único del inventario (tipo de habitación). Este valor se asigna a <RoomID> en un mensaje Transaction (Property Data). Admite un máximo de 50 caracteres.
Promotions/HotelPromotions/Promotion/RatePlans 0..1 RatePlans Contenedor para una lista de planes de precios a los que se aplica la promoción. Si no se especifica <RatePlans>, la promoción se aplica a todos los planes de precios.
Promotions/HotelPromotions/Promotion/RatePlans/RatePlan 1..n RatePlan Especifica un plan de precios. Un plan de precios se define a partir de una combinación de paquetes, precios y disponibilidad, tal como se define en los mensajes Transaction (Property Data), OTA_HotelRateAmountNotifRQ y OTA_HotelAvailNotifRQ, y se identifica por el PackageID.
Promotions/HotelPromotions/Promotion/RatePlans/RatePlan/@id 1 String Identificador único del plan de precios. Este valor se corresponde con el valor de PackageID de <PackageData> en un mensaje Transaction (Property Data) y en el atributo RatePlanCode de <StatusApplicationControl> en los mensajes <OTA_HotelRateAmountNotifRQ> y <OTA_HotelAvailNotifRQ>. Admite un máximo de 50 caracteres.
Promotions/HotelPromotions/Promotion/BookingDates 0..1 BookingDates Contenedor para uno o varios periodos que determinan cuándo debe producirse una reserva para que se aplique la promoción.
Promotions/HotelPromotions/Promotion/BookingDates/DateRange 1..99 DateRange Periodo en el que se especifica cuándo debe producirse una reserva para que se aplique la promoción.
Promotions/HotelPromotions/Promotion/BookingDates/DateRange/@start 0..1 Date Fecha de inicio del periodo (en función de la zona horaria de la propiedad). Esta fecha debe ser la misma o anterior a la indicada en end. Si no se especifica start, el periodo es ilimitado en lo que se refiere a la fecha de inicio.
Promotions/HotelPromotions/Promotion/BookingDates/DateRange/@end 0..1 Date Fecha de finalización del periodo (en función de la zona horaria de la propiedad). Esta fecha debe ser la misma o posterior a la indicada en start. Si no se especifica end, el periodo es ilimitado en lo que se refiere a la fecha de finalización.
Promotions/HotelPromotions/Promotion/BookingDates/DateRange/@days_of_week 0..1 String

Días de la semana permitidos en el periodo. Si no se especifica, se permiten todos los días. Cada carácter de la cadena indica un día. Por ejemplo, "MTWHF" especifica que se permiten días laborables en el periodo.

Los caracteres válidos son:

  • M para el lunes
  • T para el martes
  • W para el miércoles
  • H para el jueves
  • F para el viernes
  • S para el sábado
  • U para el domingo

Cualquier combinación de caracteres es válida.
Promotions/HotelPromotions/Promotion/CheckinDates 0..1 CheckinDates Contenedor de uno o varios periodos que determinan cuándo debe realizarse la entrada para que se aplique la promoción.
Promotions/HotelPromotions/Promotion/CheckinDates/DateRange 1..20 DateRange Periodo que indica cuándo debe realizarse la entrada para que se aplique la promoción. Este elemento no es obligatorio si vas a eliminar una o varias promociones.
Promotions/HotelPromotions/Promotion/CheckinDates/DateRange/@start 0..1 Date Fecha de inicio del periodo (en función de la zona horaria de la propiedad). Esta fecha debe ser la misma o anterior a la indicada en end. Si no se especifica start, el periodo es ilimitado en lo que se refiere a la fecha de inicio.
Promotions/HotelPromotions/Promotion/CheckinDates/DateRange/@end 0..1 Date Fecha de finalización del periodo (en función de la zona horaria de la propiedad). Esta fecha debe ser la misma o posterior a la indicada en start. Si no se especifica end, el periodo es ilimitado en lo que se refiere a la fecha de finalización.
Promotions/HotelPromotions/Promotion/CheckinDates/DateRange/@days_of_week 0..1 String

Días de la semana permitidos en el periodo. Si no se especifica, se permiten todos los días. Cada carácter de la cadena indica un día. Por ejemplo, "MTWHF" especifica que se permiten días laborables en el periodo.

Los caracteres válidos son:

  • M para el lunes
  • T para el martes
  • W para el miércoles
  • H para el jueves
  • F para el viernes
  • S para el sábado
  • U para el domingo

Cualquier combinación de caracteres es válida.
Promotions/HotelPromotions/Promotion/CheckoutDates 0..1 CheckoutDates Contenedor de uno o varios periodos que determinan cuándo debe realizarse la salida para que se aplique la promoción.
Promotions/HotelPromotions/Promotion/CheckoutDates/DateRange 1..20 DateRange Periodo que indica cuándo debe realizarse la salida para que se aplique la promoción. Este elemento no es obligatorio si vas a eliminar una o varias promociones.
Promotions/HotelPromotions/Promotion/CheckoutDates/DateRange/@start 0..1 Date Fecha de inicio del periodo (en función de la zona horaria de la propiedad). Esta fecha debe ser la misma o anterior a la indicada en end. Si no se especifica start, el periodo es ilimitado en lo que se refiere a la fecha de inicio.
Promotions/HotelPromotions/Promotion/CheckoutDates/DateRange/@end 0..1 Date Fecha de finalización del periodo (en función de la zona horaria de la propiedad). Esta fecha debe ser la misma o posterior a la indicada en start. Si no se especifica end, el periodo es ilimitado en lo que se refiere a la fecha de finalización.
Promotions/HotelPromotions/Promotion/CheckoutDates/DateRange/@days_of_week 0..1 String

Días de la semana permitidos en el periodo. Si no se especifica, se permiten todos los días. Cada carácter de la cadena indica un día. Por ejemplo, "MTWHF" especifica que se permiten días laborables en el periodo.

Los caracteres válidos son:

  • M para el lunes
  • T para el martes
  • W para el miércoles
  • H para el jueves
  • F para el viernes
  • S para el sábado
  • U para el domingo

Cualquier combinación de caracteres es válida.
Promotions/HotelPromotions/Promotion/BookingWindow 0..1 BookingWindow Especifica el periodo en que debe producirse la reserva en relación con la fecha de entrada (según la zona horaria de la propiedad). Por ejemplo, puedes configurar una ventana de reserva de al menos 7 días, pero no de más de 180 días, antes de la fecha de entrada.
Promotions/HotelPromotions/Promotion/BookingWindow/@min 0..1 Integer Número mínimo de días antes de la fecha de entrada en los que se debe realizar la reserva para que se aplique la promoción. Si no se especifica, no se aplica ningún mínimo.
Promotions/HotelPromotions/Promotion/BookingWindow/@max 0..1 Integer Número máximo de días antes de la fecha de entrada en los que se debe realizar la reserva para que se aplique la promoción. Si no se especifica, no se aplica ningún máximo.
Promotions/HotelPromotions/Promotion/LengthOfStay 0..1 LengthOfStay Define el mínimo y el máximo de noches de estancia que se permiten.
Promotions/HotelPromotions/Promotion/LengthOfStay/@min 0..1 Integer Número mínimo de noches de estancia que se permiten para que se aplique la promoción. Si no se especifica, no se aplica ningún mínimo.
Promotions/HotelPromotions/Promotion/LengthOfStay/@max 0..1 Integer Número máximo de noches de estancia que se permiten para que se aplique la promoción. Si no se especifica, no se aplica ningún máximo.
Promotions/HotelPromotions/Promotion/Discount 1 Discount Especifica el descuento que se aplicará a esta promoción.
Promotions/HotelPromotions/Promotion/Discount/@percentage 0..1 Float Nota: Se requiere exactamente uno de los objetos percentage, fixed_amount o fixed_amount_per_night.

Valor decimal comprendido entre 0 y 100 que especifica el porcentaje de descuento. Se aplica a AmountAfterTax (o AmountBeforeTax si no se especifica AmountAfterTax).

Ejemplos:

  • Si AmountAfterTax es 100 y percentage es 20, entonces

    el precio promocional = AmountAfterTax * (1 - porcentaje de descuento)

    80,00 = 100 * (1 - 0,2)

  • Si AmountBeforeTax es 100, percentage es 20 y TaxFeeInfo especifica un impuesto de 10, entonces

    el precio promocional = AmountBeforeTax * (1 - porcentaje de descuento) + impuestos

    90,00 = 100 * (1 - 0,2) + 10
Promotions/HotelPromotions/Promotion/Discount/@fixed_amount 0..1 Float Nota: Se requiere exactamente uno de los objetos percentage, fixed_amount o fixed_amount_per_night.

Importe fijo que se resta a la suma de los precios por noche de AmountAfterTax (o de AmountBeforeTax si AmountAfterTax no se especifica). Se presupone que se proporciona en la misma moneda que el precio por noche. Si es mayor que la suma de los precios por noche, el valor resultante será cero.

Ejemplos:

  • Si tenemos un precio de una estancia de 1 noche en la que los valores son 90 en AmountBeforeTax, 100 en AmountAfterTax y 20 en fixed_amount, entonces

    el precio promocional = AmountAfterTax - descuento fijo

    80,00 = 100 - 20

  • Si tenemos un precio de una estancia de 1 noche en la que los valores son 100 en AmountBeforeTax y 20 en fixed_amount, y el TaxFeeInfo especifica un impuesto del 8 %, entonces

    el precio promocional = (AmountBeforeTax - descuento fijo) * (1 + porcentaje fiscal)

    86,40 = (100 - 20) * 1,08

  • Si tenemos un precio de una estancia de 1 noche en la que los valores son 50 en AmountBeforeTax y 60 en fixed_amount, y el TaxFeeInfo especifica un impuesto del 10 %, entonces

    el precio de promoción = (AmountBeforeTax - descuento fijo) * impuestos

    10,00 = 0 + 10

  • Si tenemos un precio de una estancia de 3 noches en la que los valores son 100, 110 y 120 en AmountAfterTax y 150 en fixed_amount, entonces

    el precio promocional = suma(AmountAfterTax) - (descuento fijo)

    180,00 = (100 + 110 + 120) - 150
Promotions/HotelPromotions/Promotion/Discount/@fixed_amount_per_night 0..1 Float Nota: Se requiere exactamente uno de los objetos percentage, fixed_amount o fixed_amount_per_night.

Descuento fijo que se aplica a cada uno de los precios por noche de AmountAfterTax (o la noche más barata si se especifica applied_nights). Si no se especifica AmountAfterTax, se aplica a AmountBeforeTax. Se presupone que se proporciona en la misma moneda que el precio por noche. Si fixed_amount_per_night es superior al precio por noche, este último se reducirá a cero, ya que el descuento no puede ser negativo.

Ejemplos:

  • Si tenemos un precio de una estancia de 3 noches en la que los valores son 100, 110 y 120 en AmountAfterTax y 10 en fixed_amount_per_night, entonces

    el precio promocional = suma(AmountBeforeTax - importe del descuento fijo)

    300,00 = ((100 - 10) + (110 - 10) + (120 - 10))

  • Si tenemos un precio de una estancia de 3 noches en la que los valores son 10, 50 y 100 en AmountAfterTax y 20 en fixed_amount_per_night, entonces

    el precio promocional = suma(AmountAfterTax - importe del descuento fijo)

    110,00 = (0 + (50 - 20) + (100 - 20))
Promotions/HotelPromotions/Promotion/Discount/@applied_nights 0..1 Integer Nota: Solo debe usarse con percentage o con fixed_amount_per_night.

Número de noches al que se aplica el descuento, empezando por el precio más barato. Debe ser un número entero comprendido entre 1 y 99. Si no se especifica, se aplicará el descuento a todas las noches.
Promotions/HotelPromotions/Promotion/MinimumAmount 0..1 MinimumAmount Especifica la suma mínima de los precios diarios de la habitación (usando el valor AmountBeforeTax o AmountAfterTax, dependiendo de cuál sea mayor) que debe superarse para que se aplique la promoción.
Promotions/HotelPromotions/Promotion/MinimumAmount/@before_discount 1 Integer Valor que debe superarse para que se aplique la promoción.
Promotions/HotelPromotions/Promotion/Devices 0..1 Devices Contenedor para mostrar los dispositivos de usuario que cumplen los requisitos de la promoción. Si se especifica, el descuento solo se aplica a los usuarios aptos de los dispositivos incluidos. De lo contrario, se ofrece el descuento a los usuarios de cualquier dispositivo.
Promotions/HotelPromotions/Promotion/Devices/Device 1..3 Device Define un tipo de dispositivo de usuario que cumple los requisitos de la promoción.
Promotions/HotelPromotions/Promotion/Devices/Device/@type 1 Enum Tipo de dispositivo. El valor debe ser desktop, tablet o mobile.
Promotions/HotelPromotions/Promotion/UserCountries 0..1 UserCountries Contenedor para mostrar las ubicaciones de usuarios (países) que cumplen los requisitos de la promoción. Si se especifica, el descuento solo se aplica a los usuarios aptos de los países incluidos. De lo contrario, se ofrece el descuento a los usuarios de cualquier país.
Promotions/HotelPromotions/Promotion/UserCountries/Country 1..50 Country Define un país cuyos usuarios cumplen los requisitos de la promoción.
Promotions/HotelPromotions/Promotion/UserCountries/Country/@code 1 String Código de país CLDR (por ejemplo, ES o FR). En algunos países, el CLDR no es el mismo que el código de país ISO de dos letras. Además, no se admiten los códigos de región CLDR.

Ejemplos

Mensaje básico

En el siguiente ejemplo se muestra un mensaje Promotions básico:

<?xml version="1.0" encoding="UTF-8"?>
<Promotions partner="account_xyz"
            id="123_abc"
            timestamp="2020-05-18T16:20:00-04:00">
  <HotelPromotions hotel_id="Property_1">
    <Promotion id="1">
      <RoomTypes>
         <RoomType id="123"/>
         <RoomType id="456"/>
      </RoomTypes>
      <RatePlans>
         <RatePlan id="234"/>
         <RatePlan id="567"/>
      </RatePlans>
      <BookingDates>
         <DateRange start="2020-07-01" end="2020-07-31" days_of_week="MTWHF"/>
         <DateRange start="2020-09-01" end="2020-09-30"/>
      </BookingDates>
      <CheckinDates>
         <DateRange start="2020-10-01" end="2020-10-31" days_of_week="FSU"/>
      </CheckinDates>
      <CheckoutDates>
         <DateRange start="2020-10-08" end="2020-11-07" days_of_week="FSU"/>
      </CheckoutDates>
      <BookingWindow min="7" max="330"/>
      <LengthOfStay min="2" max="14"/>
      <Discount percentage=".2" applied_nights="2"/>
      <Devices>
        <Device type="mobile"/>
        <Device type="tablet"/>
      </Devices>
      <UserCountries>
        <Country code="US"/>
        <Country code="UK"/>
      </UserCountries>
    </Promotion>
  </HotelPromotions>
</Promotions>

Eliminar una promoción

En el siguiente ejemplo se muestra cómo eliminar una promoción de una propiedad:

<?xml version="1.0" encoding="UTF-8"?>
<Promotions timestamp="2020-06-18T16:20:00-04:00">
  <HotelPromotions hotel_id="Property_1">
    <Promotion id="1" action="delete"/>
  </HotelPromotions>
</Promotions>

Eliminar todas las promociones

En el siguiente ejemplo se muestra cómo eliminar todas las promociones de una propiedad:

<?xml version="1.0" encoding="UTF-8"?>
<Promotions timestamp="2020-07-18T16:20:00-04:00">
  <HotelPromotions hotel_id="Property_1" action="overlay"/>
</Promotions>

Superponer todas las promociones

En el siguiente ejemplo se muestra cómo superponer el elemento <HotelPromotions> de una propiedad con una o varias promociones nuevas. Cuando se incluye action="overlay", todas las promociones almacenadas se eliminan antes de que se almacenen las que se especifican en el mensaje actual:

<?xml version="1.0" encoding="UTF-8"?>
<Promotions timestamp="2020-07-18T16:20:00-04:00">
  <HotelPromotions hotel_id="Property_1" action="overlay"/>
    <Promotion id="1">
      <RoomTypes>
         <RoomType id="123"/>
         <RoomType id="456"/>
      </RoomTypes>
      <RatePlans>
         <RatePlan id="234"/>
         <RatePlan id="567"/>
      </RatePlans>
      <BookingDates>
         <DateRange start="2020-09-01" end="2020-09-30"/>
      </BookingDates>
      <Discount percentage=".1"/>
    </Promotion>
  </HotelPromotions>
</Promotions>