أسعار مدة الإقامة

Travel Partner Prices API

توفّر لك واجهة برمجة التطبيقات Travel Partner Prices واجهة RESTful لإرسال أسعار الأماكن المتاحة للاستئجار إلى Google.

الخدمة: travelpartnerprices.googleapis.com

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

نقطة نهاية الخدمة

نقطة نهاية الخدمة هي الجزء الأساسي من عنوان URL الذي يحدّد عنوان الشبكة لخدمة واجهة برمجة التطبيقات. قد يكون للخدمة الواحدة أكثر من نقطة نهاية واحدة. تحتوي هذه الخدمة على نقطة النهاية التالية، وجميع عناوين URI المُدرَجة تكون نسبيّة لهذه النقطة:

https://travelpartnerprices.googleapis.com
الطُرق
ingestLosPropertyPrices POST /v1/accounts/account_id/properties/property_id:ingestLosPropertyPrices

حمِّل أسعار الإقامة لمدة محددة للمكان المحدّد.

يتطلّب رسالة أسعار LoS مشفّرة بتنسيق JSON (راجِع أدناه) كنص رسالة HTTP.

account_id: قيمة السلسلة هذه هي قيمة "رقم تعريف الحساب" المُدرَجة في صفحة "إعدادات الحساب" ضمن Hotel Center.

property_id: يجب أن تكون قيمة هذا العنصر سلسلة تتطابق مع معرّف البيانات في "خلاصة بيانات الفنادق".

مصادقة واجهة برمجة التطبيقات

تستخدم واجهة برمجة التطبيقات Travel Partner Prices API بروتوكول OAuth 2.0 لمصادقة تطبيقك حتى تتمكّن من الوصول إلى واجهات برمجة التطبيقات.

اتّبِع تعليمات إعداد OAUTH 2.0 للحصول على إذن باستخدام واجهة برمجة التطبيقات Travel Partner Prices API.

عند إنشاء مشروع جديد لواجهة Travel Partners Prices API، عليك تفعيل إمكانية الوصول إلى مشروعك الجديد على Google Cloud Console، وهو ما يشبه التعليمات المقدَّمة في Travel Partner API.

يُرجى الرجوع إلى الخطوات المقدَّمة في Travel Partner API واستبدال جميع عبارات "Travel Partner API" بعبارة "Travel Partner Prices API" لتفعيل مشروعك.

نطاق واجهة برمجة التطبيقات Travel Partner Prices API هو: "https://travelpartnerprices.googleapis.com"

مسار التحميل لواجهة برمجة تطبيقات Travel Partner Prices API هو: "/travel/lodging/uploads/accounts/<account_id>/property_data"

الطلبات

البنية

تستخدم الرسالة LoS Prices البنية التالية:

{
  "requestTime": YYYY-MM-DDTHH:mm:ss.SSSZ,
  "propertyPrices": {
    "arrivalDatePrices": [{
      "startDate": {
        "year": int
        "month": int
        "day": int
      }
      "endDate": {
        "year": int
        "month": int
        "day": int
      }
      "productPrices": [{
        "roomTypeId": "string"
        "ratePlanId": "string"
        "occupancyPrices": [{
          "adults": int
          "prices": [{
            "rateRuleId": "string"
            "currencyCode": "string"
            "rates": [night_1,night_2,...]
            "taxes": [night_1,night_2,...]
            "fees": [night_1,night_2,...]
          }]
        }]
      }]
    }]
  }
}

العناصر والسمات

تتضمّن رسالة أسعار مدة الإقامة العناصر والسمات التالية:

العنصر عدد مرات الظهور النوع الوصف
requestTime 1 string

تمثّل هذه السمة الوقت الذي تم فيه إرسال رسالة "سعر مدة الإقامة"، ويتم التعبير عنها كسلسلة منسّقة وفق RFC 3339.

تتم معالجة أي رسالة تم إرسالها باستخدام requestTime خلال الـ 24 ساعة السابقة، ويتم تجاهل الرسائل التي لم يتم إرسالها باستخدام requestTime.

تتم معالجة الرسائل بترتيب requestTime، بغض النظر عن ترتيب استلامها. على سبيل المثال، يتم تجاهل تعديل السعر الذي يتضمّن requestTime بقيمة 2019-05-03T14:09:00Z والذي تم تلقّيه بعد رسالة تتضمّن خطط الرحلة نفسها مع requestTime بقيمة 2019-05-03T14:10:00Z، ويتم الاحتفاظ بالرسالة التي تحمل الطابع الزمني الأحدث.

يتطلّب معيار RFC 3339 تحديد التاريخ والوقت بشكل كامل على النحو التالي: YYYY-MM-DDThh:mm:ss.SSZ. يجب تحديد المنطقة الزمنية كمعادلة موجبة أو سالبة hh:mm من التوقيت العالمي المنسّق، أو Z كاختصار للتوقيت العالمي المنسّق.

الثواني الكسرية اختيارية، ويمكن التعبير عنها بدقة تصل إلى جزء من مليار من الثانية. على سبيل المثال، ترمّز 2017-01-15T01:30:15.01-08:00 15.01 ثانية بعد الساعة 1:30 صباحًا بتوقيت المحيط الهادئ في 15 يناير 2017.
propertyPrices 1 Object أسعار مكان للاستئجار تنطبق جميع الأسعار ضمن هذا propertyPrices على الموقع نفسه.

لا يتم تكرار هذا العنصر. لإرسال أسعار لعدة أماكن متاحة للاستئجار، عليك تقديم طلبات HTTP متعددة (طلب واحد على الأقل لكل مكان).

arrivalDayPrices[] 1..n Object أسعار تاريخ الوصول تنطبق جميع الأسعار الواردة في arrivalDayPrices على مكان إقامة محدّد، ولكن مع تواريخ وصول مختلفة.
startDate 1 Object يتم تطبيق productPrices على جميع تواريخ الوصول بين startDate وendDate، بما في ذلك هذان التاريخان.

إذا كنت تحاول تحديد تاريخ وصول واحد فقط (وليس نطاقًا زمنيًا)، أدخِل تاريخ الوصول في كل من startDate وendDate.

startDate.year 1 integer عام startDate يجب أن تتراوح القيمة بين 1 و9999.
startDate.month 1 integer الشهر من السنة يجب أن تتراوح القيمة بين 1 و12.
startDate.day 1 integer اليوم من الشهر يجب أن يكون رقمًا يتراوح بين 1 و31 ويكون صالحًا للسنة والشهر.
endDate 0..1 Object يتم تطبيق productPrices على جميع تواريخ الوصول بين startDate وendDate، بما في ذلك هذان التاريخان.

إذا كنت تحاول تحديد تاريخ وصول واحد فقط (وليس نطاقًا)، يمكن حذف endDate.

endDate.year 1 integer عام endDate يجب أن تتراوح القيمة بين 1 و9999.
endDate.month 1 integer الشهر من السنة يجب أن تتراوح القيمة بين 1 و12.
endDate.day 1 integer اليوم من الشهر يجب أن يكون رقمًا يتراوح بين 1 و31 ويكون صالحًا للسنة والشهر.
productPrices[] 1..n Object تمثّل هذه السمة أسعار المنتج. تنطبق جميع الأسعار الواردة ضمن productPrices على مجموعة محدّدة من الموقع وتاريخ الوصول، ولكن على منتجات مختلفة.
roomTypeId 0..1 string المعرّف الفريد للغرفة التي يشير إليها هذا السعر. استخدِم هذا المعرّف لمطابقة بيانات "حزمة الغرفة" مع البيانات التي أرسلتها في roomdata. لمزيد من المعلومات، يُرجى الاطّلاع على البيانات الوصفية لحزمة الغرف.
ratePlanId 0..1 string المعرّف الفريد لبيانات الحزمة التي يشير إليها هذا السعر. استخدِم رقم التعريف هذا لمطابقة بيانات "حزمة الغرف" مع البيانات التي أرسلتها في packagedata. لمزيد من المعلومات، يُرجى الاطّلاع على البيانات الوصفية لحزمة الغرف.
occupancyPrices[] 1..n Object أسعار الإقامة تنطبق جميع الأسعار الواردة في هذا occupancyPrices على موقع محدّد وتاريخ وصول ومجموعة منتجات، ولكنها تختلف حسب عدد الأشخاص الذين يشغلون المكان.
adults 1 integer تمثّل هذه السمة الحد الأقصى لعدد الضيوف الذين يمكن حجزهم في كل غرفة، بما في ذلك البالغون والأطفال. يتم ضبط هذه القيمة لجميع الأسعار ضمن حقل occupancyPrices ذي الصلة، ويجب أن تكون عددًا صحيحًا موجبًا يتراوح بين 1 و99.

ملاحظة: يُرجى التواصل مع فريق الدعم لإرسال بيانات الإشغال لأكثر من أربعة بالغين.
prices[] 1..n Object أسعار مدة الإقامة تنطبق جميع الأسعار ضمن prices على موقع محدّد وتاريخ وصول محدّد ومنتج محدّد ومجموعة إشغال محدّدة.
rateRuleId 0..1 string بالنسبة إلى الأسعار المشروطة، يتطابق هذا المعرّف مع سعر وتعريف في ملف تعريف قاعدة الأسعار. عدد الأحرف المسموح به في هذا الحقل هو 40 حرفًا.
currencyCode 1 string تمثّل هذه السمة رمز العملة المكوّن من ثلاثة أحرف والذي يتم توفير rates وtaxes به. على سبيل المثال، "USD" للدولار الأمريكي.
rates[] 30 float مكوّن السعر الأساسي لأسعار مدة الإقامة

في حال توفير قيمة taxes مقابلة، يكون هذا المعدّل غير شامل للضريبة. السعر الإجمالي هو مجموع السعر والضريبة المعنيين.

تمثّل القيمة في الفهرس n مدة إقامة n+1.

يجب إرسال مجموعة كاملة من الأسعار لمدة الإقامة (LoS) تبلغ 30 سعرًا في المرة الواحدة. إذا أرسلت أقل من 30 سعرًا، سيتم التعامل مع جميع أسعار مدة الإقامة المقدَّمة على أنّها عادية، ولن تتوفّر الأسعار المتبقية حتى مدة الإقامة 30. إذا أرسلت أكثر من 30 سعرًا، سيتم تجاهل أي أسعار ترسلها بعد السعر رقم 30 .

يجب تمثيل مدة الإقامة غير المتاحة باستخدام 0.

taxes[] 30 float تمثّل هذه السمة جزء الضريبة من أسعار مدة الإقامة.

تمثّل القيمة في الفهرس n مدة إقامة n+1.
fees[] 30 float تمثّل هذه السمة جزء الرسوم من أسعار مدة الإقامة.

تمثّل القيمة في الفهرس n مدة إقامة n+1.

مثال

الأسعار والضرائب استنادًا إلى مدة الإقامة

يعرض المثال التالي ضبط الحد الأدنى لمدة الإقامة على ليلتَين لتاريخ تسجيل وصول واحد وعدم ضبط أي توفّر لتاريخ تسجيل وصول آخر. إذا ضبطت startDate من 1/9/2023 بدون endDate، يعني ذلك أنّك تحدّد الأسعار ليوم واحد فقط ويمكنك حذف endDate.

تتيح لك مصفوفة occupancyPrices التي تم ضبطها على 2 تحديد أسعار مختلفة لحالات إشغال مختلفة. لذلك، لا يحدّ عدم توفّر غرف شاغرة في 04/09/23 من عدد الغرف المتاحة rates.

يتم احتساب مصفوفة taxes المعروضة على أنّها% 10 من السعر.

تفرض مصفوفة fees المعروضة رسوم تنظيف بقيمة 50 دولار أمريكي لكل إقامة.

إذا كان تاريخ تسجيل الوصول بأكمله غير متاح، مثلاً 3/9/2023، عليك إرسال التاريخ بشكل صريح وحذف rates وtaxes وproductPrices للإشارة إلى عدم توفّر أي غرف في التاريخ المطلوب.

{
  "requestTime": "2023-08-10T12:15:222",
  "propertyPrices": {
    "arrivalDatePrices": [
      {
        "startDate": {
          "year": 2023,
          "month": 9,
          "day": 1
        },
        "productPrices": [
          {
            "occupancyPrices": [
              {
                "adults": 2,
                "prices": [
                  {
                    "currencyCode": "USD",
                    "rates": [
                      0, 200, 300, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
                      0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0
                    ],
                    "taxes": [
                      0, 20, 30, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
                      0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0
                    ],
                    "fees": [
                      0, 50, 50, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
                      0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0
                    ]
                  }
                ]
              }
            ]
          }
        ]
      },
      {
        "startDate": {
          "year": 2023,
          "month": 9,
          "day": 3
        },
        "productPrices": [
          {
            "occupancyPrices": [
              {
                "adults": 2,
                "prices": [
                  {
                    "currencyCode": "USD",
                    "rates": [
                      0, 200, 300, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
                      0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0
                    ],
                    "taxes": [
                      0, 20, 30, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
                      0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0
                    ],
                    "fees": [
                      0, 50, 50, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
                      0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0
                    ]
                  }
                ]
              }
            ]
          }
        ]
      }
    ]
  }
}

نص الاستجابة

إذا كانت الاستجابة ناجحة، سيحتوي نص الاستجابة على بيانات بالبنية التالية:

تمثيل JSON 
        {
          "name": "string"
        }
الحقول
name اسم المورد الخاص بـ PropertyPrices الذي تم تعديله. يحتوي النموذج على:
accounts/{account}/properties/{property}.