תמחור משך השהייה (LoS)

Travel Partner Prices API

Travel Partner Prices API מספק ממשק RESTful לשליחת מחירי נכסים ל-Google.

שירות: travelpartnerprices.googleapis.com

כדי להתקשר לשירות הזה, מומלץ להשתמש בלקוח ש-Google מספקת ספריות. אם האפליקציה שלכם צריכה להשתמש בספריות משלכם כדי לקרוא לשירות הזה, עליכם לפנות למנהל החשבונות הטכני (TAM) כדי לקבל את מסמך הגילוי של השירות הזה.

נקודת קצה (endpoint) של שירות

נקודת קצה של שירות היא כתובת URL בסיסית שצוינה בה כתובת הרשת של שירות API. שירות אחד יכולות להיות כמה נקודות קצה (endpoint) של שירות. השירות הזה כולל את השירות הבא נקודת הקצה וכל מזהי ה-URI שמפורטים ביחס לנקודת הקצה הזו של השירות:

https://travelpartnerprices.googleapis.com
שיטות
ingestLosPropertyPrices POST /v1/accounts/account_id/properties/property_id:ingestLosPropertyPrices

מעלים את המחירים שצוינו על משך השהייה במלון מסוים.

נדרש הודעה מקודדת ב-JSON עם מחירי LoS (ראו בהמשך) כגוף הודעת ה-HTTP.

account_id: ערך המחרוזת הזה הוא מספר חשבון הערך שרשום בדף הגדרות החשבון ב'מלון' מרכז.

property_id: הערך של האלמנט הזה חייב להיות מחרוזת שתואמת למזהה הדף בפיד של רשימת המלונות.

אימות API

ב-Travel Partner Prices API נעשה שימוש ב-OAuth 2.0 כדי לאמת את האפליקציה כדי לקבל גישה לממשקי ה-API.

מבצעים את ההגדרה של OAUTH 2.0. הוראות לקבלת הרשאה עבור Travel Partner Prices API.

כשיוצרים פרויקט חדש ל-Travel Partners Prices API, צריך להפעיל את הגישה לפרויקט החדש במסוף Google Cloud, באופן דומה להוראות שמפורטות ב-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

הרגע שבו נשלחה הודעת LoS Price, שמופיע כמחרוזת בפורמט 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 משעון UTC, או Z כקיצור של שעון UTC.

שניות חלקיות הן אופציונליות, וניתן לציין אותן עד בדיוק בננו-שנייה. לדוגמה, הערך 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 מחירי המוצרים חלים על כל תאריכי ההגעה בין 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 המזהה הייחודי של החדר שאליו המחיר הזה מתייחס. כדאי להשתמש המזהה הזה, שיתאים לנתונים של חבילת החדר לנתונים ששלחת בנתוני החדר. למידע נוסף, עיינו במאמר מטא-נתונים של חבילות חדרים.
ratePlanId 0..1 string המזהה הייחודי של נתוני החבילה שאליהם מתייחס המחיר. כדאי להשתמש המזהה הזה כך שיתאים לנתונים של חבילת החדר לנתונים ששלחת בנתוני ה-package. למידע נוסף, עיינו במאמר מטא-נתונים של חבילות חדרים.
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 תואם, התעריף הזה לא כולל את המס. המחיר הכולל הוא הסכום של התעריף הרלוונטי והמס.

הערך ב-index n תואם למשך השהייה n+1.

חובה לשלוח את הקבוצה המלאה של 30 המחירים ב-LoS בכל פעם. אם תשלחו פחות מ-30, כל המחירים שציינתם יטופלו כרגיל, והתעריפים הנותרים לא יהיו זמינים עד ל-LoS 30. אם תשלחו יותר מ-30, כל המחירים ששלחתם מעבר לתעריף ה-30 יוסרו.

צריך לייצג משך שהייה לא זמין באמצעות 0

taxes[] 30 float רכיב המס במחירים של משך השהייה.

הערך ב-index n תואם למשך השהייה n+1.
fees[] 30 float רכיב העמלה במחירים של משך השהייה.

הערך ב-index n תואם למשך השהייה n+1.

דוגמה

מחירים מיסים על בסיס LOS

בדוגמה הבאה מוצגת הגדרה של משך שהייה מינימלי של 2 לתאריך צ'ק אין אחד והגדרה של חוסר זמינות לתאריך צ'ק אין אחר. אם מגדירים את startDate מ-1 בספטמבר 2023 ללא endDate, המשמעות היא שמציינים את התעריפים לתאריך אחד בלבד, וניתן להשמיט את endDate.

מערך occupancyPrices שמוגדר כ-2 מאפשר להגדיר תעריפים שונים לתפוסות שונות. לכן, אין מקום פנוי במגבלות של 04/09/23 זמין בתאריך rates.

המערך taxes שמוצג מחושב כ-10% מהתעריף.

מערך fees שמוצג מתייחס לתשלום של 50$ על ניקיון לכל שהייה.

אם תאריך הצ'ק אין המלא לא זמין &dash;9/3/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}