مرجع XML للأسعار ومستودع الغرف (المعاملات)

توفر هذه الصفحة مرجعًا لرسائل المعاملات المستندة إلى XML.

<Transaction>

العنصر الجذر لرسالة المعاملة هو <Transaction>. إنها حاوية للمعلومات الوصفية حول الغرف والحزم وأسعار الغرف والحزم ومدى توفّرها.

يظهر العنصر <Transaction> في المكان التالي ضمن التسلسل الهرمي بتنسيق XML لرسالة المعاملة:

+ <Transaction>
    + <PropertyDataSet>  // Room and package metadata
        + <Property>
        + <RoomData>
        + <PackageData>
    + <Result>           // Pricing and availability
        + <Rates>
        + <RoomBundle>
        + ...

بالنسبة إلى الرسائل التي تستخدم <Transaction> كعنصر جذر، يجب أن تتوفّر عنصرًا ثانويًا واحدًا على الأقل. يمكن أن تحتوي رسائل المعاملات على أي عدد من العناصر الفرعية، طالما لا يتجاوز إجمالي حجم الرسالة 100 ميغابايت.

البنية

يستخدم العنصر <Transaction> البنية التالية:

<?xml version="1.0" encoding="UTF-8"?>
<Transaction timestamp="timestamp" id="transaction_ID">

  <!-- Defines data about a room or package (Room Bundle) -->
  <PropertyDataSet>
    ...
  </PropertyDataSet>

  <!-- Updates/sets prices and availability for rooms and Room Bundles -->
  <!-- (Also removes itineraries from inventory) -->
  <Result>
    ...
  </Result>

</Transaction>

السمات

يحتوي العنصر <Transaction> على السمات التالية:

السمة مطلوب؟ النوع الوصف
id Required سلسلة معرّف فريد لكل رسالة "معاملة"
partner Optional string حساب الشريك الموجّه إليه رسالة "المعاملة" ويمكنك استخدام هذا الخيار عادةً إذا كانت الخلفية توفّر خلاصات أسعار لحسابات شركاء متعدّدة. قيمة السلسلة هذه هي قيمة "مفتاح الشريك" المدرَجة في صفحة إعدادات الحساب في Hotel Center.
timestamp Required DateTime

اللحظة التي تم فيها إرسال رسالة "المعاملة".

ستتم معالجة أي رسالة مُرسَلة ذات طابع زمني خلال آخر 24 ساعة، وسيتم تجاهل الرسائل التي لم يتم إرسالها بعد.

تتم معالجة الرسائل بترتيب timestamp، وليس بترتيب استلامها. على سبيل المثال، ستستمر معالجة السعر الجديد الذي يتضمّن طابعًا زمنيًا بقيمة 2019-05-03 14:09:00 والذي يتم استلامه بعد رسالة تتضمّن طابعًا زمنيًا 2019-05-03 14:10:00، وسيتم استخدام السعر الوارد في الرسالة التي تتضمّن الطابع الزمني 2019-05-03 14:10:00.

العناصر الفرعية

يحتوي العنصر <Transaction> على العناصر الثانوية التالية:

العنصر الفرعي مطلوب؟ النوع الوصف
<PropertyDataSet> Optional* <PropertyDataSet>

تصف هذه السمة حِزم غرف محدّدة وغرفة معيّنة. يمكنك عادةً استخدام هذا العنصر في رسالة "معاملة" منفصلة لتحديد القيم المشتركة لحِزم الغرف وتقليل حجم رسائل "المعاملات".
<Result> Optional* <Result>

بيانات الأسعار لبرنامج رحلة الغرفة أو أحد العناصر <RoomBundle> الذي يحدّد حِزم الغرف والأنواع الإضافية من الغرف في الموقع ويمكن أيضًا استخدام العنصر <Result> لإزالة برامج الرحلات من المستودع.
* يجب توفير سمة واحدة على الأقل من <PropertyDataSet> أو <Result>.

أمثلة

بيانات الغرفة

يحدِّد المثال التالي بيانات الغرف في رسالة "المعاملة":

<?xml version="1.0" encoding="UTF-8"?>
<Transaction timestamp="2017-07-18T16:20:00-04:00" id="42">
  <PropertyDataSet>
    <Property>1234</Property>
    <RoomData>
      <RoomID>5440OF</RoomID>
      <Name>
        <Text text="Single King Bed Room" language="en"/>
        <Text text="Simple Lit de Roi" language="fr"/>
      </Name>
      <Description>
        <Text text="One king bed with pillowtop mattresses, 300-thread-count linens,
          and down comforters (bedspreads). City view. 300 square feet. Desk with
          rolling chair. Multi-line phone with voice mail. Cable/satellite TV with
          complimentary HBO and pay movies." language="en"/>
        <Text text="Un très grand lit avec matelas à plateau-coussin, ..." language="fr"/>
      </Description>
      <PhotoURL>
        <Caption>
          <Text text="Bathroom View" language="en"/>
          <Text text="La salle de baines" language="fr"/>
        </Caption>
        <URL>http://www.foo.com/static/bar/image1234.jpg</URL>
      </PhotoURL>
      <Capacity>4</Capacity>
    </RoomData>
  </PropertyDataSet>
</Transaction>

بيانات الأسعار

يحدد المثال التالي بيانات الأسعار في رسالة "المعاملة":

<?xml version="1.0" encoding="UTF-8"?>
<Transaction timestamp="2017-07-23T16:20:00-04:00" id="42">
  <Result>
    <Property>060773</Property>
    <RoomID>RoomType101</RoomID>
    <PackageID>Package101</PackageID>
    <Checkin>2018-06-10</Checkin>
    <Nights>2</Nights>
    <Baserate currency="USD">278.33</Baserate>
    <Tax currency="USD">25.12</Tax>
    <OtherFees currency="USD">2.00</OtherFees>
    <AllowablePointsOfSale>
      <PointOfSale id="site1"/>
    </AllowablePointsOfSale>
  </Result>
  <Result>
    <Property>052213</Property>
    <RoomID>RoomType101</RoomID>
    <PackageID>Package101</PackageID>
    <Checkin>2018-06-10</Checkin>
    <Nights>2</Nights>
    <Baserate currency="USD">299.98</Baserate>
    <Tax currency="USD">26.42</Tax>
    <OtherFees currency="USD">2.00</OtherFees>
    <AllowablePointsOfSale>
      <PointOfSale id="otto"/>
      <PointOfSale id="simon"/>
    </AllowablePointsOfSale>
  </Result>
</Transaction>

أسعار الإقامة في الليلة

يحدّد المثال التالي بيانات الأسعار لليلة واحدة إلى 7 ليالٍ اعتبارًا من 7 حزيران (يونيو) 2023:

<?xml version="1.0" encoding="UTF-8"?>
<Transaction timestamp="2017-08-24T16:20:00-04:00" id="42">
  <Result>
    <Property>1234</Property>
    <Checkin>2018-06-07</Checkin>
    <Nights>1</Nights>
    <Baserate currency="USD">209.99</Baserate>
    <Tax currency="USD">25.12</Tax>
    <OtherFees currency="USD">2.00</OtherFees>
  </Result>
  <Result>
    <Property>1234</Property>
    <Checkin>2018-06-07</Checkin>
    <Nights>2</Nights>
    <Baserate currency="USD">419.98</Baserate>
    <Tax currency="USD">25.12</Tax>
    <OtherFees currency="USD">2.00</OtherFees>
  </Result>
  <Result>
    <Property>1234</Property>
    <Checkin>2018-06-07</Checkin>
    <Nights>3</Nights>
    <Baserate currency="USD">614.97</Baserate>
    <Tax currency="USD">21.12</Tax>
    <OtherFees currency="USD">2.00</OtherFees>
  </Result>
  <Result>
    <Property>1234</Property>
    <Checkin>2018-06-07</Checkin>
    <Nights>4</Nights>
    <Baserate currency="USD">819.96</Baserate>
    <Tax currency="USD">21.12</Tax>
    <OtherFees currency="USD">2.00</OtherFees>
  </Result>
  <Result>
    <Property>1234</Property>
    <Checkin>2018-06-07</Checkin>
    <Nights>5</Nights>
    <Baserate currency="USD">999.95</Baserate>
    <Tax currency="USD">21.12</Tax>
    <OtherFees currency="USD">2.00</OtherFees>
  </Result>
  <Result>
    <Property>1234</Property>
    <Checkin>2018-06-07</Checkin>
    <Nights>6</Nights>
    <Baserate currency="USD">1193.94</Baserate>
    <Tax currency="USD">21.12</Tax>
    <OtherFees currency="USD">2.00</OtherFees>
  </Result>
  <Result>
    <Property>1234</Property>
    <Checkin>2018-06-07</Checkin>
    <Nights>7</Nights>
    <Baserate currency="USD">1259.93</Baserate>
    <Tax currency="USD">21.12</Tax>
    <OtherFees currency="USD">2.00</OtherFees>
  </Result>
</Transaction>


الأسعار الأساسية والأسعار المشروطة

يوضح المثال التالي رسالة معاملة تحتوي على سعر أساسي وسعر مشروط:

<?xml version="1.0" encoding="UTF-8" ?>
<Transaction timestamp="2023-05-18T16:20:00-04:00" id="42">
  <Result>
    <Property>1234</Property>
    <Checkin>2023-04-10</Checkin>
    <Nights>1</Nights>

    <Baserate currency="USD">200.00</Baserate>
    <Tax currency="USD">20.00</Tax>
    <OtherFees currency="USD">1.00</OtherFees>

    <Rates>
      <!-- The rate_rule_id is required when using conditional rates -->
      <Rate rate_rule_id="mobile">
        <!-- Override base rate and taxes for conditional rates -->
        <Baserate currency="USD">180.00</Baserate>
        <Tax currency="USD">18.00</Tax>
        <!-- NOTE: OtherFees is inherited from the above setting -->
        <Custom1>ratecode123</Custom1>
      </Rate>
    </Rates>

  </Result>
</Transaction>

إزالة المستودع

في المثال التالي، تتم إزالة عدّة مستودعات (إقامات لمدة ليلة واحدة لعدة تواريخ مختلفة) لفندق من المستودع:

<?xml version="1.0" encoding="UTF-8"?>
<Transaction timestamp="2023-05-23T16:20:00-04:00" id="42">
  <Result>
    <Property>1123581321</Property>
    <Checkin>2023-05-23</Checkin>
    <Nights>1</Nights>
    <Unavailable>
      <NoVacancy/>
    </Unavailable>
    <Tax currency="USD">0</Tax>
    <OtherFees currency="USD">0</OtherFees>
  </Result>
  <Result>
    <Property>1123581321</Property>
    <Checkin>2023-05-24</Checkin>
    <Nights>1</Nights>
    <Unavailable>
      <NoVacancy/>
    </Unavailable>
    <Tax currency="USD">0</Tax>
    <OtherFees currency="USD">0</OtherFees>
  </Result>
  <!---Sending <Baserate> is optional with <Unavailable> -->
  <Result>
    <Property>1123581321</Property>
    <Checkin>2023-05-25</Checkin>
    <Nights>1</Nights>
    <Baserate currency="USD">-1</Baserate>
    <Unavailable>
      <NoVacancy/>
    </Unavailable>
    <Tax currency="USD">0</Tax>
    <OtherFees currency="USD">0</OtherFees>
  </Result>
</Transaction>

<PropertyDataSet>

حاوية لمعلومات الغرفة والحزمة (أو حزمة الغرفة) في رسالة <Transaction>. يتمّ تحديد القيم المتعلّقة بقيم إلغاء الفنادق والتي تم ضبطها على أحد الشركاء. تخزّن Google هذه المعلومات بدون الحاجة إلى تحديدها في كل مرة ترسل فيها تعديلات الأسعار.

يظهر العنصر <PropertyDataSet> في المكان التالي ضمن التسلسل الهرمي بتنسيق XML لرسالة المعاملة:

+ <Transaction>
    + <PropertyDataSet>  // Room and package metadata
        + <Property>
        + <RoomData>
        + <PackageData>
    + <Result>  // Pricing and availability
        + <Rates>
        + <RoomBundle>
        + ...

لمزيد من المعلومات، يُرجى الرجوع إلى البيانات الوصفية لحزمة الغرف.

البنية

يستخدم العنصر <PropertyDataSet> البنية التالية:

<?xml version="1.0" encoding="UTF-8"?>
<Transaction ... >
  <PropertyDataSet>
    <!-- (Required) ID that matches the Hotel List Feed -->
    <Property>hotel_ID</Property>

    <!-- (Optional) Defines metadata about a room -->
    <RoomData>
      ...
    </RoomData>

    <!-- (Optional) Defines package metadata to be paired with rooms (Room Bundles) -->
    <PackageData>
      ...
    </PackageData>
  </PropertyDataSet>
  ...
</Transaction>

السمات

لا يتضمّن العنصر <PropertyDataSet> أيّ سمات.

العناصر الفرعية

يحتوي العنصر <PropertyDataSet> على العناصر الثانوية التالية:

العنصر الفرعي مطلوب؟ النوع الوصف
<PackageData> Optional* <PackageData> يصف حزمة الغرف. ترتبط هذه البيانات بشريك وفندق، ولكن ليس ببرنامج رحلة. يشبه هذا العنصر السمة <RoomData>، ولكنّه يصف وسائل الراحة والمصطلحات التي لا تشكّل جزءًا من وصف الغرفة.

أنت تشير إلى رقم تعريف الحِزمة في تعديلات الأسعار.

لمزيد من المعلومات، راجِع البيانات الوصفية لحزمة الغرف.
<Property> Required string رقم تعريف الفندق الذي تنطبق عليه البيانات المرتبطة. ويجب أن تكون قيمة هذا العنصر سلسلة تتطابق مع بطاقة البيانات <id> في خلاصة بيانات الفنادق.
<RoomData> Optional* <RoomData> وصف غرفة. ترتبط هذه البيانات بشريك وفندق، ولكن ليس بمسار رحلة.

أنت تشير إلى رقم تعريف الغرفة في تعديلات الأسعار.
* يجب توفير سمة واحدة على الأقل من <PackageData> أو <RoomData>.

أمثلة

بيانات الغرف والحزمة

يعرض المثال التالي بيانات الغرفة والحزمة في <PropertyDataSet>:

<?xml version="1.0" encoding="UTF-8"?>
<Transaction timestamp="2017-07-18T16:20:00-04:00" id="42">
  <PropertyDataSet>
    <Property>180054</Property>
    <RoomData>
      <RoomID>060773</RoomID>
      <Name>
        <Text text="Single Bed Room" language="en"/>
        <Text text="Chambre single" language="fr"/>
      </Name>
      <Description>
        <Text text="Non-smoking" language="en"/>
        <Text text="Pas de fumiers" language="fr"/>
      </Description>
      <PhotoURL>
        <Caption>
          <Text text="Living area" language="en"/>
          <Text text="Le chambre" language="fr"/>
        </Caption>
        <URL>http://www.foo.com/static/bar/image1234.jpg</URL>
      </PhotoURL>
    </RoomData>
    <PackageData>
      <PackageID>P54321</PackageID>
      <Name>
        <Text text="Breakfast Included" language="en"/>
        <Text text="Avec le petit déjeuner" language="fr"/>
      </Name>
      <Description>
        <Text text="Includes a delightful array of jams and jellies." language="en"/>
        <Text text="Comprend une délicieuse gamme de confitures et gelées." language="fr"/>
      </Description>
      <BreakfastIncluded>1</BreakfastIncluded>
    </PackageData>
  </PropertyDataSet>
</Transaction>

عند إرسال الأسعار ومدى التوفّر لهذه الغرفة وحزمة الغرف، يمكنك الرجوع إلى أرقام تعريف الغرف والحِزم في رسائل الأسعار. والنتيجة هي تقليل حجم الرسائل بشكل كبير وكذلك تقليل عدد الأخطاء التي قد تواجهها بسبب البيانات المكررة. لمزيد من المعلومات، يُرجى الرجوع إلى البيانات الوصفية لحزمة الغرفة.

<RoomData>

تحدّد بيانات وصفية غير مستقلة عن برنامج الرحلة حول الغرف، وبالتالي، تكون "حِزم الغرف" (لأنّ "حِزم الغرف" عبارة عن غرف بالإضافة إلى وسائل راحة إضافية). استخدِم <RoomData> لتقليل تكرار البيانات الوصفية في خلاصة الأسعار.

يظهر العنصر <RoomData> في المكان التالي ضمن التسلسل الهرمي بتنسيق XML لرسالة المعاملة:

+ <Transaction>
    + <PropertyDataSet>  // Room and package metadata
        + <Property>
        + <RoomData>
        + <PackageData>
    + <Result>           // Pricing and availability
        + <Rates>
        + <RoomBundle>
        + ...

تحتوي عناصر <RoomData> على معلومات مرتبطة بشريك وفندق، ولكن ليس ببرنامج رحلة. الغرض المقصود هو جميع البيانات غير خطية.

العنصر <RoomData> يشبه <PackageData>، لكنه يصف الغرفة الفعلية بدلاً من وسائل الراحة وبنود الحزمة. يمكنك استخدام <RoomData> و<PackageData> معًا لتقديم تفاصيل حول حِزم الغرف. بالنسبة إلى الغرف الفردية التي ليست جزءًا من باقة، استخدِم <RoomData> فقط.

يمكنك تحديد كل من العنصرين <RoomData> و<PackageData> للغرفة أو مجموعة الغرفة نفسها. عندما تعرض Google تلك الغرفة أو الحزمة في نتائج البحث، سيتم تضمين الأوصاف من كليهما، مع الفصل بينها بواصلة.

لمزيد من المعلومات، يُرجى الرجوع إلى البيانات الوصفية لحزمة الغرف.

البنية

يستخدم العنصر <RoomData> البنية التالية:

<?xml version="1.0" encoding="UTF-8"?>
<Transaction ... >
  <PropertyDataSet>
    ...
    <RoomData>
      <RoomID>room_ID</RoomID>

      <Name>
        <Text text="room_name" language="language_code"/>
        ...
      </Name>

      <Description>
        <Text text="room_description" language="language_code"/>
        ...
      </Description>

      <Capacity>max_number_of_occupants</Capacity>
      <Occupancy>max_number_of_intended_occupants</Occupancy>
      <OccupancyDetails> <!-- optional info about the types of guests,
      whether adults, children, or seniors --></OccupancyDetails>
      <OccupancySettings>
        <MinOccupancy>min_number_of_occupants</MinOccupancy>
        <MinAge>min_age_of_occupants</MinAge>
      </OccupancySettings>

      <PhotoURL>
        <Caption>
          <Text text="photo_description" language="language_code"/>
          ...
        </Caption>
        <URL>photo_location</URL>
      </PhotoURL>
      <RoomFeatures>
        ...
      </RoomFeatures>
    </RoomData>
    ...
  </PropertyDataSet>
</Transaction>

السمات

لا يتضمّن العنصر <RoomData> أيّ سمات.

العناصر الفرعية

يحتوي العنصر <RoomData> على العناصر الثانوية التالية:

العنصر الفرعي مطلوب؟ النوع الوصف
<Capacity> Optional integer تمثّل هذه السمة الحدّ الأقصى لعدد الضيوف الذي يمكن استيعابه فعليًا في الغرفة. بالنسبة إلى الغرفة، تكون السعة أكبر من أو تساوي عدد النزلاء.

وعند تحديدها، يجب أن تساوي هذه القيمة قيمة العنصر <Occupancy> أو أكبر منها، وهي العدد المقصود للضيوف لغرفة معيّنة. على سبيل المثال، قد يكون <Capacity> لحزمة كبيرة 6، في حين أنّ <Occupancy> له 4.

ويجب أن تكون قيمة <Capacity> عددًا صحيحًا موجبًا يتراوح بين 1 و20، بما في ذلك القيم الواقعة بينهما.
<Description> Optional Object وصف تفصيلي للغرفة. يجب أن يحتوي هذا العنصر على معلومات لا تصفها عناصر أخرى أو عنصر <Name>. يجب عدم استخدام أحرف كبيرة بالكامل عند تحديد وصف الغرفة.

يأخذ العنصر <Description> عنصرًا فرعيًا واحدًا، وهو <Text>، ويحتوي على السمتين المطلوبتين التاليتين:

  • text: وصف تفصيلي للغرفة
  • language: رمز لغة مكوَّن من حرفين، مثل fr

استخدِم عنصر <Text> منفصلاً لكل لغة قد يظهر بها الإعلان أو رابط الحجز المجاني (بقيم مختلفة لسمات language).

يعرض المثال التالي نسختَين باللغتَين الفرنسية والإنجليزية لوصف الغرفة:

<Description>
  <Text text="Two queen-sized beds" language="en"/>
  <Text text="Deux lits de la reine" language="fr"/>
</Description>
<Name> Required string اسم فئة الغرفة. ويجب أن تتطابق هذه القيمة مع ما يظهر على الصفحة المقصودة للفندق (المعروفة سابقًا باسم نقطة البيع). لا تضبط قيمة هذا العنصر على أحرف كبيرة بالكامل.

يأخذ هذا العنصر عنصرًا فرعيًا واحدًا، وهو <Text>، ويحتوي على السمتين المطلوبتين التاليتين:

  • text: اسم الغرفة
  • language: رمز لغة مكوَّن من حرفين، مثل fr

استخدِم عنصر <Text> منفصلاً لكل لغة قد يظهر بها الإعلان أو رابط الحجز المجاني (بقيم مختلفة لسمات language).

يعرض المثال التالي نسختَي اللغة الفرنسية والإنجليزية من اسم الغرفة:

<Name>
  <Text text="Standard Double Room" language="en"/>
  <Text text="Le chambre double" language="fr"/>
</Name>
<Occupancy> Optional integer الحدّ الأقصى لعدد الضيوف المخصّصة للغرفة. على سبيل المثال، قد يتّسع جناح كبير فعليًا لـ 6 نزلاء (السعة = 6 نزلاء)، ولكنه مُخصّص لما يصل إلى 4 نزلاء فقط.

يجب أن تكون هذه القيمة أقل من أو مساوية للعنصر <Capacity>، وهو عدد الأشخاص الذين يمكن أن تتسع لهم الغرفة.

ويجب أن تكون قيمة <Occupancy> عددًا صحيحًا موجبًا بين 1 و99، بشكل شامل.

وقد تكون سمة <Occupancy> مصحوبةً بالسمة <OccupancyDetails> التي تحدّد نوع الضيوف (الأشخاص البالغون أو الأطفال). يُرجى الرجوع إلى <OccupancyDetails> للتعرّف على بنية العناصر الفرعية ووصفها.
<OccupancySettings> Optional Object الإعدادات التي يمكنها تقييد متطلبات إشغال الغرفة أو تعديلها.

يأخذ العنصر <OccupancySettings> العناصر الثانوية التالية:

  • <MinOccupancy>: الحدّ الأدنى لعدد النزلاء الذين يمكنهم الإقامة في غرفة. على سبيل المثال، إذا تم ضبط السياسة على 2، لا يمكن حجز هذه الغرفة لضيف واحد.

    ويجب أن تكون قيمة <MinOccupancy> عددًا صحيحًا موجبًا بين 1 و99، بشكل شامل.

  • <MinAge>: الحدّ الأدنى لعمر جميع النزلاء المقيمين في غرفة. على سبيل المثال، إذا تمّ ضبط الغرفة على 18، لا يمكن حجز هذه الغرفة إلا للمجموعات التي يبلغ فيها جميع المدعوين 18 عامًا أو أكثر.

    يجب أن تكون قيمة <MinAge> عددًا صحيحًا موجبًا بين 0 و99، بما في ذلك القيم الواقعة بينهما.

<OccupancySettings>
  <MinOccupancy>2</MinOccupancy>
  <MinAge>16</MinAge>
</OccupancySettings>

لا يلزم تضمين كل العناصر الفرعية.
<PhotoURL> Optional Object عنوان URL وتسمية توضيحية اختيارية لصورة للغرفة أو مجموعة الغرف. ويمكنك تحديد أكثر من سمة <PhotoURL> واحدة للغرفة أو لحزمة غرف. يجب أن يكون لكل عنوان URL لصورة في <PhotoURL> خاص به.

يأخذ هذا العنصر العناصر الفرعية التالية:

  • <URL>: لتحديد موقع الصورة. يجب أن يكون الموقع الجغرافي علنيًا (ليس محميًا بجدار حماية) وأن يتضمّن البروتوكول (مثل https://). استخدِم <URL> واحدًا فقط لكل <PhotoURL>.
  • <Caption>: لتحديد الشرح للصورة. يأخذ هذا العنصر عنصرًا فرعيًا واحدًا، وهو <Text>، وله سمتان مطلوبتان، هما: text وlanguage. السمة text هي الشرح، أمّا السمة language، فتحدّد رمز لغة مؤلفًا من حرفَين، مثل en.

مثال:

<PhotoURL>
  <URL>https://www.example.com/static/bar/image1234.jpg</URL>
  <Caption>
    <Text text="A bright and breezy way to enjoy your mornin'
      cuppa tea." language="en"/>
    <Text text="Une façon lumineuse et aérée pour profiter
      de votre journée tasse de thé." language="fr"/>
  </Caption>
</PhotoURL>
<PhotoURL>
  <URL>https://www.foo.com/static/bar/image5678.jpg</URL>
  <Caption>
    <Text text="Or, perhaps you prefer coffee." language="en"/>
    <Text text="Ou peut-être préférez-vous le café." language="fr"/>
  </Caption>
</PhotoURL>
<RoomFeatures> Optional <RoomFeatures> يحتوي على معلومات عن ميزات الغرفة.
<RoomID> Required string المعرّف الفريد للغرفة. يمكنك استخدام رقم التعريف هذا لمطابقة بيانات الغرفة مع عناصر <Result> في تعديلات الأسعار. لمزيد من المعلومات، يُرجى الرجوع إلى البيانات الوصفية لحزمة الغرف. (يمكنك أيضًا استخدام هذا المعرّف للإشارة إلى تعريف مشترك للغرفة في رسالة معاملة واحدة عند تحديد بيانات الغرفة بشكل مضمّن).

أمثلة

بيانات الغرفة

يحدِّد المثال التالي بيانات الغرفة:

<?xml version="1.0" encoding="UTF-8"?>
<Transaction timestamp="2017-07-18T16:20:00-04:00" id="42">
  <PropertyDataSet>
    <Property>1234</Property>
    <RoomData>
      <RoomID>5440OF</RoomID>
      <Name>
        <Text text="Single King Bed Room" language="en"/>
        <Text text="Simple Lit de Roi" language="fr"/>
      </Name>
      <Description>
        <Text text="One king bed with pillowtop mattresses, 300-thread-count linens,
          and down comforters (bedspreads). City view. 300 square feet. Desk with
          rolling chair. Multi-line phone with voice mail. Cable/satellite TV with
          complimentary HBO and pay movies." language="en"/>
        <Text text="Un très grand lit avec matelas à plateau-coussin, ..." language="fr"/>
      </Description>
      <PhotoURL>
        <Caption>
          <Text text="Bathroom View" language="en"/>
          <Text text="La salle de baines" language="fr"/>
        </Caption>
        <URL>http://www.foo.com/static/bar/image1234.jpg</URL>
      </PhotoURL>
      <Capacity>4</Capacity>
    </RoomData>
  </PropertyDataSet>
</Transaction>

البيانات الوصفية للغرفة والحزمة

يحدّد المثال التالي البيانات الوصفية للغرفة والحزمة:

<?xml version="1.0" encoding="UTF-8"?>
<Transaction timestamp="2017-07-18T16:20:00-04:00" id="42">
  <PropertyDataSet>
    <Property>180054</Property>
    <RoomData>
      <RoomID>060773</RoomID>
      <Name>
        <Text text="Single Bed Room" language="en"/>
        <Text text="Chambre single" language="fr"/>
      </Name>
      <Description>
        <Text text="Non-smoking" language="en"/>
        <Text text="Pas de fumiers" language="fr"/>
      </Description>
      <PhotoURL>
        <Caption>
          <Text text="Living area" language="en"/>
          <Text text="Le chambre" language="fr"/>
        </Caption>
        <URL>http://www.foo.com/static/bar/image1234.jpg</URL>
      </PhotoURL>
    </RoomData>
    <PackageData>
      <PackageID>P54321</PackageID>
      <Name>
        <Text text="Breakfast Included" language="en"/>
        <Text text="Avec le petit déjeuner" language="fr"/>
      </Name>
      <Description>
        <Text text="Includes a delightful array of jams and jellies." language="en"/>
        <Text text="Comprend une délicieuse gamme de confitures et gelées." language="fr"/>
      </Description>
      <BreakfastIncluded>1</BreakfastIncluded>
    </PackageData>
  </PropertyDataSet>
</Transaction>

مجموعات غرف متعددة

يحدّد المثال التالي البيانات الوصفية للغرفة والحزمة لحِزم غرف متعددة:

<?xml version="1.0" encoding="UTF-8"?>
<Transaction timestamp="2017-07-18T16:20:00-04:00" id="42">
  <!-- A transaction message with room types result. -->
  <PropertyDataSet>
    <Property>12345</Property>
    <RoomData>
      <RoomID>single</RoomID>
      <Name>
        <Text text="Single room" language="en"/>
        <Text text="Chambre simple" language="fr"/>
      </Name>
      <Description>
        <Text text="A single room" language="en"/>
        <Text text="Le chambre simple" language="fr"/>
      </Description>
      <PhotoURL>
        <Caption>
          <Text text="Living area" language="en"/>
          <Text text="Le chambre" language="fr"/>
        </Caption>
        <URL>http://www.foo.com/static/bar/image1234.jpg</URL>
      </PhotoURL>
      <PhotoURL>
        <URL>http://www.foo.com/static/bar/image1235.jpg</URL>
      </PhotoURL>
      <Capacity>2</Capacity>
    </RoomData>
    <RoomData>
      <RoomID>double</RoomID>
      <Name>
        <Text text="Double room" language="en"/>
        <Text text="Chambre double" language="fr"/>
      </Name>
      <Occupancy>1</Occupancy>
    </RoomData>
    <PackageData>
      <PackageID>refundbreakfast</PackageID>
      <Name>
        <Text text="Refundable Room with Breakfast" language="en"/>
        <Text text="Chambre remboursable avec le petit déjeuner" language="fr"/>
      </Name>
      <Description>
        <Text text="Continental Breakfast" language="en"/>
        <Text text="Petit déjeuner continental" language="fr"/>
      </Description>
      <ChargeCurrency>hotel</ChargeCurrency>
      <Refundable available="1" refundable_until_days="3"/>
      <BreakfastIncluded>1</BreakfastIncluded>
    </PackageData>
    <PackageData>
      <PackageID>prepaid</PackageID>
      <Name>
        <Text text="Nonrefundable" language="en"/>
        <Text text="Non remboursable" language="fr"/>
      </Name>
      <Description>
        <Text text="Blah blah blad" language="en"/>
        <Text text="Le blah blah blad" language="fr"/>
      </Description>
      <Occupancy>2</Occupancy>
      <ChargeCurrency>web</ChargeCurrency>
      <Refundable available="0"/>
    </PackageData>
  </PropertyDataSet>
</Transaction>

<RoomFeatures>

تحدد الميزات الموجودة في الغرفة.

يظهر العنصر <RoomFeatures> في المكان التالي ضمن التسلسل الهرمي بتنسيق XML لرسالة المعاملة:

+ <Transaction>
    + <PropertyDataSet>  // Room and package metadata
        + <Property>
        + <RoomData>
            + <RoomFeatures>

البنية

يستخدم العنصر <RoomFeatures> البنية التالية:

<?xml version="1.0" encoding="UTF-8"?>
<Transaction ... >
  <PropertyDataSet ... >
    ...
    <RoomData>
      <RoomFeatures>
        <JapaneseHotelRoomStyle>[western|japanese|japanese_western]</JapaneseHotelRoomStyle>
        <Beds>
           <Bed size="[single|semi_double|double|queen|king]">
             <Width unit="cm" number="width"/>
             <Length unit="cm" number="length"/>
           </Bed>
           <!-- Include with any additional beds. -->
        </Beds>
        <Suite/>
        <Capsule/>
        <Roomsharing>[shared|private]</Roomsharing>
        <Outdoor/>
        <MobilityAccessible/>
        <Smoking>[smoking|non_smoking]</Smoking>
        <BathAndToilet relation="[together|separate]">
          <Bath bathtub="[false|true]" shower="[false|true]"/>
          <Toilet electronic_bidet="[false|true]" mobility_accessible="[false|true]"/>
        </BathAndToilet>
        <OpenAirBath/>
        <AirConditioning/>
        <Balcony/>
        <Views>
          <!-- (Optional) Defines the type of views from the room. -->
          <!-- Example: <OceanView/> -->
        </Views>

      </RoomFeatures>
      ...
    </RoomData>
    ...
  </PropertyDataSet>
</Transactions>

السمات

لا يتضمّن العنصر <RoomFeatures> أيّ سمات.

العناصر الفرعية

يحتوي العنصر <RoomFeatures> على العناصر الثانوية التالية:

العنصر الفرعي مطلوب؟ النوع الوصف
<JapaneseHotelRoomStyle> Optional enum

يشير إلى نمط غرفة فندق ياباني.

القيم الصالحة هي:

  • western: غرفة على الطراز الغربي فيها أسرّة
  • japanese: غرفة على الطراز الياباني فيها أسرّة فوتون
  • japanese_western: غرفة على الطراز الياباني الغربي فيها أسرّة على الطراز الغربي ومقاعد فوتون على الطراز الياباني
<Beds> Optional Object تحتوي على أكبر عدد ممكن من "<Bed>" في الغرفة. يُرجى العِلم أنّه لا يجب احتساب مقاعد الفوتون اليابانية هنا.

يتضمّن كل <Bed> السمات التالية:

  • size (اختياري): القيم الصالحة هي single وsemi_double وdouble وqueen وking.
يحتوي كل <Bed> على العناصر الثانوية التالية:
  • <Width> (اختياري): لتحديد عرض السرير. ويجب إضافة السمة unit مع القيمة cm والسمة number مع عرض السرير بأعداد صحيحة.
  • <Length> (اختياري): لتحديد طول السرير. يجب أن تتوفّر السمة unit مع القيمة cm والسمة number مع طول السرير بأعداد صحيحة بسنتيمتر.
مثال: 
<Beds>
  <Bed size="double">
    <Width unit="cm" number="140"/>
    <Length unit="cm" number="195"/>
  </Bed>
  <Bed/> <!-- Size unknown -->
</Beds>
<Suite> Optional empty يمكنك توفير هذا العنصر عندما تكون هذه الغرفة جناحًا.
<Capsule> Optional empty توفير هذا العنصر عندما تكون هذه الغرفة عبارة عن غرفة صغيرة جدًا
<Roomsharing> Optional enum تُستخدَم لتحديد ما إذا كانت هذه الغرفة مشترَكة مع ركّاب آخرين، مثل المالكين أو الضيوف الآخرين. القيمتان الصالحتان هما shared وprivate.
<Outdoor> Optional empty يمكنك توفير هذا العنصر عندما تكون هذه الغرفة عبارة عن بيت ضيافة في الهواء الطلق ليس فيه جدران ثابتة وسباكة ونظام التحكّم في المناخ. على سبيل المثال، لا تُعدّ غرف الفنادق أماكن إقامة في الهواء الطلق، في حين أنّ مواقع التخييم التي يقيم فيها النزلاء في خيام ومتنزّهات للمركبات الترفيهية حيث يجلب النزلاء مركبتهم الترفيهية الخاصة بهم هي أماكن إقامة في الهواء الطلق.
<MobilityAccessible> Optional empty توفير هذا العنصر عندما تكون هذه الغرفة متاحة للتنقل
<Smoking> Optional enum تُستخدَم لتحديد ما إذا كانت هذه الغرفة مخصّصة لغير المدخنين. القيمتان الصالحتان هما non_smoking وsmoking.
<BathAndToilet> Optional Object تحتوي على معلومات عن حمّام ومرحاض في الغرفة.

السمة هي:

  • relation (اختيارية): تشير إلى كيفية وضع الحمام والمرحاض معًا. القيمتان الصالحتان هما together (يقع كلّ من الحمّام والمرحاض معًا في الغرفة نفسها (مثل الحمّام) بجانب بعضهما مباشرةً) وseparate (لكلّ من الحمّام والمرحاض مساحات مخصّصة). يجب عدم ضبط هذه السمة عندما لا تحتوي الغرفة على حمّام ومرحاض معًا.

يأخذ العنصر بشكل اختياري العناصر الفرعية التالية:

  • <Bath> (اختياري): يشير توفُّر هذا العنصر إلى أنّ الغرفة تضمّ حوض استحمام.

    السمات هي:

    • bathtub (اختيارية): تشير إلى أنّ الحمّام يحتوي على حوض استحمام في الحمّام. القيمتان الصالحتان هما 0 (أو false) و1 (أو true).
    • shower (مَعلمة اختيارية): تشير إلى أنّه يتضمّن دُشًا. القيمتان الصالحتان هما 0 (أو false) و1 (أو true).
  • <Toilet> (اختيارية): يشير استخدام هذا العنصر إلى أنّ هذه الغرفة تحتوي على مرحاض.

    السمات هي:

    • electronic_bidet (اختيارية): تشير إلى أنّ المرحاض يحتوي على بيديه إلكتروني. القيمتان الصالحتان هما 0 (أو false) و1 (أو true).
    • mobility_accessible (اختيارية): تشير إلى أنّه يمكن التنقّل في المرحاض. القيمتان الصالحتان هما 0 (أو false) و1 (أو true).

مثال:

<BathAndToilet relation="separate">
  <Bath bathtub="1" shower="1"/>
  <Toilet
    electronic_bidet="1"
    mobility_accessible="1"/>
</BathAndToilet>
<OpenAirBath> Optional empty توفير هذا العنصر عندما تحتوي هذه الغرفة على حمّام خاص في الهواء الطلق
<AirConditioning> Optional empty يجب توفير هذا العنصر عندما تحتوي هذه الغرفة على مكيّفات هواء.
<Balcony> Optional empty يجب توفير هذا العنصر عندما تحتوي هذه الغرفة على شرفة أو شرفة.
<Views> Optional Object تشمل الخيارات الصالحة ما يلي:

<AirportView/>
<BayView/>
<BeachView>/>
<CastleView/>
<CityView/>
<CountrysideView/>
<CourtyardView/>
<DuneView/>
<ForestView/>
<GardenView/>
<GolfCourseView/>
<HarborView/>
<LagoonView/>
<LakeView/>
<MarinaView/>
<MountainView/>
<NatureView/>
<OceanView/>
<ParkView/>
<PartialOceanView/>
<PisteView/>
<PoolView/>
<PyramidView/>
<RiverView/>
<StreetView/>

أمثلة

لا تحتوي السمة JapaneseHotelRoomStyle على قيمة تلقائية. ولا يؤدي إغفال قيمة إلى خطأ XML، ولكن لا تظهر بطاقة بيانات نشاطك التجاري في نتائج البحث عندما يجري المستخدم تصفية حسب نمط الغرفة أو الأسرّة.

سريران مفردان

يوضّح المثال التالي كيفية استخدام <RoomFeatures>:

<?xml version="1.0" encoding="UTF-8"?>
<Transaction timestamp="2017-07-18T16:20:00-04:00" id="42">
  <PropertyDataSet>
    <Property>1234</Property>
    <RoomData>
      <RoomID>RoomID_1</RoomID>
      <RoomFeatures>
        <JapaneseHotelRoomStyle>western</JapaneseHotelRoomStyle>
        <Beds> <!-- Two single beds -->
          <Bed size="single">
            <Width unit="cm" number="97"/>
            <Length unit="cm" number="195"/>
          </Bed>
          <Bed size="single">
            <Width unit="cm" number="97"/>
            <Length unit="cm" number="195"/>
          </Bed>
        </Beds>
        <Suite/>
        <Capsule/>
        <Roomsharing>private</Roomsharing>
        <Outdoor/>
        <MobilityAccessible/>
        <Smoking>non_smoking</Smoking>
        <BathAndToilet relation="separate">
          <Bath bathtub="1" shower="1"/>
          <Toilet electronic_bidet="1" mobility_accessible="1"/>
        </BathAndToilet>
        <OpenAirBath/>
        <AirConditioning/>
        <Balcony/>
        <Views>
          <LakeView/>
          <MarinaView/>
          <BeachView/>
          <ForestView/>
          <MountainView/>
          <NatureView/>
        </Views>
      </RoomFeatures>
    </RoomData>
  </PropertyDataSet>
</Transaction>

سريران مزدوجان

في ما يلي مثال على غرفة يابانية بطراز western تضمّ سريرَين double.

<?xml version="1.0" encoding="UTF-8"?>
<Transaction timestamp="2023-07-23T16:20:00-04:00" id="42">
  <PropertyDataSet>
    <Property>1234</Property>
    <RoomData>
      <RoomID>RoomID_1</RoomID>
      <RoomFeatures>
        <JapaneseHotelRoomStyle>western</JapaneseHotelRoomStyle>
        <Beds> <!-- Two double beds-->
          <Bed size="double"></Bed>
          <Bed size="double"></Bed>
        </Beds>
      </RoomFeatures>
    </RoomData>
  </PropertyDataSet>
</Transaction>


الطراز الياباني بدون سرير

في ما يلي مثال على غرفة على الطراز الياباني بدون سرير. إنّ معلومات السرير غير مطلوبة لغرفة بتصميم japanese.

<?xml version="1.0" encoding="UTF-8"?>
<Transaction timestamp="2023-07-23T16:20:00-04:00" id="42">
  <PropertyDataSet>
    <Property>1234</Property>
    <RoomData>
      <RoomID>RoomID_1</RoomID>
      <RoomFeatures>
        <JapaneseHotelRoomStyle>japanese</JapaneseHotelRoomStyle>
      </RoomFeatures>
    </RoomData>
  </PropertyDataSet>
</Transaction>

موسيقى غربية يابانية مع سرير

في ما يلي مثال على غرفة بنمط "japanese_western" تضمّ سريرًا بحجم king.

<?xml version="1.0" encoding="UTF-8"?>
<Transaction timestamp="2023-07-23T16:20:00-04:00" id="42">
  <PropertyDataSet>
    <Property>1234</Property>
    <RoomData>
      <RoomID>RoomID_1</RoomID>
      <RoomFeatures>
        <JapaneseHotelRoomStyle>japanese_western</JapaneseHotelRoomStyle>
        <Beds>
          <Bed size="king"></Bed>
        </Beds>
      </RoomFeatures>
    </RoomData>
  </PropertyDataSet>
</Transaction>

إذا لم يكن لدى الشريك معلومات عن عدد الأسرّة في japanese_western غرفة، يمكنك اتّباع المثال:

<?xml version="1.0" encoding="UTF-8"?>
<Transaction timestamp="2023-07-23T16:20:00-04:00" id="42">
  <PropertyDataSet>
    <Property>1234</Property>
    <RoomData>
      <RoomID>RoomID_1</RoomID>
      <RoomFeatures>
        <JapaneseHotelRoomStyle>japanese_western</JapaneseHotelRoomStyle>
      </RoomFeatures>
    </RoomData>
  </PropertyDataSet>
</Transaction>

<PackageData>

تحدِّد هذه السياسة بيانات وصفية مستقلة عن برنامج الرحلة حول حِزم الغرف لأحد المواقع. يحتوي هذا العنصر على معلومات مرتبطة بشريك وفندق، ولكن ليس بمسار رحلة. الغرض المقصود هو تحديد جميع البيانات غير المتعلقة بمسار الرحلة مرة واحدة والإشارة إليها من بيانات برنامج الرحلة.

يظهر العنصر <PackageData> في المكان التالي ضمن التسلسل الهرمي بتنسيق XML لرسالة المعاملة:

+ <Transaction>
    + <PropertyDataSet>  // Room and package metadata
        + <Property>
        + <RoomData>
        + <PackageData>
    + <Result>           // Pricing and availability
        + <Rates>
        + <RoomBundle>
        + ...

العنصر <PackageData> مشابه للعنصر <RoomData>، لكنه يصف ميزات السعر وعباراته التي لا تشكّل جزءًا من وصف الغرفة. يمكنك استخدام <RoomData> و<PackageData> معًا لتقديم تفاصيل حول حِزم الغرف وميزات الأسعار. بالنسبة إلى الغرف الفردية التي ليست جزءًا من باقة، استخدِم <RoomData> فقط.

يمكنك تحديد كلٍّ من العنصرَين <RoomData> و<PackageData> للغرفة أو مجموعة الغرفة نفسها. عندما تعرض Google تلك الغرفة أو الحزمة في نتائج البحث، سيتم تضمين الأوصاف من كليهما، مع الفصل بينها بواصلة.

إذا عدَّلت عنصر <PackageData> واحد لإحدى المواقع، عليك تعديل كل عناصر <PackageData> و<RoomData> لهذه السمة. ويتم اعتبار كل <PropertyDataSet> جميع البيانات المتعلقة بالموقع الإلكتروني، وتستبدل أي بيانات حالية.

لمزيد من المعلومات، يُرجى الرجوع إلى البيانات الوصفية لحزمة الغرف.

البنية

يستخدم العنصر <PackageData> البنية التالية:

<?xml version="1.0" encoding="UTF-8"?>
<Transaction ... >
  <PropertyDataSet ... >
    <PackageData>
      <PackageID>package_ID</PackageID>
      <Name>
        <Text text="package_name" language="language_code"/>
        ...
      </Name>
      <Description>
        <Text text="package_description" language="language_code"/>
        ...
      </Description>
      <Refundable available="[false|true]" refundable_until_days="number_of_days"
        refundable_until_time="time"/>
      <ChargeCurrency>[deposit|hotel|installments|web]</ChargeCurrency>
      <Occupancy>max_number_of_intended_occupants</Occupancy>
      <OccupancyDetails><!-- optional info about the types of guests,
      whether adults or children --></OccupancyDetails>
      <!-- For these next 3 elements, boolean_value can be 0/1 or true/false -->
      <BreakfastIncluded>boolean_value</BreakfastIncluded>
      <InternetIncluded>boolean_value</InternetIncluded>
      <ParkingIncluded>boolean_value</ParkingIncluded>
      <PhotoURL>
        <Caption>
          <Text text="photo_description" language="language_code"/>
          ...
        </Caption>
        <URL>photo_location</URL>
      </PhotoURL>
      ...
      <Meals>
        <Breakfast
          included="[true|false]" buffet="[true|false]"
          in_room="[true|false]" in_private_space="[true|false]"/>
        <Dinner
          included="[true|false]" buffet="[true|false]"
          in_room="[true|false]" in_private_space="[true|false]"/>
      </Meals>
      <CheckinTime>checkin_time</CheckinTime>
      <CheckoutTime>checkout_time</CheckoutTime>
      <MembershipBenefitsIncluded>
        <ProgramName>
          <Text language="en" text="Special Rewards">
        </ProgramName>
        <ProgramLevel>
          <Text language="en" text="Platinum">
        </ProgramLevel>
      </MembershipBenefitsIncluded>
      <OnPropertyCredit>
        <Amount currency="USD">123.45</Amount>
      </OnPropertyCredit>
    </PackageData>
    <!-- a PackageID with a MilesIncluded rate feature -->
    <PackageData>
      <PackageID>room_with_miles</PackageID>
      <Name>
       <Text text="Room with Bundled Miles" language="en">
      </Name>
      <ChargeCurrency>hotel </ChargeCurrency>
      <MilesIncluded>
        <NumberOfMiles>1000 </NumberOfMiles>
        <Provider>
          <Text language="en" text="United Airlines">
        </Provider>
      </MilesIncluded>
    </PackageData>
    ...
    ...
  </PropertyDataSet>
  ...
</Transaction>

السمات

لا يتضمّن العنصر <PackageData> أيّ سمات.

العناصر الفرعية

يحتوي العنصر <PackageData> على العناصر الثانوية التالية:

العنصر الفرعي مطلوب؟ النوع الوصف
<BreakfastIncluded> Optional boolean تحدِّد هذه السياسة ما إذا كانت هذه الحزمة تتضمّن وجبة الفطور مع السعر. القيمتان الصالحتان هما 0 (أو false) و1 (أو true).

ومن المفضّل استخدام <Meals> بدلاً من <BreakfastIncluded>.
<ChargeCurrency> Optional enum متى وأين يدفع المستخدم مقابل الحجز. يستخدم هذا العنصر البنية نفسها المستخدَمة في <ChargeCurrency> في <Result>.

تكون القيمة التلقائية web.
<CheckinTime> Optional Time أقرب وقت ممكن لتسجيل الوصول. يجب أن يكون الوقت أقل من 24:00 بالتوقيت المحلي للفندق.
<CheckoutTime> Optional Time آخر وقت ممكن لتسجيل المغادرة بالتوقيت المحلي من الفندق.
<Description> Optional Object وصف مفصل للطرد. يجب أن يحتوي هذا العنصر على معلومات لا تصفها عناصر أخرى أو عنصر <Name>. يجب عدم استخدام أحرف كبيرة بالكامل عند تحديد وصف الغرفة.

يستخدم العنصر <Description> عنصرًا ثانويًا واحدًا، وهو <Text>، ويحتوي على سمتَين مطلوبتَين، هما text وlanguage. تمثّل السمة text الوصف، بينما تحدد السمة language رمز لغة مؤلفًا من حرفَين، على النحو الموضّح في المثال التالي:

<Description>
  <Text text="Two breakfast buffet certificates for
    each night of stay." language="en"/>
  <Text text="Deux certificats petit-déjeuner buffet
    pour chaque nuit de séjour." language="fr"/>
</Description>
<InternetIncluded> Optional boolean وإذا كانت الحزمة تتضمّن إمكانية الوصول إلى الإنترنت بدون أي رسوم، لن تتضمّن الحزم الأخرى هذه وسائل الراحة. لا تضبط هذا العنصر لحِزم الغرف في فندق يوفّر خدمة إنترنت مجانية لجميع الغرف. لا ينطبق هذا العنصر على الإنترنت السلكي داخل الغرفة أو الإنترنت اللاسلكي غير المتوفّر في غرف النزلاء. القيمتان الصالحتان هما 0 (أو false) و1 (أو true).
<Meals> Optional Object تحتوي على معلومات حول الوجبات المضمّنة في هذه الحزمة.

يستخدم العنصر <Meals> عنصرَين ثانويَين اختياريَين، <Breakfast> و<Dinner>، واللذين يتضمّنان السمات التالية:

  • included (مطلوبة): يجب ضبطها على 1 (أو true) إذا كان السعر يشمل الفطور/العشاء، أو على 0 أو false.
  • in_room (اختياري): اضبط السمة على 1 (أو true) إذا كان بإمكان الضيوف تناول الفطور/العشاء في الغرفة التي يقيمون فيها، أو سيتم ضبطها على 0 (أو false).
  • in_private_space (اختياري): اضبط السمة على 1 (أو true) إذا كان بإمكان الضيوف تناول الفطور/العشاء في مساحة (باستثناء الغرفة التي يقيمون فيها) حيث يمكنهم تجنُّب التواصل مع نزلاء آخرين، أو بدلاً من ذلك، يتم ضبطها على 0 (أو false).
  • buffet (اختيارية): يتم ضبطها على 1 (أو true) إذا كان الفطور/العشاء يقدّمان بوفيه، أو يتم ضبطه على 0 (أو false).

يتم استخدام السمات الاختيارية فقط عندما تكون السمة included true.

لكي تعمل فلاتر الوجبات (no meals وbreakfast only وdinner only وbreakfast and dinner) بشكل صحيح، يجب إضافة السمة included إلى كلّ من <Breakfast> و<Dinner>.
<Name> Required string اسم الحِزمة ويجب أن تتطابق هذه القيمة مع ما يظهر على الصفحة المقصودة للفندق. لا تضبط قيمة هذا العنصر على أحرف كبيرة بالكامل.

يأخذ هذا العنصر عنصرًا فرعيًا واحدًا، وهو <Text>، له سمتان، هما text وlanguage. تمثّل السمة text الوصف، بينما تحدد السمة language رمز لغة مؤلفًا من حرفَين، كما هو موضّح في المثال التالي:

<Name>
  <Text text="Bed and Breakfast" language="en"/>
  <Text text="Lit et petit déjeuné" language="fr"/>
</Name>
<Occupancy> Optional integer الحدّ الأقصى لعدد الضيوف المخصَّص لهم "حزمة غرف". على سبيل المثال، قد يتّسع جناح كبير لما يصل إلى 6 نزلاء، ولكنّه مخصّص لما يصل إلى 4 نزلاء فقط.

يجب أن تكون هذه القيمة أقل من أو مساوية للعنصر <Capacity>، وهو عدد الأشخاص الذين يمكن أن تتسع لهم الغرفة.

ويجب أن تكون قيمة <Occupancy> عددًا صحيحًا موجبًا بين 1 و99، بشكل شامل.

وإذا حددت هذا العنصر في كل من <RoomBundle> و<PackageData>، تكون الأولوية للقيمة في <RoomBundle>.

ملاحظة:

وقد تكون السمة <Occupancy> مصحوبة بالسمة <OccupancyDetails> التي تحدّد نوع الضيوف (الأشخاص البالغون أو الأطفال). راجِع السمة <OccupancyDetails> للتعرّف على بنية العناصر الفرعية ووصفها.
<PackageID> Required string

المعرّف الفريد للحزمة يمكنك استخدام هذا المعرّف لمطابقة بيانات حِزمة الغرف مع وحدات <Result> في تعديلات الأسعار. لمزيد من المعلومات، راجِع البيانات الوصفية لحزمة الغرف.

(يمكنك أيضًا استخدام هذا المعرّف للإشارة إلى تعريف شائع لحزمة الغرف تم استخدامه في رسالة "معاملة" واحدة عند تحديد بيانات حزمة الغرف مضمّنًا).
<ParkingIncluded> Optional boolean ما إذا كانت حزمة الغرف تشمل موقف سيارات بدون أي رسوم، حيث تكون خدمة ركن السيارات خدمة مدفوعة في هذا الفندق. لا تحدّد قيمة لهذا العنصر لفندق يقدّم مواقف مجانية للسيارات.

القيمتان الصالحتان هما 0 (أو false) و1 (أو true). القيمة التلقائية هي false.
<PhotoURL> Optional Object (مثل <PhotoURL> في <RoomData>، ولكن للحزمة (مثل صور الوجبات).
<Refundable> Optional Object تتيح هذه السياسة إدراج السعر على أنّه قابل للاسترداد بالكامل أو عملية إلغاء مجانية. وفي حال عدم توفيرها، لا يتم عرض أي معلومات عن عملية ردّ الأموال. تؤدي سياسة ردّ الأموال على مستوى <PackageData> إلى إلغاء سياسة ردّ الأموال على مستوى <Result>. تؤدي سياسة ردّ الأموال على المستوى <Rates> إلى إلغاء سياسة ردّ الأموال على المستوى <PackageData>. ويمكن أيضًا إبراز الأسعار القابلة للاسترداد للمستخدمين، من خلال خيارات بديلة بدون تعديل مخطط رسالة المعاملات مباشرةً. يمكنك الاطّلاع على مزيد من المعلومات حول هذه الخيارات سياسة الأسعار القابلة لردّ الأموال.

يعرض المثال التالي العنصر <Refundable> مع ضبط كل سماته:

<Refundable available="1" refundable_until_days="7"
refundable_until_time="18:00:00"/>

ملاحظة: ننصح بإعداد جميع السمات. ويتم إنشاء رسالة تحذيرية بشأن حالة الخلاصة عندما لا يتم ضبط سمة واحدة أو أكثر.

في حال عدم ضبط أي سمات، لن يتم عرض السعر قابل للاسترداد. السمات هي:

  • available: (مطلوبة) يجب ضبطها على 1 أو true للإشارة إلى ما إذا كان السعر يسمح بردّ الأموال بالكامل، وإلا سيتم ضبطه على 0 أو false.
  • refundable_until_days: (مطلوبة إذا كانت قيمة available هي true) لتحديد عدد الأيام التي يمكن خلالها طلب استرداد الأموال بالكامل قبل تسجيل الوصول. يجب أن تكون قيمة refundable_until_days عددًا صحيحًا يتراوح بين 0 و330، بشكل شامل.
  • refundable_until_time: (يُنصح بهذا الخيار بشدة إذا كانت قيمة السمة available هي true) تحدّد آخر وقت من اليوم، بالتوقيت المحلي للفندق، الذي سيتم فيه قبول طلب استرداد الأموال بالكامل. يمكن دمج هذه السمة مع السمة refundable_until_days للإشارة، على سبيل المثال، إلى أنّ "عمليات ردّ الأموال متاحة حتى الساعة 4:00 بعد الظهر قبل يومَين من تسجيل الوصول". إذا لم يتم ضبط السمة refundable_until_time، سيتم ضبط القيمة التلقائية على منتصف الليل.

    تستخدم قيمة هذه السمة تنسيق الوقت.

عند تحديد السمات، يجب التنبّه لما يلي:

  • إذا لم يتم ضبط available أو refundable_until_days، لن يتم عرض السعر على أنّه قابل للاسترداد.
  • وإذا كانت قيمة السمة available هي 0 أو false، يتم تجاهل السمات الأخرى. ولا يمكن استرداد السعر حتى في حال ضبط إحدى السمتَين الأخريين أو كلتيهما.
<MembershipBenefits Included> Optional boolean يشمل السعر مزايا الحصول على تصنيف "النخبة" لمدة الإقامة. يتضمّن المَعلمات التالية:
  • ProgramName: اسم برنامج الدرجة الأولى
  • ProgramLevel: مستوى البرنامج على سبيل المثال: "خبير ذهبي"
  • NightlyValue (optional): قيمة المزايا في الليلة
<CarRentalIncluded> Optional boolean يشمل السعر خدمة تأجير السيارات مجانًا لمدة الإقامة.
<MilesIncluded>> Optional boolean يشمل السعر أميالاً في برنامج المسافر الدائم. وتشمل المَعلمات ما يلي:
  • NumberofMiles: عدد الأميال لكل برنامج رحلة
  • Provider: يتم توفير الأميال للمسافرين الدائمين.
<OnPropertyCredit> Optional boolean يشمل السعر الرصيد في الفندق (للمأكولات و/أو المنتجع الصحي والمنتجع الصحي، إلخ). المَعلمة:
  • Amount: قيمة الرصيد لكل برنامج رحلة، بالعملة المحلية
<AirportTransportationIncluded> Optional Object يشمل السعر خدمة نقل مجانية من وإلى مطار قريب. وتحدّد السمة direction الاختيارية اتجاه وسيلة النقل. تشمل القيم الصالحة ما يلي:
    from: يتم توفير خدمة النقل من المطار إلى الفندق. هذه هي القيمة التلقائية في حال عدم تحديد اتجاه. to: يتم توفير خدمة نقل إلى المطار من الفندق. round_trip: يتم توفير خدمة النقل من المطار وإليه.

أمثلة

حزمة من غرفة واحدة

ويوضّح المثال التالي "حزمة غرف" واحدة لشخصَين (شخص بالغ وطفل واحد) ويشمل وجبة الفطور:

<?xml version="1.0" encoding="UTF-8"?>
<Transaction timestamp="2017-07-18T16:20:00-04:00" id="42">
  <PropertyDataSet>
    <Property>1234</Property>
    <PackageData>
      <Occupancy>2</Occupancy>
      <OccupancyDetails>
        <NumAdults>1</NumAdults>
        <Children>
          <Child age="17"/>
        </Children>
      </OccupancyDetails>
      <PackageID>P54321</PackageID>
      <Name>
         <Text text="Breakfast Included" language="en"/>
         <Text text="Avec le petit déjeuner" language="fr"/>
      </Name>
      <Description>
        <Text text="Two certificates for continental
          breakfast will be provided." language="en"/>
        <Text text="Deux certificats pour le petit déjeuner
          continental seront fournis." language="fr"/>
      </Description>
      <BreakfastIncluded>1</BreakfastIncluded>
    </PackageData>
  </PropertyDataSet>
</Transaction>

البيانات الوصفية للغرفة والحزمة

يحدّد المثال التالي البيانات الوصفية للغرفة والحزمة:

<?xml version="1.0" encoding="UTF-8"?>
<Transaction timestamp="2017-07-18T16:20:00-04:00" id="42">
  <PropertyDataSet>
    <Property>180054</Property>
    <RoomData>
      <RoomID>060773</RoomID>
      <Name>
        <Text text="Single Bed Room" language="en"/>
        <Text text="Chambre single" language="fr"/>
      </Name>
      <Description>
        <Text text="Non-smoking" language="en"/>
        <Text text="Pas de fumiers" language="fr"/>
      </Description>
      <PhotoURL>
        <Caption>
          <Text text="Living area" language="en"/>
          <Text text="Le chambre" language="fr"/>
        </Caption>
        <URL>http://www.foo.com/static/bar/image1234.jpg</URL>
      </PhotoURL>
    </RoomData>
    <PackageData>
      <PackageID>P54321</PackageID>
      <Name>
        <Text text="Breakfast Included" language="en"/>
        <Text text="Avec le petit déjeuner" language="fr"/>
      </Name>
      <Description>
        <Text text="Includes a delightful array of jams and jellies." language="en"/>
        <Text text="Comprend une délicieuse gamme de confitures et gelées." language="fr"/>
      </Description>
      <BreakfastIncluded>1</BreakfastIncluded>
    </PackageData>
  </PropertyDataSet>
</Transaction>

مجموعات غرف متعددة

يحدّد المثال التالي البيانات الوصفية للغرفة والحزمة لحِزم غرف متعددة:

<?xml version="1.0" encoding="UTF-8"?>
<Transaction timestamp="2017-07-18T16:20:00-04:00" id="42">
  <!-- A transaction message with room types result. -->
  <PropertyDataSet>
    <Property>12345</Property>
    <RoomData>
      <RoomID>single</RoomID>
      <Name>
        <Text text="Single room" language="en"/>
        <Text text="Chambre simple" language="fr"/>
      </Name>
      <Description>
        <Text text="A single room" language="en"/>
        <Text text="Le chambre simple" language="fr"/>
      </Description>
      <PhotoURL>
        <Caption>
          <Text text="Living area" language="en"/>
          <Text text="Le chambre" language="fr"/>
        </Caption>
        <URL>http://www.foo.com/static/bar/image1234.jpg</URL>
      </PhotoURL>
      <PhotoURL>
        <URL>http://www.foo.com/static/bar/image1235.jpg</URL>
      </PhotoURL>
      <Capacity>2</Capacity>
    </RoomData>
    <RoomData>
      <RoomID>double</RoomID>
      <Name>
        <Text text="Double room" language="en"/>
        <Text text="Chambre double" language="fr"/>
      </Name>
      <Occupancy>1</Occupancy>
    </RoomData>
    <PackageData>
      <PackageID>refundbreakfast</PackageID>
      <Name>
        <Text text="Refundable Room with Breakfast" language="en"/>
        <Text text="Chambre remboursable avec le petit déjeuner" language="fr"/>
      </Name>
      <Description>
        <Text text="Continental Breakfast" language="en"/>
        <Text text="Petit déjeuner continental" language="fr"/>
      </Description>
      <ChargeCurrency>hotel</ChargeCurrency>
      <Refundable available="1" refundable_until_days="3"/>
      <BreakfastIncluded>1</BreakfastIncluded>
    </PackageData>
    <PackageData>
      <PackageID>prepaid</PackageID>
      <Name>
        <Text text="Nonrefundable" language="en"/>
        <Text text="Non remboursable" language="fr"/>
      </Name>
      <Description>
        <Text text="Blah blah blad" language="en"/>
        <Text text="Le blah blah blad" language="fr"/>
      </Description>
      <Occupancy>2</Occupancy>
      <ChargeCurrency>web</ChargeCurrency>
      <Refundable available="0"/>
    </PackageData>
  </PropertyDataSet>
</Transaction>


حزمة غرف مع أسعار

يحدّد المثال التالي البيانات الوصفية للغرف والحزمة لحزمة غرف تتضمّن ميزات السعر:

<Transaction timestamp="2010-04-24T20:44:56-04:00" id="TXNID">
  <PropertyDataSet>
    <Property>12345</Property>
    <RoomData>
     ...
    </RoomData>
<!-- definitions of PackageData types including rate features -->
    <PackageData>
      <PackageID>room_with_addl_benefits</PackageID>
      <Name>
        <Text text="Acme Hotels 2017 Promotion Package" language="en"/>
      </Name>
      <ChargeCurrency>hotel</ChargeCurrency>
      <BreakfastIncluded>1</BreakfastIncluded>
      <MembershipBenefitsIncluded>
        <ProgramName>
          <Text language="en" text="Marriott Rewards"/>
        </ProgramName>
        <ProgramLevel>
          <Text language="en" text="Platinum"/>
        </ProgramLevel>
      </MembershipBenefitsIncluded>
      <OnPropertyCredit>
        <Amount currency="USD">123.45</Amount>
      </OnPropertyCredit>
    </PackageData>
    <PackageData>
      <PackageID>room_with_miles</PackageID>
      <Name>
        <Text text="Room with Bundled Miles" language="en"/>
      </Name>
      <ChargeCurrency>hotel</ChargeCurrency>
      <MilesIncluded>
        <NumberOfMiles>1000</NumberOfMiles>
        <Provider>
          <Text language="en" text="United Airlines"/>
        </Provider>
      </MilesIncluded>
      <AirportTransportationIncluded direction="from"/>
    </PackageData>
  </PropertyDataSet>

<!-- The actual list of prices -->
  <Result>
…
  </Result>
</Transaction>

الوجبات والصور

يحدد المثال التالي البيانات الوصفية للغرفة والحزمة للوجبات والصور وأوقات الوصول والمغادرة:

<?xml version="1.0" encoding="UTF-8"?>
<Transaction timestamp="2017-07-18T16:20:00-04:00" id="42">
  <PropertyDataSet>
    <Property>1234</Property>
    <PackageData>
      <PackageID>PackageID_1</PackageID>
      <Name>
        <Text text="Meals Included" language="en"/>
      </Name>
      <PhotoURL>
        <Caption>
          <Text text="Breakfast" language="en"/>
          <Text text="朝食" language="ja"/>
        </Caption>
        <URL>http://example.com/static/bar/image1234.jpg</URL>
      </PhotoURL>
      <Meals>
        <!-- Guests can choose to have breakfast in their room or in another
        space to avoid contact with other guests. -->
        <Breakfast included="1" in_room="1" in_private_space="1"/>
        <Dinner included="1" buffet="1"/>
      </Meals>
      <CheckinTime>15:00</CheckinTime>
      <CheckoutTime>11:00</CheckoutTime>
    </PackageData>
  </PropertyDataSet>
</Transaction>

فطور

<?xml version="1.0" encoding="UTF-8"?>
<Transaction timestamp="2017-07-18T16:20:00-04:00" id="42">
  <PropertyDataSet>
    <Property>1234</Property>
    <PackageData>
      <PackageID>PackageID_1</PackageID>
      <Name>
        <Text text="Breakfast Included" language="en"/>
      </Name>
      <PhotoURL>
        <Caption>
          <Text text="Breakfast" language="en"/>
          <Text text="朝食" language="ja"/>
        </Caption>
        <URL>http://example.com/static/bar/image1234.jpg</URL>
      </PhotoURL>
      <Meals>
        <Breakfast included="true"/>
        <!-- Dinner not included needs to be explicitly specified -->
        <Dinner included="false"/>
      </Meals>
      <CheckinTime>15:00</CheckinTime>
      <CheckoutTime>11:00</CheckoutTime>
    </PackageData>
  </PropertyDataSet>
</Transaction>

<Result>

حاوية لتعديلات الأسعار ومدى التوفّر في رسالة <Transaction>

يظهر العنصر <Result> في المكان التالي ضمن التسلسل الهرمي بتنسيق XML لرسالة المعاملة:

+ <Transaction>
    + <PropertyDataSet>  // Room and package metadata
        + <Property>
        + <RoomData>
        + <PackageData>
    + <Result>           // Pricing and availability
        + <Rates>
        + <RoomBundle>
        + ...

يمكنك استخدام "<Result>" لضبط أسعار الغرف أو تعديلها وتحديد المستودع الإعلاني المتوفّر. تشير عادةً العناصر المحدّدة في هذا العنصر إلى بيانات وصفية مستقلة عن برنامج الرحلة حول غرفة أو باقة (مثل وصف أو مجموعة من وسائل الراحة) المحدّدة في <PackageData> و<RoomData>.

ترسل عادةً رسائل المعاملات مع تعديلات الأسعار بشكل متكرر. ويعتمد تحديد معدّل تكرار هذه العملية على وضع التسليم الذي تستخدمه.

يمكنك استخدام "<Result>" في رسالة "المعاملة" لإزالة برامج الرحلات، على النحو الموضّح في إزالة المستودع. للمزيد من المعلومات عن استخدام رسائل "المعاملات" لتعديل الأسعار ومدى التوفّر، يمكنك مراجعة إضافة المستودع وتعديله.

يمكن أن تتضمَّن رسالة "المعاملة" الواحدة أي عدد من عناصر <Result>، ما دام حجم الرسالة لا يتجاوز 100 ميغابايت.

البنية

يستخدم العنصر <Result> البنية التالية:

<?xml version="1.0" encoding="UTF-8"?>
<Transaction ... >
  <Result>
    <!-- Required -->
    <Property>hotel_ID</Property>
    <!-- Required -->
    <Checkin>YYYY-MM-DD</Checkin>
    <!-- Required -->
    <Nights>number_of_nights</Nights>

    <Baserate currency="currency_code">price</Baserate>
    <!-- Only required when <Baserate> contains a real price -->
    <Tax currency="currency_code">tax_amount</Tax>
    <!-- Only required when <Baserate> contains a real price  -->
    <OtherFees currency="currency_code">fee_amount</OtherFees>
    <Refundable available="[false|true]" refundable_until_days="number_of_days"
      refundable_until_time="time"/>

    <RoomID>room_ID</RoomID>
    <PackageID>package_ID</PackageID>
    <ExpirationTime>expiration_time</ExpirationTime>
    <ChargeCurrency>[deposit|hotel|installments|web]</ChargeCurrency>

    <Occupancy>max_number_of_intended_occupants</Occupancy>
    <!-- For Baserate, occupancy value must be greater than or equal to 2.
         If a value is not provided for occupancy, it defaults to 2. -->
    <OccupancyDetails>occupancy_info</OccupancyDetails>

    <Rates>...</Rates>

    <RoomBundle>...</RoomBundle>

    <AllowablePointsOfSale>
      <PointOfSale id="landing_page_identifier"/>
      ...
    </AllowablePointsOfSale>

    <Custom[1-5]>custom_value</Custom[1-5]>
  </Result>
  ...
  </Transaction>

السمات

يحتوي العنصر <Result> على السمات التالية:

السمة مطلوب؟ النوع الوصف
mergeable Optional boolean بشكل تلقائي، سيتم استبدال أي أسعار سابقة (غير منتهية الصلاحية) متوفّرة في ذاكرة التخزين المؤقت لدى Google بالأسعار الجديدة لفندق وبرنامج رحلة محدّدَين. تتيح لك السمة القابلة للدمج تخزين المزيد من الأسعار في ذاكرة التخزين المؤقت لدى Google بدون حذف معلومات الأسعار السابقة. سيتم دائمًا ضبط هذه السمة على true (بصرف النظر عن ردّك على رسالة المعاملة) لطلب البحث عن الأسعار المباشرة مع الردود السياقية.

العناصر الفرعية

يحتوي العنصر <Result> على العناصر الثانوية التالية:

العنصر الفرعي مطلوب؟ النوع الوصف
<AllowablePointsOfSale> Optional Object صفحة مقصودة واحدة أو أكثر مؤهّلة للفندق. الصفحة المقصودة هي موقع إلكتروني يمكنه معالجة عملية الحجز للمستخدم النهائي. لتضمين صفحة مقصودة معيّنة بشكل صريح (واستبعاد صفحات أخرى)، أضِف عنصر <AllowablePointsOfSale> واحدًا أو أكثر يتطابق مع سمة id للسمة <PointOfSale> في ملف الصفحات المقصودة.

في حال عدم تضمين هذا العنصر، تُعتبر جميع الصفحات المقصودة المحدّدة في ملف الصفحات المقصودة مؤهّلة للاستخدام في حجز الغرفة. للحصول على مزيد من المعلومات، يمكنك الاطّلاع على بنية ملف الصفحات المقصودة.
<Baserate> Optional float

تمثّل هذه السمة سعر الغرفة لمدة الإقامة. يجب أن تعكس قيمة هذا العنصر ما يلي:

  • في حال اختيار غرفة خاصة، يجب تحديد معدّل الإقامة المزدوجة الأقل تكلفة الذي تقدّمه.
  • بالنسبة إلى الغرف المشتركة، اترك الحقل فارغًا واستخدِم <RoomBundle>.
  • إجمالي مدة الإقامة، وليس متوسّط سعر الليلة

إذا كانت الغرفة غير متوفّرة لبرنامج الرحلة، يجب حذف السمة <Baserate> أو ضبطها على -1، ويجب تحديد السمة <Unavailable>، بالإضافة إلى أي أسباب معروفة لعدم توفّرها.

لإزالة حزمة غرف، اتّبِع التعليمات الواردة في المقالة إزالة مجموعة غرف.

يجب ألا تحتوي السمة <Baserate> على أي رموز لتجميع الأرقام، مثل الفاصلة (,) أو النقطة (.). وعليك دائمًا فصل الكسور باستخدام النقطة (.) كعلامة عشرية. على سبيل المثال، يمكنك تمثيل 1,200.40 دولار أمريكي على النحو التالي:

<Baserate currency="USD">1200.40</Baserate>

يتضمّن العنصر <Baserate> السمات الاختيارية التالية:

  • all_inclusive: قيمة منطقية تشير إلى ما إذا كان هذا المعدّل يشمل الضرائب والرسوم. وبشكل عام، اضبط هذه القيمة على false للمستخدمين النهائيين في الولايات المتحدة وكندا، فضلاً عن قيم توفّر العنصرَين <Tax> و<OtherFees>. إذا كنت تستخدم الأسعار الشاملة الخدمات، قد لا تكون مؤهّلاً للظهور في بيانات المنتجات إذا لم تفصل الأسعار بين الضرائب والرسوم للمستخدمين في الولايات المتحدة وكندا.

    بالنسبة إلى جميع المستخدمين النهائيين الآخرين، عليك عادةً تضمين الضرائب والرسوم في السعر الأساسي وضبط قيمة السمة all_inclusive على true. لمزيد من المعلومات، يُرجى الاطّلاع على سياسة الضرائب والرسوم.

    تكون القيمة التلقائية false.

  • currency: رمز العملة المكوَّن من ثلاثة أحرف. على سبيل المثال، USD للدولار الأمريكي.
<ChargeCurrency> Optional enum متى وأين يدفع المستخدم مقابل الحجز. ويمكن استخدام هذا العنصر في رسالة "المعاملة" في العنصر <Result> لسعر الفندق أو الجزء <PackageData> من حزمة غرف.

القيم الصالحة هي:

  • web: يتم تحصيل الرسوم من المستخدم على الإنترنت في وقت الحجز. هذه هي القيمة الافتراضية. يتم تحديد الصفحة المقصودة الفعلية من خلال ملف الصفحة المقصودة، ويمكن أن تتأثر بعملة المستخدم أو موقعه الجغرافي أو لغته أو عوامل أخرى.
  • hotel: يتم تحصيل الرسوم من المستخدم عند تسجيل الوصول في الفندق. إذا كان يجب دائمًا تسديد الدفعات بعملة الفندق، اضبط القيمة <ChargeCurrency> على hotel. ولا تتأثر الصفحة المقصودة الفعلية بعملة المستخدم.
  • deposit: يتم تحصيل جزء من المبلغ من المستخدم على الفور ويتم تحصيل المبلغ المتبقي في وقت لاحق، عادةً عندما يغادر المستخدم الفندق.
  • installments: يتم تحصيل كسر أوّلي من المبلغ الإجمالي المستحق للمستخدم، ومن المتوقّع أن يدفع بشكل روتيني رصيدًا محددًا خلال فترة زمنية ثابتة.

تكون القيمة التلقائية web.
<Checkin> Required Date تاريخ تسجيل الوصول لبرنامج رحلة باستخدام تنسيق التاريخ. بالجمع بين العنصر <Nights> والعنصر <Checkin>، يشكّلون برنامج رحلة.
<Custom[1‑5]> Optional string تحدد حقلاً مخصّصًا يمكنك استخدامه لتمرير بيانات إضافية مرتبطة بأحد الفنادق. ويمكنك ضبط ما يصل إلى خمس قيم مخصّصة مع أسماء العناصر التالية:
  • <Custom1>
  • <Custom2>
  • <Custom3>
  • <Custom4>
  • <Custom5>

تتيح لك عناصر <Custom> تمرير بيانات عشوائية. على سبيل المثال، يمكنك تحديد قيمة في هذا الحقل سيتمّ استخدامها لاحقًا بواسطة ملف الصفحات المقصودة لإنشاء عنوان URL مخصّص لصفحة مقصودة. هناك حدّ أقصى يبلغ 200 حرف لكلّ حقل مخصّص. للحصول على مزيد من المعلومات، يمكنك مراجعة ملفات الصفحة المقصودة .

لا يتم توريث عناصر <Custom> الواردة في العنصر <Rate> إلى العنصر <RoomBundle>. ويجب تحديد السمة <Custom> بشكل منفصل في كل سمة <RoomBundle>.

<ExpirationTime> Optional DateTime تشير هذه السمة إلى التاريخ والوقت اللذين يُعتبر فيهما السعر منتهي الصلاحية (3 ساعات على الأقل).

ننصحك بعدم توفير طوابع زمنية لانتهاء الصلاحية إذا لم تكن هذه الطوابع الزمنية مهمّة للأسعار.

لا تقدّم Google أي أسعار انتهت صلاحيتها، وسيصبح أي برنامج رحلة انتهت صلاحية سعره مؤهَّلاً لتلقّي طلبات البحث عن الأسعار في الوقت الفعلي.
<Nights> Required integer عدد الليالي لبرنامج الرحلة. ويجب أن تكون قيمة العنصر <Nights> عددًا صحيحًا موجبًا. أمّا الجمع بين <Nights> و<Checkin>، فيشكّل برنامج رحلة.
<OtherFees> Optional float الرسوم الأخرى غير السعر الأساسي والضرائب التي تؤثر في السعر النهائي للغرفة. يتضمّن العنصر <OtherFees> سمة واحدة مطلوبة، وهي currency، تحدّد رمز العملة المكوَّن من ثلاثة أحرف للرسوم. مثلاً: USD

يجب إدخال العنصر <OtherFees> إذا كان <Baserate> أكبر من صفر.
<Occupancy> Optional integer تحدّد هذه السمة الحد الأقصى لعدد النزلاء. عندما تظهر السمة <Occupancy> ضمن <Result>، يجب أن تحدّد السمة 2 أو أكثر. وقد تكون السمة <Occupancy> مصحوبة بسمة <OccupancyDetails> التي تحدّد نوع الضيوف (الأشخاص البالغون أو الأطفال). يمكنك الرجوع إلى <OccupancyDetails> للتعرّف على بنية العناصر الفرعية ووصفها. إذا لم يتم توفير العنصر <Occupancy>، سيتم ضبط مستوى الإشغال تلقائيًا على 2.

ملاحظة: يمكنك التواصل مع فريق الدعم لتفعيل الميزة لإرسال أسعار الإقامة غير المزدوجة.
<PackageID> Optional string المعرّف الفريد للحزمة لربطها ببيانات الحزمة المحدَّدة مسبقًا تُستخدَم أيضًا لتعبئة متغيّر الصفحة المقصودة PACKAGE-ID. لمزيد من المعلومات، راجِع البيانات الوصفية لحزمة الغرف.
<Property> Required string رقم تعريف الفندق المتأثر بالبيانات المرتبطة به (السعر أو برنامج الرحلة أو حزمة الغرف أو البيانات الوصفية). يجب أن تكون قيمة هذا العنصر سلسلة. يجب أن تتطابق قيمة هذا العنصر مع بطاقة بيانات <id> التي حدّدتها في "خلاصة قائمة الفنادق".
<Rates> Optional <Rates> حاوية لحزمة <Rate> واحدة أو أكثر وتحدّد كل <Rate> في <Rates> سعرًا مختلفًا لمجموعة الغرفة/برنامج الرحلة.

لا تستخدم العنصر <Rates> إلا عند توفّر أسعار متعددة لمجموعة البرامج/الغرفة نفسها. على سبيل المثال، يمكنك تحديد أسعار متعددة للأسعار المشروطة أو الأسعار الخاصة أو الأسعار المشروطة في حِزم الغرف.

<Refundable> Optional Object تتيح هذه السياسة إدراج السعر على أنّه قابل للاسترداد بالكامل أو عملية إلغاء مجانية. وفي حال عدم توفيرها، لا يتم عرض أي معلومات عن عملية ردّ الأموال. تؤدي سياسة ردّ الأموال على مستوى <PackageData> إلى إلغاء سياسة ردّ الأموال على مستوى <Result>. تؤدي سياسة ردّ الأموال على المستوى <Rates> إلى إلغاء سياسة ردّ الأموال على المستوى <PackageData>. ويمكن أيضًا إبراز الأسعار القابلة للاسترداد للمستخدمين، من خلال خيارات بديلة بدون تعديل مخطط رسالة المعاملات مباشرةً. يمكنك الاطّلاع على مزيد من المعلومات حول سياسة الأسعار القابلة لردّ الأموال.

يعرض المثال التالي العنصر <Refundable> مع ضبط كل سماته:

<Refundable available="1" refundable_until_days="7"
refundable_until_time="18:00:00"/>

ملاحظة: ننصح بإعداد جميع السمات. ويتم إنشاء رسالة تحذيرية بشأن حالة الخلاصة عندما لا يتم ضبط سمة واحدة أو أكثر.

في حال عدم ضبط أي سمات، لن يتم عرض السعر قابل للاسترداد. السمات هي:

  • available: (مطلوبة) يجب ضبطها على 1 (أو true) للإشارة إلى ما إذا كان السعر يسمح بردّ الأموال بالكامل، أو يتم ضبطها على 0 (أو false).
  • refundable_until_days: (مطلوبة إذا كانت قيمة available هي true) لتحديد عدد الأيام التي يمكن خلالها طلب استرداد الأموال بالكامل قبل تسجيل الوصول. يجب أن تكون قيمة refundable_until_days عددًا صحيحًا يتراوح بين 0 و330، بشكل شامل.
  • refundable_until_time: (يُنصح بهذا الخيار بشدة إذا كانت قيمة السمة available هي true) تحدّد آخر وقت من اليوم، بالتوقيت المحلي للفندق، الذي سيتم فيه قبول طلب استرداد الأموال بالكامل. يمكن دمج هذه السمة مع السمة refundable_until_days للإشارة، على سبيل المثال، إلى أنّ "عمليات ردّ الأموال متاحة حتى الساعة 4:00 بعد الظهر قبل يومَين من تسجيل الوصول". إذا لم يتم ضبط السمة refundable_until_time، سيتم ضبط القيمة التلقائية على منتصف الليل.

    تستخدم قيمة هذه السمة تنسيق الوقت.

عند تحديد السمات، يجب التنبّه لما يلي:

  • إذا لم يتم ضبط available أو refundable_until_days، لن يتم عرض السعر على أنّه قابل للاسترداد.
  • وإذا كانت قيمة السمة available هي 0 (أو false)، يتم تجاهل السمات الأخرى. ولا يمكن استرداد السعر حتى في حال ضبط إحدى السمتَين الأخريين أو كلتيهما.
<RoomBundle> Optional <RoomBundle> حاوية تتضمّن معلومات عن الأوصاف المادية للغرفة وأي حزمة لوسائل الراحة وبعض تفاصيل سياسة الشراء للفندق وبرنامج الرحلة المحدّدَين.

بوجهٍ عام، يمكنك استخدام هذا العنصر لتحديد سعر الغرفة الأساسية وأنواع مختلفة من الغرف في الموقع نفسه. على الرغم من إمكانية تحديد أوصاف حزمة الغرف المضمّنة، عليك استخدام رسالة "معاملة" منفصلة لتحديد هذه المعلومات. سيخزّن Google البيانات الوصفية لتتمكّن من الرجوع إليها بدلاً من تكرارها في جميع تعديلات الأسعار المستقبلية.
<RoomID> Optional string رقم التعريف الفريد للغرفة لربطها ببيانات الغرفة المحدّدة مسبقًا. وتُستخدم أيضًا لتعبئة متغيّر الصفحة المقصودة PARTNER-ROOM-ID. لمزيد من المعلومات، راجِع البيانات الوصفية لحزمة الغرف.
<Tax> Optional float الضرائب التي يتم احتسابها للسعر النهائي للغرفة. يتضمّن العنصر <Tax> سمة واحدة مطلوبة، وهي currency، تحدّد رمز العملة المكوّن من ثلاثة أحرف للضرائب. مثلاً: USD ويجب إضافة العنصر <Tax> إذا كان <Baserate> أكبر من صفر.
<Unavailable> Optional Object تشير هذه السمة إلى أنّ برنامج الرحلة غير متوفّر للحجز. يعمل كحاوية لأسباب أكثر تفصيلاً لعدم توفّر برنامج الرحلة. قد يتم دمج سبب أو أكثر من أسباب عدم التوفّر التالية ضمن العلامة <Unavailable>:
  • <NoVacancy/>: لا تتوفّر غرف أخرى للبيع لمدة ليلة واحدة أو أكثر من الإقامة.
  • <MinNightStay value=N/>: كان برنامج الرحلة أقل من الحد الأدنى للإقامة في الليلة والذي يبلغ N خلال تواريخ الإقامة.
  • <MaxNightStay value=N/>: كان برنامج الرحلة أعلى من الحد الأقصى للإقامة في الليلة والذي يبلغ N لتواريخ الإقامة.
  • <MinAdvancePurchase value=N/>: كان برنامج الرحلة أقل من الحد الأدنى لفترة الحجز المُسبق التي تبلغ N لتواريخ الإقامة.
  • <MaxAdvancePurchase value=N/>: كان برنامج الرحلة أعلى من الحد الأقصى لفترة الحجز المُسبق التي تبلغ N لتواريخ الإقامة.
  • <ClosedToArrival/>: لا يسمح الفندق بتسجيل الوصول في تاريخ وصول برنامج الرحلة.
  • <ClosedToDeparture/>: لا يسمح الفندق بتسجيل المغادرة في تاريخ مغادرة برنامج الرحلة.
  • <PropertyClosed first_open="YYYY-MM-DD" first_closed="YYYY-MM-DD"/>: الفندق مغلق طوال فترة الإقامة أو جميعها. تحدّد السمتان المقترَحتان first_open وfirst_closed التاريخ الأول الذي يكون أكبر من أو يساوي تاريخ الوصول الذي سيكون فيه الموقع مفتوحًا أو مغلقًا، على التوالي. بالنسبة إلى الموقع الإلكتروني الذي يُغلق بعد تاريخ الوصول، يجب أن يكون first_open مساويًا لتاريخ الوصول، في حين يجب أن يمثّل first_closed التاريخ الذي يُغلق فيه الموقع. بالنسبة إلى الموقع الإلكتروني الذي يتم إغلاقه في تاريخ الوصول، يجب أن يكون الرمز first_closed مساويًا لتاريخ الوصول، بينما يجب أن يكون first_opened هو التاريخ التالي الذي يفتح فيه الموقع.
  • <NotFetched/>: لم يتم توفير سعر برنامج الرحلة من خلال مصادر بيانات عملية بيع البرنامج.
  • <InvalidProperty/>: لم يتم التعرّف على معرّف الموقع المطلوب.
  • <InvalidOccupancy/>: عدد النزلاء المطلوب غير متاح في الفندق.
  • <PriceIssue/>: حدثت مشكلة في السعر تسبّبت في عدم إرساله.
  • <InternalError reason=""/>: حدث خطأ غير معروف. يمكن لسمة السبب الاختيارية الإبلاغ عن الخطأ كنص.
  • <OtherRestriction restriction=""/>: لم يكن برنامج الرحلة متاحًا بسبب بعض القيود غير العددية على الحجز. تتيح سمة التقييد الاختيارية الإبلاغ عن القيود على شكل نص.

أمثلة

مثال على مواقع متعدّدة

يحدّد المثال التالي برنامج رحلة واحدًا وأسعاره لموقعَين:

<?xml version="1.0" encoding="UTF-8"?>
<Transaction timestamp="2017-07-23T16:20:00-04:00" id="42">
  <Result>
    <Property>060773</Property>
    <RoomID>RoomType101</RoomID>
    <PackageID>Package101</PackageID>
    <Checkin>2018-06-10</Checkin>
    <Nights>2</Nights>
    <Baserate currency="USD">278.33</Baserate>
    <Tax currency="USD">25.12</Tax>
    <OtherFees currency="USD">2.00</OtherFees>
    <AllowablePointsOfSale>
      <PointOfSale id="site1"/>
    </AllowablePointsOfSale>
  </Result>
  <Result>
    <Property>052213</Property>
    <RoomID>RoomType101</RoomID>
    <PackageID>Package101</PackageID>
    <Checkin>2018-06-10</Checkin>
    <Nights>2</Nights>
    <Baserate currency="USD">299.98</Baserate>
    <Tax currency="USD">26.42</Tax>
    <OtherFees currency="USD">2.00</OtherFees>
    <AllowablePointsOfSale>
      <PointOfSale id="otto"/>
      <PointOfSale id="simon"/>
    </AllowablePointsOfSale>
  </Result>
</Transaction>

لا تظهر في هذا المثال تفاصيل عن الغرفة، مثل الوصف والصورة والشرح واسم الغرفة وسعة الغرفة.

يمكنك تحديد هذه المعلومات مرة واحدة في رسالة معاملة منفصلة تخزّنها Google. يمكنك بعد ذلك الإشارة إليها في جميع التعديلات اللاحقة على الأسعار والمستودع. لمزيد من المعلومات، يمكنك الاطّلاع على البيانات الوصفية لحزمة الغرف.

مثال على الأسعار المتعدّدة

يحدّد المثال التالي برنامج رحلة واحدًا وموقعًا بأسعار متعدّدة لإشغالات مختلفة. يمكن استخدام العنصر <Rates> لتوفير أسعار متعددة خاصة بموقع معيّن. يُعد المثال التالي مفيدًا أيضًا لمواقع إيجار الإجازات (VR):

<?xml version="1.0" encoding="UTF-8"?>
<Transaction timestamp="2020-07-23T16:20:00-04:00" id="42">
  <Result>
    <Property>1234</Property>
    <Checkin>2021-01-13</Checkin>
    <Nights>9</Nights>
    <Baserate currency="USD">3196.1</Baserate>
    <Tax currency="USD">559.49</Tax>
    <OtherFees currency="USD">543.34</OtherFees>
    <Occupancy>2</Occupancy>
    <Rates>
      <Rate>
        <Baserate currency="USD">3196.1</Baserate>
        <Tax currency="USD">559.49</Tax>
        <OtherFees currency="USD">543.34</OtherFees>
        <Occupancy>1</Occupancy>
      </Rate>
      <Rate>
        <Baserate currency="USD">3196.1</Baserate>
        <Tax currency="USD">559.49</Tax>
        <OtherFees currency="USD">543.34</OtherFees>
        <Occupancy>3</Occupancy>
      </Rate>
      <Rate>
        <Baserate currency="USD">3196.1</Baserate>
        <Tax currency="USD">559.49</Tax>
        <OtherFees currency="USD">543.34</OtherFees>
        <Occupancy>4</Occupancy>
      </Rate>
      <Rate>
        <Baserate currency="USD">3196.1</Baserate>
        <Tax currency="USD">559.49</Tax>
        <OtherFees currency="USD">543.34</OtherFees>
        <Occupancy>5</Occupancy>
      </Rate>
      <Rate>
        <Baserate currency="USD">3196.1</Baserate>
        <Tax currency="USD">559.49</Tax>
        <OtherFees currency="USD">543.34</OtherFees>
        <Occupancy>6</Occupancy>
      </Rate>
    </Rates>
  </Result>
</Transaction>

مثال غير متوفر

يحدّد المثال التالي برنامج رحلة يتعذّر استرداد مدى توفّره من قنوات تنزيل البيانات، وآخر بسعر أقل من الحد الأدنى للإقامة في الليل، وقد تم حجزه مسبقًا في التواريخ المحدّدة، وآخر برنامج يكون قد تم إغلاقه في تاريخ الوصول ولكن يفتح خلال فترة الإقامة:

<?xml version="1.0" encoding="UTF-8"?>
<Transaction timestamp="2017-07-23T16:20:00-04:00" id="42">
  <Result>
    <Property>060773</Property>
    <Checkin>2018-06-10</Checkin>
    <Nights>2</Nights>
    <Unavailable>
      <NotFetched/>
    </Unavailable>
  </Result>
  <Result>
    <Property>073313</Property>
    <Checkin>2018-06-10</Checkin>
    <Nights>2</Nights>
    <Unavailable>
      <NoVacancy/>
      <MinNightStay value=3/>
    </Unavailable>
  </Result>
  <Result>
    <Property>052213</Property>
    <Checkin>2018-06-10</Checkin>
    <Nights>10</Nights>
    <Unavailable>
      <PropertyClosed first_open="2018-06-15" first_closed="2018-06-10"/>
    </Unavailable>
  </Result>
</Transaction>

<Rates>

حاوية لحزمة <Rate> واحدة أو أكثر وتحدّد كل سمة <Rate> في <Rates> سعرًا مختلفًا لمجموعة الغرف أو برنامج الرحلة.

استخدِم العنصر <Rates> فقط عند توفّر أسعار متعددة لمجموعة الغرف أو برنامج الرحلة نفسها. على سبيل المثال، يمكنك تحديد أسعار متعددة للأسعار المشروطة أو الأسعار الخاصة أو الأسعار المشروطة في حِزم الغرف.

يظهر العنصر <Rates> في المكان التالي ضمن التسلسل الهرمي بتنسيق XML لرسالة المعاملة:

+ <Transaction>
    + <PropertyDataSet>  // Room and package metadata
        + <Property>
        + <RoomData>
        + <PackageData>
    + <Result>         // Pricing and availability
        + <Rates>
        + <RoomBundle> (Can also contain <Rates>)
        + ...

تلغي القيم التي تم ضبطها في <Rate> القيم المرتبطة بالتسعير على العنصر الرئيسي <Result> أو <RoomBundle>. وإذا لم يتم ضبطها في <Rate>، ستكتسب قيمتها من العنصر الرئيسي. يتم اكتساب <AllowablePointsofSale> فقط للعنصر <RoomBundle>.

البنية

يستخدم العنصر <Rates> البنية التالية:

<?xml version="1.0" encoding="UTF-8"?>
<Transaction ... >
  <Result>
    <Rates>
      <Rate rate_rule_id="rate_rule_id">
        <Baserate currency="currency_code">price</Baserate>
        <Tax currency="currency_code">tax_amount</Tax>
        <OtherFees currency="currency_code">fee_amount</OtherFees>
        <ExpirationTime>expiration_time</ExpirationTime>
        <Refundable available="[false|true]" refundable_until_days="number_of_days"
        refundable_until_time="time"/>
        <ChargeCurrency>[deposit|hotel|installments|web]</ChargeCurrency>
        <AllowablePointsOfSale>
          <PointOfSale id="landing_page_identifier"/>
        </AllowablePointsOfSale>
        <Occupancy>max_number_of_intended_occupants</Occupancy>
        <OccupancyDetails> <!-- optional info about the types of guests,
      whether adults or children --></OccupancyDetails>
          ...
        <Custom[1-5]>custom_value</Custom[1-5]>
      </Rate>
      ...
    </Rates>
  </Result>
  ...
</Transaction>

السمات

يحتوي العنصر <Rates> على السمات التالية:

السمة مطلوب؟ الوصف
rate_rule_id Optional بالنسبة إلى الأسعار المشروطة، يتطابق رقم التعريف هذا مع سعر مع تعريف في ملف تعريف قاعدة السعر. عدد الأحرف المسموح به لهذا الحقل هو 40 حرفًا.

العناصر الفرعية

يحتوي العنصر <Rates> على العناصر الثانوية التالية:

العنصر الفرعي مطلوب؟ النوع الوصف
<AllowablePointsOfSale> Optional Object صفحة مقصودة واحدة أو أكثر مؤهّلة للفندق. يستخدم هذا العنصر البنية نفسها المستخدَمة في <AllowablePointsOfSale> على <Result>.
<Baserate> Required float تمثّل هذه السمة سعر الغرفة لمدة الإقامة. يستخدم هذا العنصر البنية نفسها المستخدَمة في <Baserate> على <Result>.

ملاحظة: لا يمكن تحديد العنصر الفرعي <Baserate> ضمن <Rate> على أنّه غير متوفّر.
<ChargeCurrency> Optional enum متى وأين يدفع المستخدم مقابل الحجز. يستخدم هذا العنصر البنية نفسها المستخدَمة في <ChargeCurrency> في <Result>.
<Custom[1‑5]> Optional string حقول مخصّصة يمكنك استخدامها لنقل البيانات الإضافية المرتبطة بفندق إلى صفحة مقصودة. يستخدم هذا العنصر البنية نفسها المستخدَمة في <Custom[1‑5]> في <Result>. الحدّ الأقصى المسموح به لعدد الأحرف هو 200 حرف لكل حقل مخصّص. لمزيد من المعلومات، يمكنك الاطّلاع على ملفات الصفحات المقصودة.

في حال توفير عناصر <Custom> في العنصر <Result>، لن يتم اكتسابها في العنصر <RoomBundle> ويجب تحديدها بشكل منفصل لكل <RoomBundle>، أو يمكن تضمينها في <PackageData> إذا لزم الأمر.
<ExpirationTime> Optional DateTime التاريخ والوقت اللذين يتم فيهما اعتبار السعر منتهي الصلاحية. يستخدم هذا العنصر البنية نفسها المستخدَمة للسمة <ExpirationTime> في <Result>.
<Occupancy> Optional integer

تحدّد هذه السمة الحد الأقصى لعدد النزلاء. وقد تكون سمة <Occupancy> مصحوبةً بالسمة <OccupancyDetails> التي تحدّد نوع الضيوف (الأشخاص البالغون أو الأطفال). يمكنك الرجوع إلى <OccupancyDetails> للتعرّف على بنية العناصر الفرعية ووصفها.
<OtherFees> Required float الرسوم الأخرى غير السعر الأساسي والضرائب التي تؤثر في السعر النهائي للغرفة. يستخدم هذا العنصر البنية نفسها المستخدَمة في <OtherFees> في <Result>.
<Refundable> Optional Object تتيح هذه السياسة إدراج السعر على أنّه قابل للاسترداد بالكامل أو عملية إلغاء مجانية. وفي حال عدم توفيرها، لا يتم عرض أي معلومات عن عملية ردّ الأموال. تؤدي سياسة ردّ الأموال على مستوى <PackageData> إلى إلغاء سياسة ردّ الأموال على المستوى <Result>. تؤدي سياسة ردّ الأموال على المستوى <Rates> إلى إلغاء سياسة ردّ الأموال على المستوى <PackageData>. ويمكن أيضًا إبراز الأسعار القابلة للاسترداد للمستخدمين، من خلال خيارات بديلة بدون تعديل مخطط رسالة المعاملات مباشرةً. يمكنك الاطّلاع على مزيد من المعلومات حول هذه الخيارات سياسة الأسعار القابلة لردّ الأموال.

يعرض المثال التالي العنصر <Refundable> مع ضبط كل سماته:

<Refundable available="1" refundable_until_days="7"
refundable_until_time="18:00:00"/>

ملاحظة: ننصح بإعداد جميع السمات. ويتم إنشاء رسالة تحذيرية بشأن حالة الخلاصة عندما لا يتم ضبط سمة واحدة أو أكثر.

في حال عدم ضبط أي سمات، لن يتم عرض السعر قابل للاسترداد. السمات هي:

  • available: (مطلوبة) يجب ضبطها على 1 (أو true) للإشارة إلى ما إذا كان السعر يسمح بردّ الأموال بالكامل، أو يتم ضبطها على 0 (أو false).
  • refundable_until_days: (مطلوبة إذا كانت قيمة available هي true) لتحديد عدد الأيام التي يمكن خلالها طلب استرداد الأموال بالكامل قبل تسجيل الوصول. يجب أن تكون قيمة refundable_until_days عددًا صحيحًا يتراوح بين 0 و330، بشكل شامل.
  • refundable_until_time: (يُنصح بهذا الخيار بشدة إذا كانت قيمة السمة available هي true) تحدّد آخر وقت من اليوم، بالتوقيت المحلي للفندق، الذي سيتم فيه قبول طلب استرداد الأموال بالكامل. يمكن دمج هذه السمة مع السمة refundable_until_days للإشارة، على سبيل المثال، إلى أنّ "عمليات ردّ الأموال متاحة حتى الساعة 4:00 بعد الظهر قبل يومَين من تسجيل الوصول". إذا لم يتم ضبط السمة refundable_until_time، سيتم ضبط القيمة التلقائية على منتصف الليل.

    تستخدم قيمة هذه السمة تنسيق الوقت.

عند تحديد السمات، يجب التنبّه لما يلي:

  • إذا لم يتم ضبط available أو refundable_until_days، لن يتم عرض السعر على أنّه قابل للاسترداد.
  • وإذا كانت قيمة السمة available هي 0 (أو false)، يتم تجاهل السمات الأخرى. ولا يمكن استرداد السعر حتى في حال ضبط إحدى السمتَين الأخريين أو كلتيهما.
<Tax> Required float الضرائب التي يتم احتسابها للسعر النهائي للغرفة. يستخدم هذا العنصر البنية نفسها المستخدَمة في <Tax> في <Result>.

أمثلة

السعر الأساسي والسعر المشروط

يوضح المثال التالي رسالة "معاملة" تتضمن سعرًا أساسيًا وسعرًا مشروطًا:

<?xml version="1.0" encoding="UTF-8" ?>
<Transaction timestamp="2023-05-18T16:20:00-04:00" id="42">
  <Result>
    <Property>1234</Property>
    <Checkin>2023-04-10</Checkin>
    <Nights>1</Nights>

    <Baserate currency="USD">200.00</Baserate>
    <Tax currency="USD">20.00</Tax>
    <OtherFees currency="USD">1.00</OtherFees>

    <Rates>
      <!-- The rate_rule_id is required when using conditional rates -->
      <Rate rate_rule_id="mobile">
        <!-- Override base rate and taxes for conditional rates -->
        <Baserate currency="USD">180.00</Baserate>
        <Tax currency="USD">18.00</Tax>
        <!-- NOTE: OtherFees is inherited from the above setting -->
        <Custom1>ratecode123</Custom1>
      </Rate>
    </Rates>

  </Result>
</Transaction>

أسعار مشروطة متعددة

يحدّد المثال التالي سعرًا أساسيًا وأسعارًا مشروطة متعدّدة ضمن <RoomBundle>:

<?xml version="1.0" encoding="UTF-8" ?>
<Transaction timestamp="2023-05-18T16:20:00-04:00" id="42">
  <Result>
    <Property>1234</Property>
    <Checkin>2023-04-10</Checkin>
    <Nights>2</Nights>
    <!-- When Google receives new room bundle information for an itinerary, all
    previous room bundle pricing is dropped from Google's cache. Thus, if you
    want to delete a specific room bundle from Google's cache, you may do so
    by simply not providing that specific room bundle in subsequent transaction
    messages. -->
    <RoomBundle>
     ...
      <!-- RoomID is required, PackageID is recommended. -->
      <RoomID>5</RoomID>
      <PackageID>ABC</PackageID>
      <!-- Baserate is required. -->
      <Baserate currency="USD">275.00</Baserate>
      <Tax currency="USD">27.50</Tax>
      <OtherFees currency="USD">2.00</OtherFees>

      <!-- RatePlanID is optional and represents the unique identifier for a
      room and package data combination. We strongly recommend using RatePlanID
      as a variable to build your dynamic landing page (formerly Point of Sale)
      URL. For details, see Using Variables and Conditions. -->
      <RatePlanID>5-ABC</RatePlanID>

      <!-- Occupancy is mandatory for RoomBundle elements. -->
      <!-- Elements below will get inherited to nested rate elements. -->
      <Occupancy>2</Occupancy>
      <OccupancyDetails>
        <NumAdults>2</NumAdults>
      </OccupancyDetails>
      <InternetIncluded>1</InternetIncluded>


      <!-- Rate rule "mobile" overrides chargeCurrency, "us_or_gb" doesn't. -->
      <ChargeCurrency>web</ChargeCurrency>
      <Custom1>ratebasic</Custom1>
      <!-- Neither rate overrides Custom2. -->
      <Custom2>ratebasic</Custom2>

      <Rates>
        <Rate rate_rule_id="mobile">
          <Baserate currency="USD">258.33</Baserate>
          <Tax currency="USD">25.83</Tax>
          <OtherFees currency="USD">1.00</OtherFees>
          <!-- The value below overrides ChargeCurrency from roombundle. -->
          <ChargeCurrency>hotel</ChargeCurrency>
          <!-- The value below overrides Custom1 from roombundle. -->
          <Custom1>ratecode321</Custom1>
          <!-- Custom2 is inherited from roombundle. -->
        </Rate>
        <Rate rate_rule_id="us_or_gb">
          <Baserate currency="USD">268.33</Baserate>
          <Tax currency="USD">26.83</Tax>
          <OtherFees currency="USD">1.00</OtherFees>
          <!-- The value below overrides Custom1 from roombundle. -->
          <Custom1>ratecode432</Custom1>
          <!-- Custom2 is inherited from roombundle. -->
        </Rate>
      </Rates>
    </RoomBundle>
  </Result>
</Transaction>

<RoomBundle>

تُحدِّد هذه السياسة أسعار "حِزم الغرف" ومدى توفّرها عندما تكون عنصرًا ثانويًا في <Result> في رسالة <Transaction>. حدد عنصرًا منفصلاً لكل مجموعة حزمة أو برنامج رحلة. لتحديد الحزمة وبنود "حِزم الغرف"، استخدِم <RoomData>.

يظهر العنصر <RoomBundle> في المكان التالي ضمن التسلسل الهرمي بتنسيق XML لرسالة المعاملة:

+ <Transaction>
    + <PropertyDataSet>  // Room and package metadata
        + <Property>
        + <RoomData>
        + <PackageData>
    + <Result>           // Pricing and availability
        + <Rates>
        + <RoomBundle>
        + ...

لمزيد من المعلومات، يُرجى الرجوع إلى استخدام حِزم الغرف.

البنية

يستخدم العنصر <RoomBundle> البنية التالية:

<?xml version="1.0" encoding="UTF-8"?>
<Transaction ... >
  <Result>
    ...
    <RoomBundle>
      <!-- Required unless specified inline under <RoomData> -->
      <RoomID>room_ID</RoomID>
      <!-- Required  <PackageData> -->
      <PackageID>package_ID</PackageID>

      <!-- Required -->
      <Baserate currency="currency_code">price</Baserate>
      <!-- Required -->
      <Tax currency="currency_code">taxes</Tax>
      <!-- Required -->
      <OtherFees currency="currency_code">other_fees</OtherFees>

      <Refundable available="[false|true]" refundable_until_days="number_of_days"
        refundable_until_time="time"/>
      <!-- Required -->
      <ChargeCurrency>[deposit|hotel|installments|web]</ChargeCurrency>
      <Occupancy>max_number_of_intended_occupants</Occupancy>
      <OccupancyDetails> <!-- optional info about the types of guests,
      whether adults or children --></OccupancyDetails>

      <BreakfastIncluded>boolean_value</BreakfastIncluded>
      <InternetIncluded>boolean_value</InternetIncluded>
      <ParkingIncluded>boolean_value</ParkingIncluded>

      <RatePlanID>rate_plan_ID</RatePlanID>

      <Rates>...</Rates>

      <Custom1>custom_value_1</Custom1>
      <Custom2>custom_value_2</Custom2>
      <Custom3>custom_value_3</Custom3>
      <Custom4>custom_value_4</Custom4>
      <Custom5>custom_value_5</Custom5>
    </RoomBundle>
    ...
  </Result>
</Transaction>

السمات

لا يتضمّن العنصر <RoomBundle> أيّ سمات.

العناصر الفرعية

يحتوي العنصر <RoomBundle> على العناصر الثانوية التالية:

العنصر الفرعي مطلوب؟ النوع الوصف
<Baserate> Required float تحدد هذه السمة سعر مجموعة الغرف الخاصة بالإقامة. يستخدم هذا العنصر البنية نفسها مثل <Baserate> في <Result>، باستثناء ما يلي:
  • في حال عدم توفّر الغرفة لبرنامج الرحلة، عليك إزالة العنصر <RoomBundle> للإشارة إلى أنّ الغرفة لم تعُد متوفّرة في المستودع. لمزيد من المعلومات، راجِع القسم إزالة حزمة غرف.
<BreakfastIncluded> Optional boolean تُحدِّد هذه السياسة ما إذا كانت حزمة الغرف هذه تشمل وجبة فطور مع السعر.
<ChargeCurrency> Optional enum متى وأين يدفع المستخدم مقابل الحجز. يستخدم هذا العنصر البنية نفسها المستخدَمة في <ChargeCurrency> في <Result>.

تكون القيمة التلقائية web.
<Custom[1‑5]> Optional string حقول مخصّصة لتمرير بيانات إضافية إلى الصفحات المقصودة لحزمة الغرف. تستخدم هذه العناصر البنية نفسها المستخدَمة في <Custom[1-5]> في <Result>. الحدّ الأقصى المسموح به لعدد الأحرف هو 200 لكل حقل مخصّص. للحصول على مزيد من المعلومات، يمكنك الاطّلاع على ملفات الصفحة المقصودة.

في حال توفير عناصر <Custom> في العنصر <Result>، لن يتم اكتسابها في العنصر <RoomBundle> ويجب تحديدها بشكل منفصل لكل <RoomBundle>، أو يمكن تضمينها في <PackageData> إذا لزم الأمر.
<InternetIncluded> Optional boolean إذا كانت "حِزمة الغرف" تتضمن إمكانية الوصول إلى الإنترنت بدون أي رسوم، لن تتضمّن الحزم الأخرى هذه وسائل الراحة. لا تضبط هذا العنصر لحِزم الغرف في فندق يوفّر خدمة إنترنت مجانية لجميع الغرف. لا ينطبق هذا العنصر على الإنترنت السلكي داخل الغرفة أو الإنترنت اللاسلكي غير المتوفّر في غرف النزلاء.
<Occupancy> Required integer الحدّ الأقصى لعدد الضيوف المطلوب لهم "حزمة غرف". على سبيل المثال، قد يتّسع جناح كبير لـ 6 نزلاء، ولكن "حزمة شهر العسل" مخصّصة لضيفَين فقط.

يجب أن تكون هذه القيمة أقل من أو مساوية لقيمة <Capacity>، وهو عدد الأشخاص الذين يمكن أن تتّسع الغرفة فعليًا.

عند تحديد عدد النزلاء في عنوان URL للصفحة المقصودة، استخدِم المتغيرين NUM-ADULTS وNUM-CHILDREN على النحو الموضّح في مقالة استخدام المتغيرات والشروط. القيمة التلقائية هي 2 البالغين و0 الأطفال.

ويجب أن تكون قيمة <Occupancy> عددًا صحيحًا موجبًا بين 1 و99، بشكل شامل.

ملاحظات:

  • وننصح بشدة باستخدام السمة <Occupancy> للسمة <RoomBundle>، وبالتالي سيتم وضع علامة عليها على أنّها مطلوبة، وإذا تم حذفها، سيتم عرض الخطأ 1097.
  • تأتي <Occupancy> من كائن البيانات بهذا الترتيب: <RoomBundle> و<PackageData>، ثم = <RoomData>. في حال عدم وجود قيمة في أي من هذه الخيارات، سيتم ضبط القيمة التلقائية على 2.
  • وقد يكون <Occupancy> مصحوبًا بالسمة <OccupancyDetails> التي تحدّد نوع الضيوف (الأشخاص البالغون أو الأطفال). راجِع <OccupancyDetails> للتعرّف على بنية العناصر الفرعية ووصفها.
  • عند ضبط <Occupancy> في كل من <RoomBundle> و<PackageData>، تكون الأولوية للقيمة في <RoomBundle>.
<OtherFees> Required float الرسوم الأخرى غير السعر الأساسي والضرائب التي تؤثر في السعر النهائي للغرفة. يتضمّن العنصر <OtherFees> سمة واحدة مطلوبة، وهي currency، تحدّد رمز العملة المكوَّن من ثلاثة أحرف للرسوم. على سبيل المثال، استخدِم USD للدولار الأمريكي.
<PackageID> Optional (recommended) string المعرّف الفريد لبيانات الحزمة يمكنك استخدام رقم التعريف هذا لمطابقة بيانات حزمة الغرف مع ما تم إرساله في <PackageData>. لمزيد من المعلومات، يُرجى الرجوع إلى البيانات الوصفية لحزمة الغرف. (يمكنك أيضًا استخدام هذا المعرّف للإشارة إلى تعريف شائع لحزمة الغرف يُستخدَم في رسالة "معاملة" واحدة عند تحديد بيانات مجموعة غرف مضمَّنة).
<ParkingIncluded> Optional boolean ما إذا كانت حزمة الغرف تشمل موقف سيارات بدون أي رسوم، حيث تكون خدمة ركن السيارات خدمة مدفوعة في هذا الفندق. لا تحدّد قيمة لهذا العنصر لفندق يقدّم مواقف مجانية للسيارات.

القيمتان الصالحتان هما 0 (أو false) و1 (أو true). القيمة التلقائية هي false.
<RatePlanID> Optional string يمثّل رقم تعريف خطة الأسعار المعرّف الفريد لمجموعة الغرف والحزمة. على سبيل المثال، إذا كانت قيمة <RoomID> تساوي 5 وقيمة <PackageID> خاصة بـ ABC، يمكنك استخدام القيمة 5-ABC للسمة <RatePlanID>. ننصحك بشدة باستخدام RatePlanID كمتغير لإنشاء عنوان URL الديناميكي للصفحة المقصودة (المعروف سابقًا باسم "نقطة البيع").

للحصول على مزيد من المعلومات، راجِع استخدام المتغيرات والشروط.
<Rates> Optional <Rates> تتجاوز الأسعار الإعدادات التلقائية لحزمة الغرف هذه. يستخدم هذا العنصر بنية <Rates> نفسها في <Result>.
<Refundable> Optional Object تتيح هذه السياسة إدراج السعر على أنّه قابل للاسترداد بالكامل أو عملية إلغاء مجانية. وفي حال عدم توفيرها، لا يتم عرض أي معلومات عن عملية ردّ الأموال. تؤدي سياسة ردّ الأموال على مستوى <PackageData> إلى إلغاء سياسة ردّ الأموال على مستوى <Result>. تؤدي سياسة ردّ الأموال على المستوى <Rates> إلى إلغاء سياسة ردّ الأموال على المستوى <PackageData>. ويمكن أيضًا إبراز الأسعار القابلة للاسترداد للمستخدمين، من خلال خيارات بديلة بدون تعديل مخطط رسالة المعاملات مباشرةً. يمكنك الاطّلاع على مزيد من المعلومات حول هذه الخيارات سياسة الأسعار القابلة لردّ الأموال.

يعرض المثال التالي العنصر <Refundable> مع ضبط كل سماته:

<Refundable available="1" refundable_until_days="7"
refundable_until_time="18:00:00"/>

ملاحظة: ننصح بإعداد جميع السمات. ويتم إنشاء رسالة تحذيرية بشأن حالة الخلاصة عندما لا يتم ضبط سمة واحدة أو أكثر.

في حال عدم ضبط أي سمات، لن يتم عرض السعر قابل للاسترداد. السمات هي:

  • available: (مطلوبة) يجب ضبطها على 1 (أو true) للإشارة إلى ما إذا كان السعر يسمح بردّ الأموال بالكامل، أو يتم ضبطها على 0 (أو false).
  • refundable_until_days: (مطلوبة إذا كانت قيمة available هي true) لتحديد عدد الأيام التي يمكن خلالها طلب استرداد الأموال بالكامل قبل تسجيل الوصول. يجب أن تكون قيمة refundable_until_days عددًا صحيحًا يتراوح بين 0 و330، بشكل شامل.
  • refundable_until_time: (يُنصح بهذا الخيار بشدة إذا كانت قيمة السمة available هي true) تحدّد آخر وقت من اليوم، بالتوقيت المحلي للفندق، الذي سيتم فيه قبول طلب استرداد الأموال بالكامل. يمكن دمج هذه السمة مع السمة refundable_until_days للإشارة، على سبيل المثال، إلى أنّ "عمليات ردّ الأموال متاحة حتى الساعة 4:00 بعد الظهر قبل يومَين من تسجيل الوصول". إذا لم يتم ضبط السمة refundable_until_time، سيتم ضبط القيمة التلقائية على منتصف الليل.

    تستخدم قيمة هذه السمة تنسيق الوقت.

عند تحديد السمات، يجب التنبّه لما يلي:

  • إذا لم يتم ضبط available أو refundable_until_days، لن يتم عرض السعر على أنّه قابل للاسترداد.
  • وإذا كانت قيمة السمة available هي 0 (أو false)، يتم تجاهل السمات الأخرى. ولا يمكن استرداد السعر حتى في حال ضبط إحدى السمتَين الأخريين أو كلتيهما.
<RoomID> Required string المعرّف الفريد لبيانات الغرفة. يمكنك استخدام رقم التعريف هذا لمطابقة بيانات حزمة الغرف مع البيانات التي أرسلتها في <RoomData>. لمزيد من المعلومات، راجِع البيانات الوصفية لحزمة الغرف. (يمكنك أيضًا استخدام هذا المعرّف للإشارة إلى تعريف مشترك للغرفة في رسالة "معاملة" واحدة عند تحديد بيانات الغرفة بشكل مضمّن).
<Tax> Required float الضرائب التي يتم احتسابها للسعر النهائي للغرفة. يتضمّن العنصر <Tax> سمة واحدة مطلوبة، وهي currency، تحدّد رمز العملة المكوّن من ثلاثة أحرف للضرائب. على سبيل المثال، استخدِم USD للدولار الأمريكي.

أمثلة

حزمة لشخص واحد

يحدد المثال التالي استجابة بحزمة إشغال واحدة. عندما يختار المستخدم 1 في أداة اختيار عدد النزلاء، تعرض Google أدنى سعر مؤهَّل بغض النظر عن عدد النزلاء.

في حال عدم توفّر سعر للإقامة الفردية، ستعرض Google أدنى سعر للإقامة المزدوجة. تجدر الإشارة إلى أنّه لا يتم الاستعلام مباشرةً عن أسعار الإقامة الفردية إذا تم تخزين الأسعار المزدوجة أو أسعار أكثر مؤقتًا لخط سير الرحلة.

يشير هذا المثال إلى البيانات الوصفية للغرفة والحزمة محدّدة مسبقًا باستخدام العنصرَين <RoomID> و<PackageID>. استخدِم العنصرَين <RoomData> و<PackageData> لتحديد تلك المعلومات.

<!-- Efficient method of defining Room Bundles-->
<!----- Occupancy of 1 example ----->

<Transaction timestamp="2017-07-18T16:20:00-04:00" id="12345678">
  <!-- Part1: Define RoomData and PackageData in PropertyDataSet -->
  <!-- Note:  Once defined it does not have to be repeated for future
              Transaction Messages.
              PropertyDataSets can also be defined and sent in their own
              Transaction Message separately from pricing. Google can be
              configured to pull just PropertyDataSets once per day
              (or on a predefined frequency). -->
  <PropertyDataSet>
    <Property>180054</Property>
    <!-- Can be reused by multiple Room Bundles -->
    <RoomData>
      <RoomID>060773</RoomID>
      <Name>
        <Text text="Single Queen Room - Non-Smoking" language="en"/>
        <Text text="Chambre de la Roi Premium - Pas de Fumeurs" language="fr"/>
      </Name>
      <!-- Room can accommodate up to 4, but package data specifies occupancy
           between 1 to 4 -->
      <Capacity>4</Capacity>
    </RoomData>
    <RoomData>
      <RoomID>436233</RoomID>
      <Name>
        <Text text="Premium King Room - Non-Smoking" language="en"/>
        <Text text="Chambre de le Roi Premium - Pas de Fumeurs" language="fr"/>
      </Name>
      <Capacity>4</Capacity>
    </RoomData>
    <!-- Can be reused by multiple Room Bundles -->
    <PackageData>
      <PackageID>P11111</PackageID>
      <Occupancy>1</Occupancy>
      <ChargeCurrency>web</ChargeCurrency>
      <Refundable available="1" refundable_until_days="7"
           refundable_until_time="18:00:00"/>
      <ParkingIncluded>1</ParkingIncluded>
      <InternetIncluded>1</InternetIncluded>
    </PackageData>
    <PackageData>
      <PackageID>P54321</PackageID>
      <Occupancy>2</Occupancy>
      <ChargeCurrency>web</ChargeCurrency>
      <Refundable available="1" refundable_until_days="7"
           refundable_until_time="18:00:00"/>
      <ParkingIncluded>1</ParkingIncluded>
      <InternetIncluded>1</InternetIncluded>
    </PackageData>
    <PackageData>
      <PackageID>P12345</PackageID>
      <Occupancy>4</Occupancy>
      <ChargeCurrency>web</ChargeCurrency>
      <Refundable available="1" refundable_until_days="1"
           refundable_until_time="18:00:00"/>
      <ParkingIncluded>1</ParkingIncluded>
      <InternetIncluded>1</InternetIncluded>
    </PackageData>
  </PropertyDataSet>

    <!-- Efficient method of defining Room Bundles -->
    <!-- Part 2: Reference RoomData and PackageData through ID -->
  <Result>
    <!-- Single occupancy pricing will be specified in a room bundle below -->
    <Property>180054</Property>
    <Checkin>2017-10-07</Checkin>
    <Nights>2</Nights>
    <!-- Base Room Bundle -->
    <RoomBundle>
      <RoomID>060773</RoomID>
      <PackageID>P54321</PackageID>
      <Baserate currency="USD">199.99</Baserate>
      <Tax currency="USD">25.12</Tax>
      <OtherFees currency="USD">2.00</OtherFees>
      <RatePlanID>060773-P54321</RatePlanID>
    </RoomBundle>
    <RoomBundle>
      <RoomID>060773</RoomID>
      <PackageID>P11111</PackageID>
      <!-- Price for 1 ("occupancy") is the lowest price and will be
           displayed -->
      <Baserate currency="USD">174.99</Baserate>
      <Tax currency="USD">22.08</Tax>
      <OtherFees currency="USD">2.00</OtherFees>
      <RatePlanID>060773-P11111</RatePlanID>
    </RoomBundle>
    <!-- Premium Room Bundle -->
    <RoomBundle>
      <RoomID>436233</RoomID>
      <PackageID>P12345</PackageID>
      <!-- Price for 4 ("occupancy"), any eligible room bundle with 1 or more
           occupancy will be displayed-->
      <Baserate currency="USD">298.88</Baserate>
      <Tax currency="USD">42.12</Tax>
      <OtherFees currency="USD">10.00</OtherFees>
      <RatePlanID>436233-P12345</RatePlanID>
    </RoomBundle>
    <!-- ..Continue providing all available RoomBundle rates under matched
         property for 1 or more occupancies..-->
  </Result>
</Transaction>

شخصان أو أكثر

يحدد المثال التالي استجابة تتضمن إقامة نزيل أو أكثر.

يشير هذا المثال إلى البيانات الوصفية للغرفة والحزمة محدّدة مسبقًا باستخدام العنصرَين <RoomID> و<PackageID>. استخدِم العنصرَين <RoomData> و<PackageData> لتحديد تلك المعلومات.

<!-- Efficient method of defining Room Bundles-->
<!----- Occupancy of 3 example ----->

<Transaction timestamp="2017-07-18T16:20:00-04:00" id="12345678">
  <!-- Efficient method of defining Room Bundles-->
  <!-- Part1: Define RoomData and PackageData in PropertyDataSet -->
  <PropertyDataSet>
    <Property>180054</Property>
    <!-- Can be reused by multiple Room Bundles -->
    <RoomData>
      <RoomID>060773</RoomID>
      <Name>
        <Text text="Single Queen Room - Non-Smoking" language="en"/>
        <Text text="Chambre de la Roi Premium - Pas de Fumeurs" language="fr"/>
      </Name>
      <!-- Room can accommodate up to 4, but package data specifies occupancy
           between 1 to 4 -->
      <Capacity>4</Capacity>
    </RoomData>
    <RoomData>
      <RoomID>436233</RoomID>
      <Name>
        <Text text="Premium King Room - Non-Smoking" language="en"/>
        <Text text="Chambre de le Roi Premium - Pas de Fumeurs" language="fr"/>
      </Name>
      <Capacity>4</Capacity>
    </RoomData>
    <!-- Can be reused by multiple Room Bundles -->
    <PackageData>
      <PackageID>P33333</PackageID>
      <Occupancy>3</Occupancy>
      <ChargeCurrency>web</ChargeCurrency>
      <Refundable available="1" refundable_until_days="7"
           refundable_until_time="18:00:00"/>
      <ParkingIncluded>1</ParkingIncluded>
      <InternetIncluded>1</InternetIncluded>
    </PackageData>
    <PackageData>
      <PackageID>P12345</PackageID>
      <Occupancy>4</Occupancy>
      <ChargeCurrency>web</ChargeCurrency>
      <Refundable available="1" refundable_until_days="1"
           refundable_until_time="18:00:00"/>
      <ParkingIncluded>1</ParkingIncluded>
      <InternetIncluded>1</InternetIncluded>
    </PackageData>
  </PropertyDataSet>

  <Result>
    <Property>180054</Property>
    <Checkin>2017-10-07</Checkin>
    <Nights>2</Nights>
    <!-- Efficient method of defining Room Bundles -->
    <!-- Part 2: Reference RoomData and PackageData through ID -->
    <!-- Base Room Bundle -->
    <RoomBundle>
      <!-- Baserate above and attributes must match atleast one room bundle
           below -->
      <RoomID>060773</RoomID>
      <PackageID>P33333</PackageID>
      <Baserate currency="USD">499.99</Baserate>
      <Tax currency="USD">55.12</Tax>
      <OtherFees currency="USD">22.00</OtherFees>
    </RoomBundle>
    <!-- Premium Room Bundle -->
    <RoomBundle>
      <RoomID>436233</RoomID>
      <PackageID>P12345</PackageID>
      <!-- Lowest price for 3 ("occupancy"), shown below, will be displayed -->
      <Baserate currency="USD">598.88</Baserate>
      <Tax currency="USD">62.12</Tax>
      <OtherFees currency="USD">30.00</OtherFees>
    </RoomBundle>
    <!-- ..Continue providing all available RoomBundle rates under matched
         property for 2 or more occupancies..-->
  </Result>
</Transaction>


مجموعات غرف متعددة

يحدِّد المثال التالي الإشغال في حِزم غرف متعددة لتوضيح السعر المحتمل لغرف النُزُل المشترك.

<?xml version="1.0" encoding="UTF-8"?>
<Transaction ... >
  <Result>
    ...
    <!-- Suite Room Bundle -->
    <RoomBundle>
      <RoomID>suite1</RoomID>
      <PackageID>standard</PackageID>
      <Occupancy>2</Occupancy>
      <!-- Price for room -->
      <Baserate currency="USD">80.00</Baserate>
      <Tax currency="USD">5.12</Tax>
      <OtherFees currency="USD">2.00</OtherFees>
      <RoomData>
        <Name>
          <Text text="Suite for 2" language="en"/>
        </Name>
      </RoomData>
    </RoomBundle>

    <!-- Small Dorm Room Bundle -->
    <RoomBundle>
      <RoomID>small_dorm</RoomID>
      <PackageID>economy</PackageID>
      <Occupancy>1</Occupancy>
      <!-- Price per bed -->
      <Baserate currency="USD">35.00</Baserate>
      <Tax currency="USD">3.50</Tax>
      <OtherFees currency="USD">2.00</OtherFees>
      <RoomData>
        <Name>
          <Text text="1 bed in small dorm" language="en"/>
        </Name>
      </RoomData>
    </RoomBundle>

    <!-- Large Dorm Room Bundle -->
    <RoomBundle>
      <RoomID>large_dorm</RoomID>
      <PackageID>economy</PackageID>
      <Occupancy>1</Occupancy>
      <!-- Price per bed -->
      <Baserate currency="USD">20.00</Baserate>
      <Tax currency="USD">2.50</Tax>
      <OtherFees currency="USD">2.00</OtherFees>
      <RoomData>
        <Name>
          <Text text="1 bed in large dorm" language="en"/>
        </Name>
      </RoomData>
    </RoomBundle>
    ...
  </Result>
</Transaction>

أسعار مشروطة متعدّدة

يحدّد المثال التالي سعرًا أساسيًا وأسعارًا مشروطة متعدّدة ضمن <RoomBundle>:

<?xml version="1.0" encoding="UTF-8" ?>
<Transaction timestamp="2023-05-18T16:20:00-04:00" id="42">
  <Result>
    <Property>1234</Property>
    <Checkin>2023-04-10</Checkin>
    <Nights>2</Nights>
    <!-- When Google receives new room bundle information for an itinerary, all
    previous room bundle pricing is dropped from Google's cache. Thus, if you
    want to delete a specific room bundle from Google's cache, you may do so
    by simply not providing that specific room bundle in subsequent transaction
    messages. -->
    <RoomBundle>
     ...
      <!-- RoomID is required, PackageID is recommended. -->
      <RoomID>5</RoomID>
      <PackageID>ABC</PackageID>
      <!-- Baserate is required. -->
      <Baserate currency="USD">275.00</Baserate>
      <Tax currency="USD">27.50</Tax>
      <OtherFees currency="USD">2.00</OtherFees>

      <!-- RatePlanID is optional and represents the unique identifier for a
      room and package data combination. We strongly recommend using RatePlanID
      as a variable to build your dynamic landing page (formerly Point of Sale)
      URL. For details, see Using Variables and Conditions. -->
      <RatePlanID>5-ABC</RatePlanID>

      <!-- Occupancy is mandatory for RoomBundle elements. -->
      <!-- Elements below will get inherited to nested rate elements. -->
      <Occupancy>2</Occupancy>
      <OccupancyDetails>
        <NumAdults>2</NumAdults>
      </OccupancyDetails>
      <InternetIncluded>1</InternetIncluded>


      <!-- Rate rule "mobile" overrides chargeCurrency, "us_or_gb" doesn't. -->
      <ChargeCurrency>web</ChargeCurrency>
      <Custom1>ratebasic</Custom1>
      <!-- Neither rate overrides Custom2. -->
      <Custom2>ratebasic</Custom2>

      <Rates>
        <Rate rate_rule_id="mobile">
          <Baserate currency="USD">258.33</Baserate>
          <Tax currency="USD">25.83</Tax>
          <OtherFees currency="USD">1.00</OtherFees>
          <!-- The value below overrides ChargeCurrency from roombundle. -->
          <ChargeCurrency>hotel</ChargeCurrency>
          <!-- The value below overrides Custom1 from roombundle. -->
          <Custom1>ratecode321</Custom1>
          <!-- Custom2 is inherited from roombundle. -->
        </Rate>
        <Rate rate_rule_id="us_or_gb">
          <Baserate currency="USD">268.33</Baserate>
          <Tax currency="USD">26.83</Tax>
          <OtherFees currency="USD">1.00</OtherFees>
          <!-- The value below overrides Custom1 from roombundle. -->
          <Custom1>ratecode432</Custom1>
          <!-- Custom2 is inherited from roombundle. -->
        </Rate>
      </Rates>
    </RoomBundle>
  </Result>
</Transaction>

<OccupancyDetails>

تحدّد السمة <Occupancy> في رسالة المعاملة الحدّ الأقصى لعدد الضيوف في غرفة أو حزمة. ويمكن أن يحتوي "<OccupancyDetails>" على معلومات إضافية، مثل عدد الضيوف ونوعهم (أشخاص بالغون أو أطفال).

عند ظهور <Occupancy> و<OccupancyDetails> ضمن العنصر <Rates> في <Result> أو <RoomBundle>، هذا يعني أنّ المعدّل مقيَّد بتفاصيل عدد النزلاء.

البنية

عند ظهور السمة <OccupancyDetails>، تكون مسبوقة دائمًا بـ <Occupancy>. لاحظ بناء الجملة التالي:

<?xml version="1.0" encoding="UTF-8"?>
<Transaction ... >
  <Result>
  ...
    <Occupancy>max_number_of_intended_occupants</Occupancy>
    <OccupancyDetails>
      <NumAdults>number_of_adults</NumAdults>
      <Children>
        <Child age=age_of_one_child_guest/>
        <Child age=age_of_one_child_guest/>
      </Children>
    </OccupancyDetails>
  </Result>
</Transaction>

العناصر الفرعية

يحتوي العنصر <OccupancyDetails> على العناصر الثانوية التالية:

العنصر الفرعي مطلوب؟ النوع الوصف
<NumAdults> Required integer تمثّل هذه السمة عدد النزلاء البالغين. الحد الأدنى:1، الحد الأقصى:20.
<Children> Optional Object حاوية لعنصر <Child> واحد أو أكثر
<Child age> Optional integer الحد الأقصى لعمر هذا الطفل، مثل <Child age="17">.

أمثلة

توضّح الأمثلة التالية كيفية ظهور <OccupancyDetails> ضمن <Results> أو <RoomBundle> أو العنصر الفرعي <Rates>.

استجابة النتيجة

يحدّد المثال التالي برنامج رحلة واحدًا وأسعاره لموقع واحد استجابةً لطلب بحث عن الأسعار المباشرة حيث حدّد المستخدم عدد الضيوف وأنواعهم. هنا، يتم عرض <OccupancyDetails> -- وهو شخصان بالغان وطفل واحد -- في <Result>.

<?xml version="1.0" encoding="UTF-8"?>
<Transaction timestamp="2017-07-23T16:20:00-04:00" id="42">
  <Result>
    <Property>060773</Property>
    <RoomID>RoomType101</RoomID>
    <PackageID>Package101</PackageID>
    <Checkin>2018-06-10</Checkin>
    <Nights>2</Nights>
    <Baserate currency="USD">278.33</Baserate>
    <Tax currency="USD">25.12</Tax>
    <OtherFees currency="USD">2.00</OtherFees>
    <AllowablePointsOfSale>
      <PointOfSale id="site1"/>
    </AllowablePointsOfSale>
    <Occupancy>3</Occupancy>
    <OccupancyDetails>
      <NumAdults>2</NumAdults>
      <Children>
        <Child age="17"/>
      </Children>
    </OccupancyDetails>
  </Result>
</Transaction>

الردّ على الأسعار

يوضّح المثال التالي برنامج رحلة واحدًا وأسعاره لشخص بالغ وطفل واحد. هنا، يتم عرض <OccupancyDetails> في عنصر <Rates> من <Result>.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Transaction id="Wtdj8QoQIWcAAbaTGlIAAAC4" timestamp="2018-04-18T11:27:45-04:00">
  <Result>
    <Property>8251</Property>
    <Checkin>2018-06-20</Checkin>
    <Nights>1</Nights>
    <Baserate currency="USD">62.18</Baserate>
    <Tax currency="USD">2.45</Tax>
    <OtherFees currency="USD">0.00</OtherFees>
    <Rates>
      <Rate rate_rule_id="rule-951">
        <Occupancy>2</Occupancy>
        <OccupancyDetails>
          <NumAdults>1</NumAdults>
          <Children>
            <Child age="17"/>
          </Children>
        </OccupancyDetails>
        <Baserate currency="USD">42.61</Baserate>
        <Tax currency="USD">5.70</Tax>
        <OtherFees currency="USD">0.00</OtherFees>
        <Custom1>abc4</Custom1>
        <AllowablePointsOfSale>
          <PointOfSale id="yourhotelpartnersite.com"/>
        </AllowablePointsOfSale>
      </Rate>
    </Rates>
  </Result>
</Transaction>

حزمة الغرف

يحدّد المثال التالي عدد النزلاء بالغين وطفل واحد لمدة ليلتين بسعر قابل للاسترداد. هنا، تظهر علامة <OccupancyDetails> داخل <RoomBundle>

<?xml version="1.0" encoding="UTF-8"?>
<Transaction timestamp="2017-07-23T16:20:00-04:00" id="42">
  <Result>
    <Property>6781291</Property>
    <Checkin>2017-08-05</Checkin>
    <Nights>2</Nights>
    ...
    <RoomBundle>
      <RoomID>10291</RoomID>
      <RatePlanID>564739</RatePlanID>
      <PackageID>564739</PackageID>
      <Occupancy>3</Occupancy>
      <OccupancyDetails>
        <NumAdults>2</NumAdults>
        <Children>
          <Child age="17"/>
        </Children>
      </OccupancyDetails>
      <ChargeCurrency>web</ChargeCurrency>
      <Refundable available="true" refundable_until_days="1" refundable_until_time="23:59:00" />
      <Baserate currency="USD">185.34</Baserate>
      <Tax currency="USD">37.06</Tax>
      <OtherFees currency="USD">2.22</OtherFees>
    </RoomBundle>
  </Result>
</Transaction>

مجموعات غرف متعددة

يوضّح المثال التالي أسعارًا متعدّدة خاصة بـ <RoomBundle> يمكن أن تقتصر على الإقامة لفردَين بالغَين وطفلَين. هنا، تظهر <OccupancyDetails> في العنصر <Rates> ضمن <RoomBundle>.

<?xml version="1.0" encoding="UTF-8"?>
<Transaction timestamp="2017-07-18T16:20:00-04:00" id="42">
  <Result>
    <Property>1234</Property>
    <Checkin>2018-06-10</Checkin>
    <Nights>2</Nights>
    <Baserate currency="USD">275.00</Baserate>
    <Tax currency="USD">27.50</Tax>
    <OtherFees currency="USD">0</OtherFees>
    <RoomBundle>
      <RoomID>5</RoomID>
      <PackageID>STD</PackageID>
      <Baserate currency="USD">275.00</Baserate>
      <Tax currency="USD">27.50</Tax>
      <OtherFees currency="USD">0</OtherFees>
      <InternetIncluded>1</InternetIncluded>
      <ChargeCurrency>web</ChargeCurrency>
      <Custom1>ratebasic</Custom1>
      <Custom2>ratebasic</Custom2>
      <Occupancy>4</Occupancy>
      <OccupancyDetails>
          <NumAdults>2</NumAdults>
          <Children>
              <Child age="17"/>
              <Child age="17"/>
          </Children>
      </OccupancyDetails>
      <Rates>
        <Rate rate_rule_id="mobile">
          <Baserate currency="USD">258.33</Baserate>
          <Tax currency="USD">25.83</Tax>
          <OtherFees currency="USD">1.00</OtherFees>
          <ChargeCurrency>hotel</ChargeCurrency>
          <Custom1>ratecode321</Custom1>
        </Rate>
        <Rate rate_rule_id="us_or_gb">
          <Baserate currency="USD">268.33</Baserate>
          <Tax currency="USD">26.83</Tax>
          <OtherFees currency="USD">1.00</OtherFees>
          <Custom1>ratecode432</Custom1>
        </Rate>
      </Rates>
    </RoomBundle>
  </Result>
</Transaction>