Promotions

Sintassi

La sintassi del messaggio Promotions è la seguente: 
<?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>

Elementi e attributi

Il messaggio Promotions contiene i seguenti elementi e attributi:
Elemento / @attributo Occorrenze Tipo Descrizione
Promotions 1 Complex element L'elemento principale di un messaggio contenente promozioni.
Promotions / @partner 1 String L'account partner di questo messaggio. Il valore della stringa è il valore "Chiave del partner" presente nella pagina Impostazioni account in Hotel Center.

Nota: se hai un backend che fornisce feed per più account, questo valore deve corrispondere al valore dell'attributo ID specificato nell'elemento <RequestorID> dei messaggi <OTA_HotelRateAmountNotifRQ> e <OTA_HotelAvailNotifRQ> per lo stesso account.
Promotions / @id 1 String Un identificatore univoco per la richiesta. Questo valore viene restituito nella risposta e nei messaggi di errore e avviso. I caratteri consentiti sono a-z, A-Z, 0-9, _ (trattino basso) e - (trattino).
Promotions / @timestamp 1 DateTime La data e l'ora di creazione di questo messaggio.
Promotions / HotelPromotions 0..n HotelPromotions Promozioni relative a una proprietà. Ogni promozione viene applicata a una singola proprietà.
Promotions / HotelPromotions / @hotel_id 1 String L'identificatore univoco della proprietà. Questo valore deve corrispondere all'ID hotel specificato utilizzando <id> nell'elemento <listing> nel feed elenco hotel. L'ID hotel è indicato anche in Hotel Center.
Promotions / HotelPromotions / @action 0..1 Enum

Se specificato, il valore deve essere "overlay". Quando il valore è overlay, tutte le promozioni archiviate vengono eliminate prima di archiviare le promozioni specificate nel messaggio corrente.

Se non specificato, allora ogni promozione specificata nel messaggio corrente viene:

  • Aggiunta (se nessuna delle promozioni archiviate ha lo stesso id)
  • Aggiornata (se una promozione archiviata ha lo stesso id)
  • Eliminata (se una promozione archiviata ha lo stesso id e il valore dell'attributo action della promozione specificata nel messaggio corrente è "delete")
Promotions / HotelPromotions / Promotion 0..10 Promotion

Una singola promozione relativa a una proprietà. Tieni presente che se action="overlay" e <Promotion> non sono specificati, tutte le promozioni relative alla proprietà verranno eliminate.

Nota: se devi utilizzare più di dieci promozioni, contatta il tuo Technical Account Manager (TAM).
Promotions / HotelPromotions / Promotion / @id 1 String Un identificatore univoco per la promozione. Il numero massimo di caratteri consentiti è 40. I caratteri consentiti sono a-z, A-Z, 0-9, _ (trattino basso), - (trattino), e . (punto).
Promotions /HotelPromotions / Promotion / @action 0..1 Enum

Se specificato, il valore deve essere "delete". Se il valore non è specificato e se non viene archiviata una promozione con lo stesso id, allora questa promozione viene archiviata. In caso contrario, se il valore non è specificato e se viene archiviata una promozione con lo stesso id, allora la promozione esistente viene aggiornata.

Se specifichi "delete", la promozione archiviata con lo stesso id viene eliminata. Quando utilizzi "delete", non includere nessun elemento secondario in <Promotion>. Inoltre, non è consentito l'utilizzo di "delete" insieme a <HotelPromotions action="overlay"/>.

Promotions / HotelPromotions / Promotion / RoomTypes 0..1 RoomTypes Container di un elenco dei tipi di camera a cui si applica la promozione. La promozione viene applicata a ogni <RoomType> specificato. Se <RoomTypes> non è specificato, la promozione si applica a tutte le camere.
Promotions / HotelPromotions / Promotion / RoomTypes / RoomType 1..n RoomType Specifica un tipo di camera. Il tipo di camera viene definito in un elemento <RoomData> all'interno di un messaggio Transaction (Property Data) e vi viene fatto riferimento tramite il relativo valore <RoomID> (al valore <RoomID> viene fatto riferimento anche tramite l'attributo InvTypeCode nei messaggi OTA_HotelRateAmountNotifRQ).
Promotions / HotelPromotions / Promotion / RoomTypes / RoomType / @id 1 String L'identificatore univoco dell'inventario (tipo di camera). Questo valore è mappato a <RoomID> in un messaggio Transaction (Property Data). Il numero massimo di caratteri consentiti è 50.
Promotions / HotelPromotions / Promotion / RatePlans 0..1 RatePlans Container di un elenco dei piani tariffari a cui si applica la promozione. Se <RatePlans> non è specificato, la promozione si applica a tutti i piani tariffari.
Promotions / HotelPromotions / Promotion / RatePlans / RatePlan 1..n RatePlan Specifica un piano tariffario. Il piano tariffario viene definito da una combinazione di pacchetti, tariffe e disponibilità, come definito nei messaggi Transaction (Property Data), OTA_HotelRateAmountNotifRQ e OTA_HotelAvailNotifRQ e come identificato da PackageID.
Promotions / HotelPromotions / Promotion / RatePlans / RatePlan / @id 1 String L'identificatore univoco del piano tariffario. Questo valore è mappato al valore PackageID in <PackageData> all'interno di un messaggio Transaction (Property Data) e nell'attributo RatePlanCode in <StatusApplicationControl> nei messaggi <OTA_HotelRateAmountNotifRQ> e <OTA_HotelAvailNotifRQ>. Il numero massimo di caratteri consentiti è 50.
Promotions / HotelPromotions / Promotion / BookingDates 0..1 BookingDates Un container di uno o più intervalli di date che definiscono il periodo in cui deve essere effettuata la prenotazione affinché venga applicata la promozione.
Promotions / HotelPromotions / Promotion / BookingDates / DateRange 1..99 DateRange Un intervallo di date che specifica il periodo in cui deve essere effettuata la prenotazione affinché venga applicata la promozione.
Promotions / HotelPromotions / Promotion / BookingDates / DateRange / @start 0..1 Date La data di inizio dell'intervallo di date (in base al fuso orario della proprietà), incluso il giorno di inizio. Questa data deve essere precedente o uguale alla data di end. Se start non è specificato, l'intervallo di date risulta effettivamente illimitato in termini di data di inizio.
Promotions / HotelPromotions / Promotion / BookingDates / DateRange / @end 0..1 Date La data di fine dell'intervallo di date (in base al fuso orario della proprietà), incluso il giorno di fine. Questa data deve essere uguale o successiva alla data di start. Se end non è specificato, l'intervallo di date risulta effettivamente illimitato in termini di data di fine.
Promotions / HotelPromotions / Promotion / BookingDates / DateRange / @days_of_week 0..1 String

I giorni della settimana consentiti nell'intervallo di date. Se non specificato, saranno consentiti tutti i giorni nell'intervallo di date. Ogni carattere nella stringa specifica un giorno. Ad esempio, "MTWHF" specifica che nell'intervallo di date sono consentiti i giorni feriali.

I caratteri validi sono:

  • M per lunedì
  • T per martedì
  • W per mercoledì
  • H per giovedì
  • F per venerdì
  • S per sabato
  • U per domenica

Sono valide tutte le combinazioni di caratteri.
Promotions / HotelPromotions / Promotion / CheckinDates 0..1 CheckinDates Un container di uno o più intervalli di date che definiscono il periodo in cui deve essere effettuato il check-in affinché venga applicata la promozione.
Promotions / HotelPromotions / Promotion / CheckinDates / DateRange 1..20 DateRange Un intervallo di date che specifica il periodo in cui deve essere effettuato il check-in affinché venga applicata la promozione. Questo elemento non è richiesto se stai eliminando una o più promozioni.
Promotions / HotelPromotions / Promotion / CheckinDates / DateRange / @start 0..1 Date La data di inizio dell'intervallo di date (in base al fuso orario della proprietà), incluso il giorno di inizio. Questa data deve essere precedente o uguale alla data di end. Se start non è specificato, l'intervallo di date risulta effettivamente illimitato in termini di data di inizio.
Promotions / HotelPromotions / Promotion / CheckinDates / DateRange / @end 0..1 Date La data di fine dell'intervallo di date (in base al fuso orario della proprietà), incluso il giorno di fine. Questa data deve essere uguale o successiva alla data di start. Se end non è specificato, l'intervallo di date risulta effettivamente illimitato in termini di data di fine.
Promotions / HotelPromotions / Promotion / CheckinDates / DateRange / @days_of_week 0..1 String

I giorni della settimana consentiti nell'intervallo di date. Se non specificato, saranno consentiti tutti i giorni nell'intervallo di date. Ogni carattere nella stringa specifica un giorno. Ad esempio, "MTWHF" specifica che nell'intervallo di date sono consentiti i giorni feriali.

I caratteri validi sono:

  • M per lunedì
  • T per martedì
  • W per mercoledì
  • H per giovedì
  • F per venerdì
  • S per sabato
  • U per domenica

Sono valide tutte le combinazioni di caratteri.
Promotions / HotelPromotions / Promotion / CheckoutDates 0..1 CheckoutDates Un container di uno o più intervalli di date che definiscono il periodo in cui deve essere effettuato il check-out affinché venga applicata la promozione.
Promotions / HotelPromotions / Promotion / CheckoutDates / DateRange 1..20 DateRange Un intervallo di date che specifica il periodo in cui deve essere effettuato il check-out affinché venga applicata la promozione. Questo elemento non è richiesto se stai eliminando una o più promozioni.
Promotions / HotelPromotions / Promotion / CheckoutDates / DateRange / @start 0..1 Date La data di inizio dell'intervallo di date (in base al fuso orario della proprietà), incluso il giorno di inizio. Questa data deve essere precedente o uguale alla data di end. Se start non è specificato, l'intervallo di date risulta effettivamente illimitato in termini di data di inizio.
Promotions / HotelPromotions / Promotion / CheckoutDates / DateRange / @end 0..1 Date La data di fine dell'intervallo di date (in base al fuso orario della proprietà), incluso il giorno di fine. Questa data deve essere uguale o successiva alla data di start. Se end non è specificato, l'intervallo di date risulta effettivamente illimitato in termini di data di fine.
Promotions / HotelPromotions / Promotion / CheckoutDates / DateRange / @days_of_week 0..1 String

I giorni della settimana consentiti nell'intervallo di date. Se non specificato, saranno consentiti tutti i giorni nell'intervallo di date. Ogni carattere nella stringa specifica un giorno. Ad esempio, "MTWHF" specifica che nell'intervallo di date sono consentiti i giorni feriali.

I caratteri validi sono:

  • M per lunedì
  • T per martedì
  • W per mercoledì
  • H per giovedì
  • F per venerdì
  • S per sabato
  • U per domenica

Sono valide tutte le combinazioni di caratteri.
Promotions / HotelPromotions / Promotion / BookingWindow 0..1 BookingWindow Specifica il periodo di tempo in cui deve essere effettuata la prenotazione rispetto alla data di check-in (in base al fuso orario della proprietà). Ad esempio, è possibile impostare una finestra di prenotazione di almeno 7 giorni, ma non oltre 180 giorni, prima del check-in.
Promotions / HotelPromotions / Promotion / BookingWindow / @min 0..1 Integer Il numero minimo di giorni prima del check-in in cui deve essere effettuata la prenotazione affinché venga applicata la promozione. Se non specificato, non è previsto un limite minimo.
Promotions / HotelPromotions / Promotion / BookingWindow / @max 0..1 Integer Il numero massimo di giorni prima del check-in in cui deve essere effettuata la prenotazione affinché venga applicata la promozione. Se non specificato, non è previsto un limite massimo.
Promotions / HotelPromotions / Promotion / LengthOfStay 0..1 LengthOfStay Definisce il numero minimo e massimo di notti consentito per il soggiorno.
Promotions / HotelPromotions / Promotion / LengthOfStay / @min 0..1 Integer Il numero minimo di notti consentito per il soggiorno affinché venga applicata la promozione. Se non specificato, non è previsto un limite minimo.
Promotions / HotelPromotions / Promotion / LengthOfStay / @max 0..1 Integer Il numero massimo di notti consentito per il soggiorno affinché venga applicata la promozione. Se non specificato, non è previsto un limite massimo.
Promotions / HotelPromotions / Promotion / Discount 1 Discount Specifica lo sconto da applicare a questa promozione.
Promotions / HotelPromotions / Promotion / Discount / @percentage 0..1 Float Nota: è necessario specificare un solo valore tra percentage, fixed_amount e fixed_amount_per_night.

Un valore decimale compreso tra 0 e 100 che specifica la percentuale di sconto. Viene applicato a AmountAfterTax (o AmountBeforeTax se AmountAfterTax non è specificato).

Esempi:

  • Se AmountAfterTax è 100 e percentage è 20, allora

    tariffa promozionale = AmountAfterTax * (1 - percentuale di sconto)

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

  • Se AmountBeforeTax è 100, percentage è 20 e TaxFeeInfo specifica una tassa pari a 10, allora

    tariffa promozionale = AmountBeforeTax * (1 - percentuale di sconto) + tassa

    90,00 = 100 * (1 - 0,2) + 10
Promotions / HotelPromotions / Promotion / Discount / @fixed_amount 0..1 Float Nota: è necessario specificare un solo valore tra percentage, fixed_amount e fixed_amount_per_night.

Un importo fisso che deve essere sottratto dalla somma delle tariffe per notte di AmountAfterTax (o dalla somma delle tariffe per notte di AmountBeforeTax se AmountAfterTax non è specificato). Si presume che la valuta sia la stessa delle tariffe per notte. Se questo valore è maggiore della somma delle tariffe per notte, si avrà un valore pari a zero.

Esempi:

  • Stabilendo il prezzo di un soggiorno di una notte in cui AmountBeforeTax è 90, AmountAfterTax è 100 e fixed_amount è 20, allora

    tariffa promozionale = AmountAfterTax - sconto fisso

    80,00 = 100 - 20

  • Stabilendo il prezzo di un soggiorno di una notte in cui AmountBeforeTax è 100, fixed_amount è 20 e TaxFeeInfo specifica una tassa pari all'8%, allora

    tariffa promozionale = (AmountBeforeTax - sconto fisso) * (1 + tassa percentuale)

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

  • Stabilendo il prezzo di un soggiorno di una notte in cui AmountBeforeTax è 50, fixed_amount è 60 e TaxFeeInfo specifica una tassa pari a 10, allora

    tariffa promozionale = (AmountBeforeTax - sconto fisso) * tassa

    10,00 = 0 + 10

  • Stabilendo il prezzo di un soggiorno di tre notti in cui i valori di AmountAfterTax sono 100, 110 e 120, con fixed_amount pari a 150, allora

    tariffa promozionale = somma (AmountAfterTax) - (sconto fisso)

    180,00 = (100 + 110 + 120) - 150
Promotions / HotelPromotions / Promotion / Discount / @fixed_amount_per_night 0..1 Float Nota: è necessario specificare un solo valore tra percentage, fixed_amount e fixed_amount_per_night.

Uno sconto fisso applicato a ogni tariffa per notte di AmountAfterTax (o alla notte meno costosa se viene specificato applied_nights). Se AmountAfterTax non è specificato, viene applicato a AmountBeforeTax. Si presume che la valuta sia la stessa delle tariffe per notte. Se fixed_amount_per_night è maggiore di una tariffa per notte, tale tariffa sarà ridotta a zero poiché lo sconto non può far diventare negativa una tariffa per notte.

Esempi:

  • Stabilendo il prezzo di un soggiorno di tre notti in cui i valori di AmountAfterTax sono 100, 110 e 120, con fixed_amount_per_night pari a 10, allora

    tariffa promozionale = somma (AmountBeforeTax - importo sconto fisso)

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

  • Stabilendo il prezzo di un soggiorno di tre notti in cui i valori di AmountAfterTax sono 10, 50 e 100, con fixed_amount_per_night pari a 20, allora

    tariffa promozionale = somma (AmountAfterTax - importo sconto fisso)

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

Il numero di notti a cui viene applicato lo sconto, a partire dalla meno costosa. Deve essere un numero intero compreso tra 1 e 99. Se non specificato, lo sconto viene applicato a tutte le notti.
Promotions / HotelPromotions / Promotion / MinimumAmount 0..1 MinimumAmount Specifica la somma minima delle tariffe giornaliere della camera (utilizzando il valore più grande tra AmountBeforeTax e AmountAfterTax) che deve essere superata affinché la promozione venga applicata.
Promotions / HotelPromotions / Promotion / MinimumAmount / @before_discount 1 Integer Il valore che deve essere superato affinché la promozione venga applicata.
Promotions / HotelPromotions / Promotion / Devices 0..1 Devices Container dell'elenco di dispositivi utente idonei alla promozione. Se specificato, la tariffa scontata viene offerta solo agli utenti idonei che utilizzano i dispositivi inseriti nell'elenco. Se non specificato, la tariffa scontata viene offerta agli utenti idonei che utilizzano qualsiasi dispositivo.
Promotions / HotelPromotions / Promotion / Devices / Device 1..3 Device Definisce un tipo di dispositivo utente idoneo alla promozione.
Promotions / HotelPromotions / Promotion / Devices / Device / @type 1 Enum Un tipo di dispositivo. Il valore deve essere desktop, tablet o mobile.
Promotions / HotelPromotions / Promotion / UserCountries 0..1 UserCountries Container dell'elenco relativo alle località degli utenti (paesi) idonei per la promozione. Se specificato, la tariffa scontata viene offerta solo agli utenti idonei che si trovano nei paesi inseriti nell'elenco. Se non specificato, la tariffa scontata viene offerta agli utenti idonei che si trovano in qualunque paese.
Promotions / HotelPromotions / Promotion / UserCountries / Country 1..50 Country Definisce un paese in cui gli utenti sono idonei alla promozione.
Promotions / HotelPromotions / Promotion / UserCountries / Country / @code 1 String Un codice paese CLDR, ad esempio DE o FR. Nota che per alcuni paesi il codice paese CLDR non corrisponde a quello ISO di due lettere. Inoltre, non sono supportati i codici regione CLDR.

Esempi

Messaggio di base

L'esempio seguente mostra un messaggio Promotions di base:

<?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>

Eliminare una promozione

L'esempio seguente mostra come eliminare una promozione relativa a una proprietà:

<?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>

Eliminare tutte le promozioni

L'esempio seguente mostra come eliminare tutte le promozioni relative a una proprietà:

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

Sovrapporre tutte le promozioni

L'esempio seguente mostra come sovrapporre <HotelPromotions> per una proprietà con una o più nuove promozioni. Quando action="overlay", tutte le promozioni archiviate vengono eliminate prima dell'archiviazione delle promozioni specificate nel messaggio corrente:

<?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>