أسعار مدة الإقامة (خسارة)

Travel Partner Prices API

تمنحك Travel Partner Prices API واجهة RESTful لإرسال أسعار الفنادق إلى Google.

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

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

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

نقطة نهاية الخدمة هي عنوان URL أساسي يحدِّد عنوان الشبكة لخدمة واجهة برمجة التطبيقات. قد تحتوي خدمة واحدة على نقاط نهاية متعددة للخدمة. تحتوي هذه الخدمة على نقطة نهاية الخدمة التالية، وجميع معرّفات الموارد المنتظمة المدرَجة مرتبطة بنقطة نهاية الخدمة هذه:

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‏ 2019-05-03T14:09:00Z والذي تم استلامه بعد رسالة عن برامج الرحلة نفسها تحمل requestTime‏ 2019-05-03T14:10:00Z، وذلك لصالح الرسالة التي تحمل الطابع الزمني اللاحق.

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

تكون الأجزاء من الثانية اختيارية، ويمكن التعبير عنها بدقة تصل إلى نانو ثانية. على سبيل المثال، кодّت القيمة 2017-01-15T01:30:15.01-08:00 15.01 ثانية بعد 01: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.

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

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

taxes[] 30 float مكوّن الضريبة في أسعار مدة الإقامة

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

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

مثال

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

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

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

يتم احتساب صفيف 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}