Định giá theo thời gian lưu trú (LoS)

Travel Partner Prices API

Travel Partner Prices API cung cấp cho bạn một giao diện RESTful để gửi giá của cơ sở lưu trú đến Google.

Dịch vụ: travelpartnerprices.googleapis.com

Để gọi dịch vụ này, bạn nên dùng thư viện ứng dụng do Google cung cấp. Nếu ứng dụng của bạn cần dùng các thư viện riêng để gọi dịch vụ này, hãy liên hệ với Nhà quản lý tài khoản hỗ trợ kỹ thuật (TAM) để nhận Tài liệu khám phá cho dịch vụ này.

Điểm cuối dịch vụ

Điểm cuối dịch vụ là một URL cơ sở chỉ định địa chỉ mạng của một dịch vụ API. Một dịch vụ có thể có nhiều điểm cuối dịch vụ. Dịch vụ này có điểm cuối dịch vụ sau và tất cả URI được liệt kê đều liên quan đến điểm cuối dịch vụ này:

https://travelpartnerprices.googleapis.com

Phương thức

ingestLosPropertyPrices

POST /v1/accounts/account_id/properties/property_id:ingestLosPropertyPrices Tải Giá theo thời gian lưu trú đã cung cấp lên cho một cơ sở lưu trú cụ thể. Yêu cầu một thông báo về giá LoS được mã hoá bằng JSON (xem bên dưới) làm nội dung thông báo HTTP. account_id: Giá trị chuỗi này là giá trị "Mã tài khoản" được liệt kê trên trang Cài đặt tài khoản trong Hotel Center. property_id: Giá trị của phần tử này phải là một chuỗi khớp với mã trang thông tin trong Nguồn cấp dữ liệu danh sách khách sạn.

Xác thực API

Travel Partner Prices API sử dụng OAuth 2.0 để xác thực ứng dụng của bạn, nhờ đó bạn có thể truy cập vào các API này.

Làm theo hướng dẫn thiết lập OAUTH 2.0 để được cấp quyền cho Travel Partner Prices API.

Khi tạo một dự án mới cho Travel Partners Prices API, bạn cần bật quyền truy cập vào dự án mới của mình trên Google Cloud Console. Việc này tương tự như hướng dẫn được cung cấp trong Travel Partner API.

Tham khảo các bước được cung cấp trong API Đối tác du lịch và thay thế tất cả các trường hợp "API Đối tác du lịch" bằng "API Giá của đối tác du lịch" để bật dự án của bạn.

Phạm vi của Travel Partner Prices API là: "https://travelpartnerprices.googleapis.com"

Đường dẫn tải lên cho Travel Partner Prices API là: "/travel/lodging/uploads/accounts/<account_id>/property_data"

Lưu ý quan trọng: Travel Partner API và Travel Partner Prices API là hai API riêng biệt. Do đó, bạn nên tạo các dự án riêng biệt cho cả hai API trong bảng điều khiển Google Cloud.

Yêu cầu

Cú pháp

Thông báo LoS Prices sử dụng cú pháp sau:

{
  "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,...]
          }]
        }]
      }]
    }]
  }
}

Phần tử và thuộc tính

Thông báo về giá theo thời gian lưu trú có các phần tử và thuộc tính sau:

Phần tử	Số lần xuất hiện	Loại	Mô tả
requestTime	1	string	Thời điểm gửi thông báo Giá theo LoS, được biểu thị dưới dạng một chuỗi được định dạng theo RFC 3339. Những thông báo có requestTime cho biết được gửi trong vòng 24 giờ trước sẽ được xử lý và những thông báo không có requestTime đáp ứng điều kiện đó sẽ bị loại bỏ. Thông báo được xử lý theo thứ tự requestTime, bất kể thứ tự mà hệ thống nhận được. Ví dụ: một thông báo cập nhật giá có requestTime là 2019-05-03T14:09:00Z và hệ thống nhận được sau một thông báo cho cùng hành trình có requestTime là 2019-05-03T14:10:00Z sẽ bị loại bỏ để ưu tiên thông báo có dấu thời gian muộn hơn. RFC 3339 yêu cầu ngày giờ được chỉ định đầy đủ dưới dạng YYYY-MM-DDThh:mm:ss.SSZ. Bạn phải chỉ định múi giờ dưới dạng giá trị chênh lệch hh:mm dương hoặc âm so với giờ UTC, hoặc Z dưới dạng viết tắt của giờ UTC. Bạn không bắt buộc phải sử dụng phần giây và có thể biểu thị độ chính xác lên đến phần tỷ giây. Ví dụ: 2017-01-15T01:30:15.01-08:00 mã hoá 15,01 giây sau 01:30 theo giờ PST vào ngày 15 tháng 1 năm 2017.
propertyPrices	1	Object	Giá của một cơ sở lưu trú. Tất cả mức giá trong propertyPrices này đều áp dụng cho cùng một cơ sở lưu trú. Phần tử này không được lặp lại. Để gửi giá cho nhiều cơ sở lưu trú, bạn cần thực hiện nhiều yêu cầu HTTP (ít nhất một yêu cầu cho mỗi cơ sở lưu trú).
arrivalDayPrices[]	1..n	Object	Giá cho một ngày đến. Tất cả giá trong arrivalDayPrices này đều áp dụng cho một cơ sở lưu trú cụ thể, nhưng có ngày đến khác nhau.
startDate	1	Object	productPrices được áp dụng cho tất cả các ngày đến trong khoảng từ startDate đến endDate, kể cả ngày đến. Nếu bạn chỉ muốn chỉ định một ngày đến (chứ không phải một phạm vi), hãy nhập ngày đến vào cả startDate và endDate.
startDate.year	1	integer	Năm startDate. Giá trị phải từ 1 đến 9999.
startDate.month	1	integer	Tháng trong năm. Giá trị phải từ 1 đến 12.
startDate.day	1	integer	Ngày trong tháng. Giá trị phải từ 1 đến 31 và có giá trị trong năm và tháng.
endDate	0..1	Object	productPrices được áp dụng cho tất cả các ngày đến trong khoảng từ startDate đến endDate (bao gồm cả hai ngày này). Nếu chỉ cố gắng chỉ định một ngày đến (chứ không phải một khoảng ngày), bạn có thể bỏ qua endDate.
endDate.year	1	integer	Năm endDate. Giá trị phải từ 1 đến 9999.
endDate.month	1	integer	Tháng trong năm. Giá trị phải từ 1 đến 12.
endDate.day	1	integer	Ngày trong tháng. Giá trị phải từ 1 đến 31 và có giá trị trong năm và tháng.
productPrices[]	1..n	Object	Giá của một sản phẩm. Tất cả giá trong productPrices này đều áp dụng cho một tổ hợp ngày đến và tài sản cụ thể, nhưng có nhiều sản phẩm.
roomTypeId	0..1	string	Mã nhận dạng riêng biệt của phòng mà giá này đề cập đến. Sử dụng mã này để so khớp dữ liệu Gói dịch vụ phòng với dữ liệu mà bạn gửi trong roomdata. Để biết thêm thông tin, hãy tham khảo mục siêu dữ liệu của Gói dịch vụ phòng.
ratePlanId	0..1	string	Mã nhận dạng riêng biệt của dữ liệu gói dịch vụ mà giá này đang đề cập đến. Sử dụng mã này để so khớp dữ liệu Gói dịch vụ phòng với dữ liệu mà bạn gửi trong packagedata. Để biết thêm thông tin, hãy tham khảo mục siêu dữ liệu của Gói dịch vụ phòng.
occupancyPrices[]	1..n	Object	Giá cho một số lượng người lưu trú. Tất cả giá trong occupancyPrices này đều áp dụng cho một tài sản, ngày đến, tổ hợp sản phẩm cụ thể, nhưng áp dụng cho số lượng người lưu trú khác nhau.
adults	1	integer	Số lượng khách tối đa có thể đặt cho mỗi phòng, bao gồm cả người lớn và trẻ em. Giá trị này được đặt cho tất cả các mức trong trường occupancyPrices tương ứng và phải là một số nguyên dương từ 1 đến 99. Lưu ý: Liên hệ với nhóm hỗ trợ để gửi thông tin về số người lưu trú lớn hơn 4 người lớn.
prices[]	1..n	Object	Giá theo thời gian lưu trú. Tất cả giá trong prices đều áp dụng cho một tổ hợp cụ thể giữa cơ sở lưu trú, ngày đến, sản phẩm và số người lưu trú.
rateRuleId	0..1	string	Đối với giá phòng có điều kiện, mã này sẽ so khớp giá với một định nghĩa trong tệp Định nghĩa quy tắc giá. Giới hạn ký tự cho trường này là 40 ký tự.
currencyCode	1	string	Mã đơn vị tiền tệ gồm 3 chữ cái mà bạn cung cấp rates và taxes. Ví dụ: "USD" cho đô la Mỹ.
rates[]	30	float	Thành phần giá cơ bản của giá theo thời gian lưu trú. Nếu bạn cung cấp giá trị taxes tương ứng, thì mức thuế này sẽ không bao gồm thuế. Tổng giá là tổng của mức giá và thuế có liên quan. Giá trị tại chỉ mục n tương ứng với thời gian lưu trú n+1. Bạn phải gửi toàn bộ 30 mức giá trong LoS cùng một lúc. Nếu bạn gửi ít hơn 30, thì tất cả giá LoS mà bạn cung cấp sẽ được xử lý như bình thường và các mức giá còn lại sẽ không có sẵn cho đến LoS 30. Nếu bạn gửi hơn 30,thì mọi mức giá bạn gửi sau mức giá thứ 30 sẽ bị loại bỏ . Bạn nên dùng 0 để biểu thị những khoảng thời gian lưu trú không có sẵn.
taxes[]	30	float	Thành phần thuế của giá theo thời gian lưu trú. Giá trị tại chỉ mục n tương ứng với thời gian lưu trú n+1.
fees[]	30	float	Thành phần phí của giá theo thời gian lưu trú. Giá trị tại chỉ mục n tương ứng với thời gian lưu trú n+1.

Ví dụ:

Giá và thuế dựa trên thời gian lưu trú

Ví dụ sau đây cho thấy cách đặt thời gian lưu trú tối thiểu là 2 cho một ngày nhận phòng và đặt trạng thái không có phòng cho một ngày nhận phòng khác. Nếu bạn đặt startDate từ ngày 1 tháng 9 năm 2023 mà không có endDate, tức là bạn đang chỉ định giá cho một ngày duy nhất và có thể bỏ qua endDate.

Mảng occupancyPrices được đặt thành 2 cho phép bạn đặt các mức giá khác nhau cho các sức chứa khác nhau. Do đó, không còn phòng trống vào ngày 04/09/2023, giới hạn số phòng rates.

Mảng taxes được hiển thị được tính là 10% tỷ lệ.

Mảng fees được hiển thị sẽ áp dụng phí vệ sinh là 50 USD cho mỗi lượt lưu trú.

Nếu toàn bộ ngày nhận phòng là không có phòng (9/3/2023), bạn phải gửi ngày một cách rõ ràng và bỏ qua rates, taxes và productPrices để cho biết rằng không có phòng vào ngày được yêu cầu.

{
  "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
                    ]
                  }
                ]
              }
            ]
          }
        ]
      }
    ]
  }
}

Lưu ý quan trọng: Bạn nên đặt rates, taxes và fees thành 0 cho khoảng thời gian lưu trú không có sẵn.

Nội dung phản hồi

Nếu thành công, phần nội dung phản hồi sẽ chứa dữ liệu có cấu trúc sau:

Biểu diễn dưới dạng JSON
{ "name": "string" }

Trường
name	Tên tài nguyên của PropertyPrices đã được sửa đổi. Có dạng: accounts/{account}/properties/{property}.