رسالة المعاملة (بيانات الموقع)

نظرة عامة

تحدّد رسالة ARI Transaction (بيانات المنشأة) المعلومات المتعلّقة بأنواع الغرف والحِزم (أو خطط الأسعار) لكل منشأة. تتضمّن بيانات كل نوع غرفة معرّفًا فريدًا (RoomID) واسمًا مترجمًا ووصفًا وعناوين URL لصور الغرف. تتضمّن بيانات كل حزمة معرّفًا فريدًا (PackageID) واسمًا مترجمًا ووصفًا وعدد الأشخاص الذين يمكن أن تستوعبهم الحزمة ومزايا إضافية.

يمكنك استخدام رسالة المعاملة لإجراء ما يلي:

• حدِّد البيانات لموقع واحد أو أكثر.
• حدِّد نوع الغرفة ومعلومات الحزمة لكل مكان مخصّص للاستئجار.
• التحكّم في عروض المنتجات

يمكنك أيضًا ضبط الإجراءات لتنفيذ ما يلي:

• أضِف نوع غرفة وحزمة إلى مكان إقامة.

  نقطة أساسية: يبلغ الحدّ الأقصى لعدد أنواع الغرف 3,000 لكلّ مكان للإقامة. تتضمّن الحِزم أيضًا حدًا أقصى منفصلاً يبلغ 3,000 حزمة لكل موقع. يمكنك استخدام رسالة <Transaction> لإزالة أنواع الغرف أو الحِزم.

• إزالة نوع غرفة وحزمة من مكان إقامة

• أضِف نقاط الولاء أو برنامج مكافآت إلى حزمة أو فندق.

للاطّلاع على أمثلة على رسائل المعاملات، راجِع أمثلة على المعاملات (بيانات الموقع).

العناصر المطلوبة والاختيارية

يقدّم مرجع XML أوصافًا للعناصر المطلوبة والاختيارية. للحصول على تفاصيل حول السمات والعناصر الفرعية، يُرجى الاطّلاع على عناصر وسمات المعاملات (بيانات العقارات).

البنية والمخططات

استخدِم مثال بنية رسالة المعاملة (بيانات الموقع) كمرجع عند إنشاء رسالة المعاملة للتأكّد من اتّباع التنسيق الصحيح.

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

الإرشادات

اتّبِع الإرشادات التالية لرسالة المعاملة:

الإجراءات:

‫delta: تُستخدَم لإضافة أو تعديل أنواع غرف وحِزم جديدة (خطط أسعار).

‫overlay: تُستخدَم لاستبدال جميع أنواع الغرف والحِزم في مكان للاستئجار بمجموعة جديدة. يجب أن تتضمّن المعلومات جميع أنواع الغرف وخطط الأسعار التي تريد مواصلة بيعها.

اللغات المتوفّرة:

حدِّد لغة واحدة أو لغتَين (الإنجليزية ولغة محلية للعنصر إذا لزم الأمر) لحقول الاسم والوصف والترجمة والشرح. يمكنك إضافة أكثر من لغتين إذا لزم الأمر.

أنواع الغرف والحِزم:

عند تعديل نوع غرفة أو حزمة، يجب إرسال جميع المعلومات ذات الصلة بنوع الغرفة أو الحزمة. على سبيل المثال، عند إضافة صورة، يجب أيضًا تضمين الاسم والوصف.

<AllowablePackageIDs> و<AllowableRoomIDs> اختياريان، وفي حال عدم ضبطهما، يمكن إجراء أي مجموعة من نوع الغرفة وخطة الأسعار. سيظل عليك إرسال بيانات التوفّر والأسعار مع أرقام تعريف نوع الغرفة وخطة الأسعار. تتيح لك هذه العناصر التحكّم في المنتجات بالإضافة إلى إيقاف المجموعات التي لم يعُد نظامك متوافقًا معها.

أرسِل إلى Google رسالة تعديل على رسالة المعاملة كلما حدث تغيير في أنواع الغرف أو الحِزم، أو إذا أردت إضافة تفاصيل مهمة حول أنواع الغرف أو الحِزم.

ملاحظة: بما أنّ Google تخزّن بيانات الموقع المرتبطة بموقع "مطابَق"، لا يمكن أن تقبل Google هذه البيانات إلا بعد أن يتم "مطابقة" الموقع ذي الصلة في النظام. يمكن أن يساعد إرسال جميع المواقع في خلاصة القائمة في تجنُّب حدوث أخطاء أو تأخيرات لاحقة.

نقاط الولاء:

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

استخدِم العنصر <MilesIncluded> لتحديد حملة الولاء أو تعديلها. لمزيد من المعلومات، راجِع المعاملة(بيانات الموقع). يمكن تضمين نقاط الولاء مع <PackageData>.

مثال

يقدّم هذا القسم مثالاً أساسيًا لرسالة معاملة ARI باستخدام العناصر المطلوبة والاختيارية. لإضافة أنواع الغرف والحِزم أو تعديلها، يمكنك استخدام إجراء delta لإضافة أنواع الغرف والحِزم أو تعديلها، أو overlay لاستبدال جميع تعريفات أنواع الغرف والحِزم (يؤدي ذلك إلى حذف الإدخالات القديمة).

يجب تحديد لغة واحدة أو لغتَين (الإنجليزية ولغة محلية للعنصر إذا لزم الأمر) لحقول "الاسم" و"الوصف" و"التعليق". بعد ذلك، أضِف معلومات بيانات العقار، بما في ذلك روابط تؤدي إلى الصور.

بالنسبة إلى <PropertyID> و<RoomID>، استخدِم المعرّفات نفسها التي تستخدمها في نظامك لخطط الأسعار وأنواع الغرف (على التوالي). يُعدّ الاتساق مع نظامك أمرًا بالغ الأهمية لضمان عرض Google لأسعارك وبياناتك بشكلٍ صحيح.

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

بعد إعداد ملفك، عليك إرساله إلى Google عبر رسالة POST إلى نقطة النهاية التالية: https://www.google.com/travel/hotels/uploads/property_data

لمزيد من المعلومات حول كيفية إرسال الرسالة، يُرجى الاطّلاع على إرسال الرسائل.

يوضّح المثال التالي كيفية ضبط رسالة المعاملة باستخدام إجراء delta:

<?xml version="1.0" encoding="UTF-8"?>
<Transaction timestamp="202X-XX-XXT00:00:00-0X:00" id="12345678" partner="partner_key">
  <PropertyDataSet action="delta">
    <Property>PROPERTYID</Property>
      <RoomData>
        <RoomID>ROOMID</RoomID>
        <Name><Text text="ROOM NAME" language="en"/></Name>
        <Description>
          <Text text="ROOM DESCRIPTION TEXT" language="en"/>
        </Description>
        <Capacity>4</Capacity>
        <PhotoURL>
          <Caption><Text text="ROOM PHOTO CAPTION TEXT" language="en"/></Caption>
          <URL>https://LINK TO PHOTO</URL>
        </PhotoURL>
      </RoomData>
      <PackageData>
        <PackageID>BASE</PackageID>
        <Name><Text text="Internet Special" language="en"/></Name>
        <Description><Text text="Direct Booking through Hotel Website" language="en"/></Description>
        <Refundable available="true" refundable_until_days="2" refundable_until_time="12:00"/>
      </PackageData>
  </PropertyDataSet>
</Transaction>

للاطّلاع على مزيد من الأمثلة، مثل كيفية استخدام الإجراء overlay وإضافة نوع غرفة وحزمة إلى بيانات الموقع الحالية وإزالة أنواع الغرف والحِزم الحالية، يُرجى الاطّلاع على أمثلة على المعاملات (بيانات الموقع).

طرق التنفيذ

يقدّم هذا القسم حلولاً للحالات التي قد تواجهها أثناء إرسال رسائل المعاملات.

السيناريو 1: كيفية إزالة بيانات نوع الغرفة

كيف يمكنني إزالة بيانات أنواع الغرف و/أو الحِزم الحالية؟

الوصف

لقد أرسلت أنواع غرف متعدّدة، بما في ذلك غرف بحجم King وغرف بحجم Queen، للمكان المخصّص للاستئجار. جميع أنواع غرف Queen غير متاحة أثناء إعادة التصميم، وتتوفّر حاليًا أنواع غرف King فقط.

الحل

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

عيّنة

يوضّح مقتطف XML هذا كيفية استخدام الإجراء overlay لإزالة نوع غرفة.

ملاحظة: على الرغم من أنّ هذا النموذج يغطي نوع الغرفة، يمكنك أيضًا استخدام الإجراء نفسه لإزالة بيانات الحزمة.

في ما يلي delta الإجراء الأصلي الذي يتضمّن نوعَي الغرف King وQueen:

  <PropertyDataSet action="delta">
    <Property>Property_1</Property>
    <RoomData>
      <RoomID>King</RoomID>
      <Name>
        <Text text="King" language="en"/>
      </Name>
      <Capacity>2</Capacity>
    </RoomData>
    <PackageData>
      <PackageID>Standard</PackageID>
      <Name>
        <Text text="Standard" language="en"/>
      </Name>
      <Description>
        <Text text="Standard rate" language="en"/>
      </Description>
      <Refundable available="true" refundable_until_days="7" refundable_until_time="18:00:00"/>
      <BreakfastIncluded>0</BreakfastIncluded>
      </PackageData>
    <RoomData>
      <RoomID>Queen</RoomID>
      <Name>
        <Text text="Queen" language="en"/>
      </Name>
      <Capacity>2</Capacity>
      <!-- Additional RoomData child elements omitted. -->
    </RoomData>
  </PropertyDataSet>

يمكنك بعد ذلك ضبط overlay لإزالة نوع الغرفة Queen والإبقاء على نوع الغرفة King:

  <PropertyDataSet action="overlay">
    <Property>Property_1</Property>
    <RoomData>
      <RoomID>King</RoomID>
      <Name>
        <Text text="King" language="en"/>
      </Name>
      <Capacity>2</Capacity>
    </RoomData>
    <PackageData>
      <PackageID>Standard</PackageID>
      <Name>
        <Text text="Standard" language="en"/>
      </Name>
      <Description>
        <Text text="Standard rate" language="en"/>
      </Description>
      <Refundable available="true" refundable_until_days="7" refundable_until_time="18:00:00"/>
      <BreakfastIncluded>0</BreakfastIncluded>
    </PackageData>
  </PropertyDataSet>

السيناريو 2: كيفية التحكّم في المنتجات باستخدام AllowablePackageIDs

كيف يمكنني التحكّم في المنتجات (مجموعات من أنواع الغرف والحِزم) عندما يتم تجميع الحِزم حسب نوع الغرفة؟

ملاحظة: إذا كانت أنواع الغرف مجمّعة حسب الحِزم، اطّلِع على السيناريو 3.

الوصف

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

الحل

أرسِل رسالة "معاملة" معدَّلة تحدّد المنتجات المضمّنة في الحزمة باستخدام <AllowablePackageIDs>.

ملاحظة: استخدِم إما <AllowablePackageIDs> أو <AllowableRoomIDs>، ولكن ليس كلاهما، ويعتمد العنصر الذي تستخدمه على ما إذا كان نظامك يستخدم التسلسل الهرمي room>package أو package>room. إذا لم يتم تحديد أي من هذين العنصرين في رسالة المعاملة، يمكن دمج أنواع الغرف مع أي حزمة.

عيّنة

يوضّح مقتطف XML هذا كيفية استخدام <AllowablePackageIDs> لتحديد الحِزم المستخدَمة مع نوع غرفة معيّن. في هذا المثال، يتيح نوع غرفة "جناح بنتهاوس" حجز باقة "بنتهاوس" الشاملة فقط أو باقة "فطور مجاني"، بينما يتيح نوع غرفة "جناح كينغ" حجز باقة "كينغ" الشاملة فقط أو باقة "مناسبة للحيوانات الأليفة".

<RoomData>
  <RoomID>penthouse_suite</RoomID>
  <AllowablePackageIDs>
    <AllowablePackageID>penthouse_all_inclusive</AllowablePackageID>
    <AllowablePackageID>free_breakfast</AllowablePackageID>
  </AllowablePackageIDs>
  <!-- Additional child elements omitted. -->
</RoomData>
<RoomData>
  <RoomID>king_suite</RoomID>
  <AllowablePackageIDs>
    <AllowablePackageID>king_all_inclusive</AllowablePackageID>
    <AllowablePackageID>pet_friendly</AllowablePackageID>
  </AllowablePackageIDs>
  <!-- Additional child elements omitted. -->
</RoomData>
<PackageData>
  <PackageID>penthouse_all_inclusive</PackageID>
</PackageData>
<!-- Additional child elements omitted. -->
<PackageData>
  <PackageID>free_breakfast</PackageID>
</PackageData>
<!-- Additional child elements omitted. -->
<PackageData>
  <PackageID>king_all_inclusive</PackageID>
</PackageData>
<!-- Additional child elements omitted. -->
<PackageData>
  <PackageID>pet_friendly</PackageID>
</PackageData>

ملاحظة: إذا كنت تستخدم <AllowablePackageIDs> أو <AllowableRoomIDs> لإيقاف مجموعة ربما استخدمتها سابقًا ولكنها غير مسموح بها الآن في نظامك، لن تحتاج إلى إعادة إرسال بيانات "التوفّر والأسعار" لجميع التواريخ لمجرّد إزالة البيانات السابقة.

السيناريو 3: كيفية التحكّم في المنتجات باستخدام AllowableRoomIDs

كيف يمكنني التحكّم في المنتجات (مجموعات من أنواع الغرف والحِزم) عندما يتم تجميع أنواع الغرف حسب الحزمة؟

ملاحظة: إذا كانت حِزمك مجمّعة حسب نوع الغرفة، اطّلِع على السيناريو 2.

الوصف

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

الحل

أرسِل رسالة "المعاملة" المعدَّلة التي تحدّد المنتجات المضمَّنة في الحزمة باستخدام العنصر <AllowableRoomIDs>.

عيّنة

يوضّح مقتطف XML هذا كيفية استخدام <AllowableRoomID> لتحديد أنواع الغرف المطلة على البحر (King وQueen) في الحزمة.

<PackageID>RO</PackageID>
<AllowableRoomIDs>
  <AllowableRoomID>king_oceanview</AllowableRoomID>
  <AllowableRoomID>queen_oceanview</AllowableRoomID>
</AllowableRoomIDs>