Package google.maps.booking.v1alpha

索引

BookingNotification

接收來自外部排程合作夥伴的預約通知。合作夥伴應呼叫 UpdateBooking 或 UpdateOrder 之一;這取決於該合作夥伴導入的是以預訂為基礎的遠端程序呼叫 (例如 CreateBooking 和 CheckAvailability),還是以訂單為基礎的遠端程序呼叫 (例如 CreateOrder 和 CheckOrderFulfillability)。

UpdateBooking

rpc UpdateBooking(UpdateBookingRequest) returns (Booking)

更新現有的 Booking

授權範圍

需要下列 OAuth 範圍:

  • https://www.googleapis.com/auth/mapsbooking
UpdateOrder

rpc UpdateOrder(UpdateOrderRequest) returns (Order)

更新現有的 Order

授權範圍

需要下列 OAuth 範圍:

  • https://www.googleapis.com/auth/mapsbooking

動態饋給

擷取外部集結網站合作夥伴上傳的動態饋給的處理狀態。

GetStatus

rpc GetStatus(GetStatusRequest) returns (FeedStatus)

擷取並傳回指定集結網站先前上傳的動態饋給的 Status

授權範圍

需要下列 OAuth 範圍:

  • https://www.googleapis.com/auth/mapsbooking
ListStatus

rpc ListStatus(ListStatusRequest) returns (ListStatusResponse)

擷取並傳回由指定集結網站先前上傳的多個商家、服務或供應情形動態饋給的 Status

授權範圍

需要下列 OAuth 範圍:

  • https://www.googleapis.com/auth/mapsbooking

InvalidationService

接收外部合作夥伴提出的資源撤銷要求。

InvalidateResource

rpc InvalidateResource(InvalidateResourceRequest) returns (Empty)

使現有資源失效。

如果要求的資源未訂閱 Google 服務,系統就會忽略要求。

支援的資源類型:- 取貨

授權範圍

需要下列 OAuth 範圍:

  • https://www.googleapis.com/auth/mapsbooking

InventoryStatus

擷取已上傳商家的商品目錄和比對狀態。

GetMerchantStatus

rpc GetMerchantStatus(GetMerchantStatusRequest) returns (MerchantStatus)

取得 MerchantMerchantStatus

授權範圍

需要下列 OAuth 範圍:

  • https://www.googleapis.com/auth/mapsbooking
ListMerchantStatuses

rpc ListMerchantStatuses(ListMerchantStatusesRequest) returns (ListMerchantStatusesResponse)

列出符合篩選條件的合作夥伴所有MerchantStatus

授權範圍

需要下列 OAuth 範圍:

  • https://www.googleapis.com/auth/mapsbooking

InventoryUpdate

接收來自外部集結網站的庫存清單更新資訊。

BatchDeleteGenericRecords

rpc BatchDeleteGenericRecords(BatchDeleteGenericRecordsRequest) returns (Empty)

刪除指定動態饋給類型的記錄。只執行基本驗證 (例如格式錯誤的要求),之後就會立即將適當的回應傳回合作夥伴。Google 會以非同步的方式對要求執行商業邏輯驗證。這項批次呼叫不保證不可分割性。

授權範圍

需要下列 OAuth 範圍:

  • https://www.googleapis.com/auth/mapsbooking
BatchPushGenericRecord

rpc BatchPushGenericRecord(BatchPushGenericRecordRequest) returns (Empty)

插入和/或更新指定動態饋給類型的記錄。只執行基本驗證 (例如格式錯誤的要求),之後就會立即將適當的回應傳回合作夥伴。Google 會以非同步的方式對要求執行商業邏輯驗證。這項批次呼叫不保證不可分割性。

授權範圍

需要下列 OAuth 範圍:

  • https://www.googleapis.com/auth/mapsbooking
BatchReplaceServiceAvailability

rpc BatchReplaceServiceAvailability(BatchReplaceServiceAvailabilityRequest) returns (BatchReplaceServiceAvailabilityResponse)

取代現有 ServicesAvailability。這項批次呼叫不保證不可分割性。系統只會傳回成功更新的供應時段。

授權範圍

需要下列 OAuth 範圍:

  • https://www.googleapis.com/auth/mapsbooking
CreateMerchant

rpc CreateMerchant(CreateMerchantRequest) returns (Merchant)

建立並傳回由指定集結網站管理的新 Merchant

授權範圍

需要下列 OAuth 範圍:

  • https://www.googleapis.com/auth/mapsbooking
CreateService

rpc CreateService(CreateServiceRequest) returns (Service)

建立並傳回由指定集結網站管理的商家的新 Service

授權範圍

需要下列 OAuth 範圍:

  • https://www.googleapis.com/auth/mapsbooking
DeleteMerchant

rpc DeleteMerchant(DeleteMerchantRequest) returns (Empty)

刪除由指定集結網站管理的現有 Merchant。系統也會停用商家所有的服務和可預訂時段。如果您日後再次新增商家,系統會顯示相同的服務和供應時段資訊。

授權範圍

需要下列 OAuth 範圍:

  • https://www.googleapis.com/auth/mapsbooking
DeleteService

rpc DeleteService(DeleteServiceRequest) returns (Empty)

刪除由指定集結網站管理的商家的現有 Service。系統也會刪除服務的所有供應情形。

授權範圍

需要下列 OAuth 範圍:

  • https://www.googleapis.com/auth/mapsbooking
ReplaceServiceAvailability

rpc ReplaceServiceAvailability(ReplaceServiceAvailabilityRequest) returns (ServiceAvailability)

取代並傳回由指定集結網站管理的商家現有 ServiceAvailability

授權範圍

需要下列 OAuth 範圍:

  • https://www.googleapis.com/auth/mapsbooking
UpdateMerchant

rpc UpdateMerchant(UpdateMerchantRequest) returns (Merchant)

更新並傳回由指定集結網站管理的現有 Merchant

授權範圍

需要下列 OAuth 範圍:

  • https://www.googleapis.com/auth/mapsbooking
UpdateService

rpc UpdateService(UpdateServiceRequest) returns (Service)

更新並傳回由指定集結網站管理的商家的現有 Service

授權範圍

需要下列 OAuth 範圍:

  • https://www.googleapis.com/auth/mapsbooking

ActionLinkType

已與動作連結建立關聯的預定動作類型。

列舉

ActionPlatform

執行這個動作時所在的平台。一般備用選項是網頁應用程式。建議至少要有一個含有 ACTION_PLATFORM_WEB_APPLICATION 的 ActionLink。以 Android 和 iOS 做為平台的連結,只能在各自的系統上使用。

列舉
ACTION_PLATFORM_UNSPECIFIED 未指定平台。
ACTION_PLATFORM_WEB_APPLICATION 動作平台通常是網頁。
ACTION_PLATFORM_MOBILE_WEB 動作平台是行動裝置上的網頁。
ACTION_PLATFORM_ANDROID 動作平台是 Android OS。
ACTION_PLATFORM_IOS 動作平台是 iOS。

建議

透過「透過 Google 預訂」向消費者顯示的建議。

欄位
text

Text

透過「透過 Google 預訂」預訂時向使用者顯示的自訂訊息。

可用性

商家服務的供應時段,標示出時間和名額數量。

欄位
start_time

Timestamp

預約時段的開始時間。

duration

Duration

預約時段的時間長度。

spots_total

int64

這個可預訂時段的總名額和開放名額數量。請見下方例子:

  • 瑜珈教室有 10 個名額,其中 3 個名額已有人預定:availability {spots_total: 10, spots_open: 7 ...}
  • 已預訂額滿的坐式按摩時段:availability {spots_total: 1, spots_open: 0 ...}

注意事項:如果使用下方定義的預訂情形壓縮格式來傳送要求,系統會推測這兩個欄位的值。

  • Recurrence 表示 spots_total=1spots_open=1
  • ScheduleException 意指 spots_total=1spots_open=0
spots_open

int64

開放名額的數量。

availability_tag

string

(選用) 用於辨識這個供應時段的隱晦字串。如果設定這個項目,系統會在預約/更新/取消預約的要求中納入這項資訊。

resources

Resources

此為選用資源;如果可預訂時段的服務中含括不同的員工或房間,可用「資源」來做明確的區隔。

例如同一間瑜珈教室有兩名講師共用:

availability { resources { staff_id: "1" staff_name: "Amy" }
               spots_total: 10 spots_open: 7 }
availability { resources { staff_id: "2" staff_name: "John" }
               spots_total: 5 spots_open: 2 }
payment_option_id[]

string

可用於支付該時段費用的付款方式參照 ID 清單。實際付款方式需在商家層級定義,而且可由多個商家共用。

這個欄位會覆寫服務訊息中指定的任何 payment_option_ids。同樣地,在這裡指定的 payment_option_ids「不必」顯示在服務訊息中,但必須在商家層級定義。

recurrence

Recurrence

供應時段的週期資訊,代表有多個開始時間。一個週期應包含一個工作天的預約。

schedule_exception[]

ScheduleException

無法安排這項服務的時間。如要限制 schedule_exception 訊息的數量,建議加入相鄰的例外狀況。

deposit

Deposit

選用欄位,表示這個可預訂時段是否需要收取訂金。指定此欄位將會覆寫該服務的訂金。

no_show_fee

NoShowFee

選用欄位,表示這個可預訂時段是否會收取逾時未到費用。指定此欄位將會覆寫該服務的逾時未到費用。

require_credit_card

RequireCreditCard

指出消費者是否需要提供信用卡資訊才能預訂這個時段。如果沒有設定這個值,系統會沿用服務層級設定的值 (如果已在服務層級設定)。(選填)

ticket_type_id[]

string

列出此供應時段支援的票券類型。如果未設定,表示父項服務中所有的票券類型皆可供這個時段使用。請注意,這個欄位的值必須在父項服務中定義,範例:

  • 提供四種票券類型的服務:TicketType {ticket_type_id: "adult_1" short_description: "全票平日"} TicketType {ticket_type_id: "adult_2" short_description: "全票週末"} TicketType {ticket_type_id: "youth_1" short_description: "學生票平日"} TicketType {ticket_type_id: "youth_2" short_description: "學生票週末"}

如要表示平日的庫存清單:availability {ticket_type_id: "adult_1" ticket_type_id: "youth_1"...}。如要表示假日的庫存清單:availability {ticket_type_id: "adult_2" ticket_type_id: "youth_2"...}

  • 提供三種票券類型的服務:TicketType {ticket_type_id: "adult" short_description: "全票"} TicketType {ticket_type_id: "youth" short_description: "學生票"} TicketType {ticket_type_id: "senior" short_description: "敬老票"}

如要表示這個時段提供全部三種票券類型,請使用 availability {ticket_type_id: "adult" ticket_type_id: "youth" ticket_type_id: "senior" ...} 或「availability {...}」(請勿在這個時段設定 ticket_type_id)。

(選填)

duration_requirement

DurationRequirement

顯示時段時間長度和/或結束時間的規定。如果版位無法提供服務,系統會忽略這個欄位。未用於「觀光景點」類別。(選填)

scheduling_rule_overrides

SchedulingRuleOverrides

預訂情形的排程規則。填入欄位後,就會覆寫服務層級 SchedulingRules 的任何相應排程規則。

confirmation_mode

ConfirmationMode

預訂此時段時可使用的確認模式。若可預訂時段的確認模式是 CONFIRMATION_MODE_SYNCHRONOUS,就必須在建立預訂時立刻確認或拒絕。若可預訂時段的確認模式為 CONFIRMATION_MODE_ASYNCHRONOUS,就必須立即拒絕或建立預訂,且建立狀態為「待處理」。

ConfirmationMode

預訂時段時可使用的確認模式。

列舉
CONFIRMATION_MODE_UNSPECIFIED 未指定確認模式,系統會假設採用同步確認。
CONFIRMATION_MODE_SYNCHRONOUS 以同步方式確認對這個時段所做的預訂。
CONFIRMATION_MODE_ASYNCHRONOUS 以非同步方式確認對這個時段所做的預訂。

DurationRequirement

這個列舉會指出,使用者須符合哪些條件,才能確認或查看要求的時段持續時間/結束時間。

列舉
DURATION_REQUIREMENT_UNSPECIFIED 未指定結束時間。此為預設值。
DO_NOT_SHOW_DURATION 使用者不會看到結束時間。
MUST_SHOW_DURATION 您必須先向使用者顯示結束時間,才能進行預約。

重複週期

週期訊息是選用項目,能夠以更精簡的表示法代表持續重複發生的可預訂時段。這類訊息通常代表一天的工作排程,接著,系統會使用 ScheduleException 訊息來代表工作日當天已預訂/無法預訂的時間範圍。

需求條件:

  1. 擴充可預訂時段或週期時,「不得」建立完全相同的時段。系統會將 ID、startTime、duration 和 resources 都相符的時段視為相同時段。
  2. 「請勿」在單一服務的時段中混用標準供應情形格式和週期。接受預約的商家/服務都可以使用週期格式,標準格式則適用於舉辦定期課程的商家/服務。
  3. 週期不得延續超過 24 小時。
欄位
repeat_until

Timestamp

設定期限來指明要重複提供可預訂時段到何時,用世界標準時間格式的最晚時間戳記表示 (最晚時間包含在內)。

repeat_every

Duration

定義連續的可預訂時段的間隔時間。

範例:假設供應時段的期間長度為 20 分鐘,repeat_every 為 30 分鐘,start_time 為上午 9:00,repeat_until 為上午 11:00,則產生的時段將分別為上午 9:00-9:20,上午 9:30-9:50,上午 10:00-10:20,上午 10:30-10:50,上午 11:00-11:20。(必要)

ScheduleException

ScheduleException 訊息代表該工作日已預訂/無法預訂的時間範圍,這些是上述週期中的例外部分。每次有人預訂時段,就應隨之更新例外狀況清單,以顯示最新的無法預訂時間範圍,請不要修改週期本身。

欄位
time_range

TimeRange

例外狀況的時間範圍。凡是與這個「從休息中到開門營業」的時間範圍重疊的週期指定時段,都視為無法預訂。

範例:假設週期指定的期間為 20 分鐘,repeat_every 為 30 分鐘,start_time 為上午 9:00,repeat_until 為上午 11:00,而 ScheduleException 的 time_range 為上午 9:45-11:00,則上午 9:30-9:50、上午 10-10:20,以及上午 10:30-10:50 的時段皆無法預訂。

請注意,由於這是「從休息中到開門營業」的時間範圍,因此從上午 11:00 開始的時段不會受到影響。

SchedulingRuleOverrides

供應情形層級排程規則。

欄位
last_bookable_sec

int64

這個時段可供預訂的最晚時間 (以秒為單位)。這個時間戳記必須設在該時段的 start_sec 之前才能生效 (如要讓使用者在開始時間之後繼續預訂,請使用服務層級的 SchedulingRules.min_booking_before_end_time)。如果使用這個項目,其將覆寫對應服務的 SchedulingRules 在 min_booking_buffer 中指定的任何值。

first_bookable_sec

int64

這個時段可供預訂的最早時間 (以秒為單位)。這個時間戳記必須早於該時段的 start_sec 或 last_bookable_sec (如有指定)。

last_online_cancellable_sec

int64

如果設定這項功能,可透過「透過 Google 預訂」取消該特定預約時段的最後一次時間 (自 Unix 紀元開始算起的秒數)。這個欄位會覆寫任何服務層級的取消規則。(選填)

BatchDeleteGenericRecordsRequest

批次要求刪除指定動態饋給類型的記錄。

欄位
parent

string

資源名稱,格式如下:partners/{partner_id}/feeds/{feed_name}

records[]

GenericDeleteRecord

要刪除的記錄。單一 API 呼叫最多只能包含 1,000 筆記錄。

BatchPushGenericRecordRequest

批次要求,用於插入和/或更新要求網址中指定的動態饋給類型記錄。

欄位
parent

string

資源名稱,格式如下:partners/{partner_id}/feeds/{feed_name}

records[]

GenericRecord

要插入和/或更新的記錄。單一 API 呼叫最多只能包含 1,000 筆記錄。

BatchReplaceServiceAvailabilityRequest

用來取代多個 Service 供應時段的批次要求。

欄位
parent

string

partners/{partner_id} 的格式。

extended_service_availability[]

ExtendedServiceAvailability

用來取代現有供應時段的擴展服務供應情形。

BatchReplaceServiceAvailabilityResponse

用來取代多個 Service 供應時段的批次回應。只有已成功更新的時段會納入此訊息

欄位
extended_service_availability[]

ExtendedServiceAvailability

成功更新的擴展服務供應情形訊息,用於取代現有的供應時段。

預訂

針對某個庫存清單時段的預訂

欄位
name

string

預訂的資源名稱:partners/{partner ID}/bookings/{booking ID}

merchant_id

string

該時段的商家 ID

service_id

string

商家服務的 ID

start_time

Timestamp

預約時段的開始時間

duration

Duration

預約時段的時間長度。

client_information

ClientInformation

進行預約的客戶個人資訊

status

BookingStatus

預訂狀態

payment_information

PaymentInformation

與預訂相關的付款交易資訊。

party_size

int64

預訂人數

BookingFailure

以非同步方式指出預訂處理失敗原因的狀態資料。BookingFailure 主要是用來擷取商業邏輯錯誤。

欄位
cause

Cause

預訂失敗的原因。(必填)

rejected_card_type

CreditCardType

(只有在原因為 PAYMENT_ERROR_CARD_TYPE_REJECTED 時才需要提供此項目)

description

string

(選用欄位) 可供合作夥伴納入其他資訊,但僅限偵錯用途。(選填)

payment_failure

PaymentFailureInformation

付款失敗相關資訊。

原因

列舉失敗原因。

列舉
CAUSE_UNSPECIFIED 預設值:不使用;表示「不明錯誤」
SLOT_UNAVAILABLE 參照的供應時段已不提供預訂。
SLOT_ALREADY_BOOKED_BY_USER 使用者已經預訂參照的供應時段。
LEASE_EXPIRED 保留項目 (如適用) 已過期,無法再用於完成要求的預訂。
OUTSIDE_CANCELLATION_WINDOW 基於商家取消政策中設定的時間限制,目前無法執行要求的取消作業。
PAYMENT_ERROR_CARD_TYPE_REJECTED 處理付款時發生錯誤,因為商家不接受使用者提供的信用卡類型。信用卡類型必須以 rejected_card_type 提供。
PAYMENT_ERROR_CARD_DECLINED 處理付款時發生錯誤,因為使用者提供的信用卡遭拒。
PAYMENT_OPTION_NOT_VALID 用來支付預訂費用的套裝/會員方案發生錯誤。可能的情況包括已無有效的剩餘可用額度或已經過期等等。
PAYMENT_ERROR 處理這筆預訂的付款時發生錯誤。此值代表一般付款相關錯誤;只有在錯誤與上述具體錯誤皆不相符的情況下,才可使用。
USER_CANNOT_USE_PAYMENT_OPTION 使用者無法使用指定的付款方式 (例如使用者試圖二度使用首次預訂價格)。
BOOKING_ALREADY_CANCELLED 使用者嘗試取消的預訂已取消。
BOOKING_NOT_CANCELLABLE 使用者嘗試取消的預訂無法取消。
OVERLAPPING_RESERVATION 使用者目前已有的預訂項目時間太接近這個時間。
USER_OVER_BOOKING_LIMIT 由於超過集結網站的單一使用者預訂限制,因此預訂失敗。
PAYMENT_REQUIRES_3DS1

在以下情況時設定此項目:您要求再次嘗試交易,但由於這次是在經過 3DS1 驗證/回應之後,因此付款遭拒。請注意,目前交易的失敗狀態會維持失敗。重試是完全獨立的作業。

如果這是失敗原因,「必須」設定 payment_failure.3DS1_parameters。如未設定,則目前的原因就會視為 PAYMENT_ERROR。

PaymentFailureInformation

付款失敗相關資訊。

欄位
threeds1_parameters

ThreeDS1Parameters

「透過 Google 預訂」集結網站使用的參數,用來為使用者初始化 3DS1 驗證通訊協定。除非 BookingFailure.cause 設為 PAYMENT_REQUIRES_3DS1,否則系統會忽略此值。

ThreeDS1Parameters

要求「透過 Google 預訂」執行 3DS1 驗證的參數。

這些參數是由 EMVCo 的 3DS1 通訊協定說明設定。

欄位
acs_url

string

表單來源網址,用來載入表單供使用者進行驗證。

pa_req

string

PaymentAuthentication 要求。請貼在 ACSUrl 表單 (如有提供)。

transaction_id

string

ACS 供應商使用的 ID。請貼在 ACSUrl 表單 (如有提供)。

md_merchant_data

string

業務資料。請貼在 ACSUrl 表單 (如有提供)。

BookingStatus

預訂狀態

列舉
BOOKING_STATUS_UNSPECIFIED 未指定。
CONFIRMED 預訂已確認
PENDING_MERCHANT_CONFIRMATION 預訂正在等待商家確認,確認後才能轉換至「已確認」狀態 (目前「不」支援這個項目)
PENDING_CLIENT_CONFIRMATION 預訂正在等待客戶確認,確認後才能轉換至「已確認」狀態 (目前「不」支援這個項目)
CANCELED 已代表使用者取消預訂。
NO_SHOW 客戶未依預約時間到場
NO_SHOW_PENALIZED 客戶未依預約時間到場,違反取消政策規定。
FAILED 處理失敗,無法完成預訂。
DECLINED_BY_MERCHANT 商家以非同步方式拒絕了預訂。

CallMerchant

請在 UnsupportedPartySizeOption 中使用空白訊息。如果設定這個選項,系統就會顯示選項,讓使用者致電商家預訂。

CancellationPolicy

服務的取消政策。

欄位
refund_condition[]

RefundCondition

適用於該政策的零或多項退款條件。

RefundCondition

定義單一退款條件。您可以同時採用多項退款條件,按照服務開始時間前的不同階段來說明「退款步驟」。

欄位
min_duration_before_start_time

Duration

在開始時間之前的期間,直到客戶可收到服務費用的部分退款 (比例依 refund_percent 中指定的值) 為止。如果設為 0 (預設值),代表可隨時取消服務。

refund_percent

uint32

可退款的百分比 (但最晚要在服務開始時間的前 min_duration_before_start_time 取消服務預訂),範圍在 [0, 100] 之間。如果設為 0 (預設值),代表服務無法退款;如果設為 100,這項服務可全額退款。

ClientInformation

預訂者的相關個人資訊

欄位
given_name

string

客戶的名字

family_name

string

客戶的姓氏

address

PostalAddress

客戶地址

telephone

string

客戶的電話號碼

email

string

客戶的電子郵件地址

CreateMerchantRequest

建立 Merchant 的要求。

欄位
parent

string

擁有此商家的合作夥伴父項資源名稱,格式為 partners/{partner_id}

merchant_id

string

要用於此商家的商家 ID。

merchant

Merchant

要建立的商家。

CreateServiceRequest

建立新 Service 的要求。

欄位
parent

string

擁有這項服務的商家父項資源名稱,格式為 partners/{partner_id}/merchants/{merchant_id}

service_id

string

要用於這項服務的服務 ID。

service

Service

要建立的服務。

CreditCardRestrictions

針對這個商家接受的信用卡類型的相關限制。

欄位
credit_card_type[]

CreditCardType

受支援信用卡的清單。如果留空,表示不支援任何信用卡。

CreditCardType

信用卡的類型。

列舉
CREDIT_CARD_TYPE_UNSPECIFIED 未使用。
VISA Visa 信用卡。
MASTERCARD Mastercard 信用卡。
AMERICAN_EXPRESS 美國運通卡。
DISCOVER Discover 信用卡。
JCB JCB 信用卡。

DeleteMerchantRequest

刪除 Merchant 的要求。

欄位
name

string

要刪除的商家的資源名稱。格式為:partners/{partner_id}/merchants/{merchant_id}

DeleteServiceRequest

刪除 Service 的要求。

欄位
name

string

要刪除的服務的資源名稱。格式:partners/{partner_id}/merchants/{merchant_id}/services/{service_id}

存款

使用者可能會被收取的訂金,或是使用者信用卡暫時被凍結的押金額度。

欄位
deposit

Price

存款金額。

min_advance_cancellation_sec

int64

提前取消最低存款金額。

deposit_type

PriceType

定義如何根據供應情形決定存款方式。

DirectMerchantPayment

說明使用者如何直接向商家付款,而非透過 RwG 預付服務。

欄位
payment_methods[]

Text

建議使用者只透過下列付款方式付款。

DurationRange

一段時間的包裝函式,可設定上限或無界限。至少須提供 min_duration 和 max_duration 的時間長度。

欄位
min_duration

Duration

時間長度下限。

max_duration

Duration

時間長度上限。

ExtendedServiceAvailability

供應情形和適用對象/時機清單。

欄位
merchant_id

string

這是必填欄位,用來指定下列供應情形訊息所屬的商家。

service_id

string

這是必填欄位,用於指定下列可用性訊息所屬的服務。

start_time_restrict

Timestamp

如有提供,我們會將實體提供的供應情形視為於 [start_time_restrict, end_time_restrict] 擷取的完整快照。也就是說,如果以下條件皆成立,則所有現有的供應情形資料都將會刪除:

   start_time_restrict <= availability.start_sec &&
   availability.start_sec < end_time_restrict

如果設定了 duration 訊息,則條件會進一步受到限制:

  availability.duration == duration_restrict

如果設定了 resources_restrict 訊息,則條件會進一步受到限制:

   availability.resources.staff_id == resources_restrict.staff_id &&
   availability.resources.room_id == resources_restrict.room_id

這些欄位通常用來提供指定時間範圍內的供應情形完整更新。

如果設定 start_time_restrict 而不設定 end_time_restrict,系統會解讀為一律從 start_time_restrict 開始。

end_time_restrict

Timestamp

如果設定 end_time_restrict 而不設定 start_time_restrict,系統會解讀為一律到 end_time_restrict 為止。

duration_restrict

Duration

設定 duration 會進一步將更新範圍限制在相符期間內的供應情形。

resources_restrict

Resources

設定 resources_restrict 會進一步將更新範圍限制在這組資源。資源的所有 ID 欄位都必須完全相符。

availability[]

Availability

新的供應情形清單。

FeedStatistics

處理已上傳動態饋給時取得的統計資料。

欄位
new_items

int64

這個動態饋給最近新增的項目。項目可以是商家、服務或供應時段,視動態饋給的類型而定。

existing_items

int64

現有項目,必要時可透過動態饋給提供的較新資訊加以更新。

deleted_items

int64

已經不存在於這個動態饋給中,因此已遭移除的項目。

FeedStatus

集結網站平台上傳的動態饋給的狀態。

欄位
name

string

動態饋給的資源名稱,格式為

  • partners/{partner_id}/feeds/merchants/{file_name}
  • partners/{partner_id}/feeds/services/{file_name}
  • partners/{partner_id}/feeds/availability/{file_name}
state

State

這個動態饋給的處理狀態。

error_details

string

人類可讀的字串,可在系統無法處理這個動態饋給時提供更多詳細資料。

statistics

FeedStatistics

這個動態饋給的相關統計資料。

以列舉方式表示動態饋給處理狀態。

列舉
STATE_UNSPECIFIED 預設值。未使用。
IN_PROGRESS 系統仍在處理動態饋給。
SUCCESS 動態饋給已成功處理完畢。
FAILURE 處理動態饋給時發生錯誤。

FoodOrderingMetadata

訂餐動作連結的中繼資料。

欄位
fee_details[]

FeeDetails

向使用者收取的費用詳細資料,以項目總額為準。針對不同類型的費用 (例如服務費和運費等) 重複上述步驟。

advance_order_details

AdvanceOrderDetails

進階訂購支援服務的詳細資料 (又稱為「提前訂購」頁面) 可讓使用者稍後再下單索取。

聯集欄位 fulfillment_duration_options。訂單確認後的訂單出貨時間。外送訂單的處理時間,是指商品送達所需的時間。自取訂單來說,你必須長時間才能取餐。fulfillment_duration_options 只能是下列其中一項:
fulfillment_lead_time_duration

Duration

固定時間長度。例如:30 分鐘。

fulfillment_lead_time_duration_range

DurationRange

時間長度範圍。範例:* 30 分鐘至 45 分鐘 * 超過 30 分鐘 * 不到 50 分鐘

AdvanceOrderDetails

預訂支援。

欄位
is_supported

bool

如果支援「提前訂單」,又稱為「預先訂購」則為 True。(必填)

FeeDetails

費用詳細資料。

欄位
type

FeeType

費用類型。(必填)

fee_amount

FeeAmount

費用金額 (以單位幣別、購物車價值的百分比表示,或兩者併用)。(必填)

FeeAmount

FeeAmount 示例:* 固定費用:$0 (免費)、$1.5 * 固定費用範圍:$1.0 美元 (最低)、$3.0 美元 (上限)、$5.0-6.0 美元 * 購物車大小百分比:15.5%、10%-20%、10% (最小)、15% (上限) * 2 5 和百分比$2.5 美元 (最低)、25.5%$4.5 美元 (上限)、10% &1.5 到 2.5 美元、10.5%-20%,2.5 - 3.5 美元

欄位
cart_percentage

QuantitativeValue

依購物車價值百分比計算的手續費。支援範圍 (有限制和不受限) 或固定百分比。值應介於 0 到 100 之間。示例:* 修正 5.5% * 至少 5.5% * 最多 5.5% * 4.5% 到 5.5%

聯集欄位 amount_options。指定金額的選項。amount_options 只能是下列其中一項:
amount

Money

固定金額。例如 $3.5 美元。

amount_range

MoneyRange

金額範圍。示例:* 3.5 至 5.5 美元 * 至少 $3.5 美元 * 最多 $5.5 美元

amount_unknown

bool

金額不明。

FeeType

費用類型。

列舉
FEE_TYPE_UNSPECIFIED 未指定費用類型。
DELIVERY 運費。
SERVICE 服務費。

FulfillmentOption

訂單線上動作連結的出貨選項。

欄位
fulfillment_type

FulfillmentType

必要欄位。執行要求類型。

available_day[]

AvailableDay

必要欄位。提供這種出貨方法可預約的日期清單 (建議至少提供 2 天)。

fee_details

FeeDetails

必要欄位。出貨方法的費用詳細資料。

minimum_order

Price

必要欄位。與動作連結相關聯的執行要求方法的最低訂單要求。

AvailableDay

可用日期層級。

欄位
fulfillment_date

Date

必要欄位。適用於執行要求方法的日期。假定為商家所在的時區。

last_ordering_time

Timestamp

必要欄位。Unix 時間戳記。使用者上次可以訂購及收到商品的時間:fulfillment_date。換句話說,last_ordering_time 之後的 fulfillment_date 不會再顯示為可用。

舉例來說,如果 fulfillment_date 為 2020-08-10: - last_ordering_time 值為 2020-08-10 18:00,表示消費者必須在 2020 年 8 月 10 日下午 6 點前完成訂購。- 如果 last_ordering_time 值為 2020-08-08 20:00,代表使用者必須在 2020 年 8 月 10 日晚上 8 點前完成訂購。

FeeDetails

與動作連結相關聯的執行要求方法費用詳細資料。

欄位
聯集欄位 fee_details。執行要求方法的費用模型。fee_details 只能是下列其中一項:
no_fee

NoFee

執行要求方法不收取任何費用。

base_fee

MinimumFee

與執行要求方法相關聯的基本費用。

fixed_fee

FixedFee

與出貨方法相關聯的固定費用。

FixedFee

與動作連結相關聯的執行要求方法所需固定費用。

欄位
amount

Price

必要欄位。執行要求方法的固定費用金額。

FulfillmentType

與動作連結相關聯的執行要求類型。

列舉
FULFILLMENT_TYPE_UNSPECIFIED 未指定執行要求類型。
FULFILLMENT_TYPE_DELIVERY 出貨類型是「出貨」。
FULFILLMENT_TYPE_PICKUP 出貨類型為自取。

MinimumFee

與動作連結相關聯的執行要求方法要求的最低費用。

欄位
base_fee_amount

Price

必要欄位。執行要求方法的基本費用金額。

NoFee

與動作連結相關聯的執行方式方法不會產生費用。

GenericDeleteRecord

要刪除網址要求中提及的動態饋給類型的記錄。

欄位
delete_time

Timestamp

必要欄位。系統會利用這個時間戳記判斷刪除資產的刪除順序。

聯集欄位 record_type。封裝不同類型的動態饋給 (例如 ndjson、proto 等)合作夥伴可以提供完整記錄,就像在動態饋給或 BatchPush API 中提供記錄的方式。合作夥伴也可以選擇只填入識別記錄所需的重要欄位。record_type 只能是下列其中一項:
data_record

bytes

適用於非原型設計動態饋給。

proto_record

Any

適用於 proto 型動態饋給。

GenericRecord

網址要求中提及的動態饋給類型記錄。

欄位
generation_timestamp

Timestamp

必要欄位。這個時間戳記是用來確保商品目錄更新的正確順序。

聯集欄位 record_type。封裝不同類型的動態饋給 (例如 ndjson、proto 等)record_type 只能是下列其中一項:
data_record

bytes

適用於非原型設計動態饋給。

proto_record

Any

適用於 proto 型動態饋給。

GeoCoordinates

特定位置的地理資訊,包括經緯度和地址。

欄位
latitude

double

緯度度數。(選填)

longitude

double

經度度數。(選填)

聯集欄位 addresses。某位置的地址,可以是結構化或非結構化資料。addresses 只能是下列其中一項:
address

PostalAddress

位置的郵寄地址 (建議使用)。

unstructured_address

string

您也可以提供非結構化的地址備用。例如:「1600 amphitheatre parkway Mountain View, ca 94043, USA」

GetMerchantStatusRequest

取得 MerchantStatus 的要求

欄位
name

string

必要欄位。資源名稱,格式如下:partners/{partner_id}/merchants/{merchant_id}/status。

GetStatusRequest

要求擷取由集結網站平台上傳的特定動態饋給的 Status

欄位
name

string

動態饋給的資源名稱,格式為

  • partners/{partner_id}/feeds/merchants/{file_name}
  • partners/{partner_id}/feeds/services/{file_name}
  • partners/{partner_id}/feeds/availability/{file_name}

HomeServiceData

必須為居家服務產業提供額外資訊。

欄位
category_type

string

這項住家服務所屬的概略類別。例如:水電工、電工等

job_type

string

指定居家服務所屬類別下的工作類型。例如:unclog_drain、install_faucet 是「水電工」類別下的工作類型。

IntegrationType

支援的整合深度。

列舉
INTEGRATION_TYPE_UNSPECIFIED 預設為 END_TO_END。
INTEGRATION_TYPE_END_TO_END 完全整合,允許透過 Google 進行端對端預訂。
INTEGRATION_TYPE_INVENTORY_ONLY 預訂伺服器不需要支援這項服務。只需要傳送商家、服務和 (選用的) 供應情形資料。

InvalidateResourceRequest

要求撤銷資源。

欄位
resource_id

string

要撤銷的資源名稱。

舉例來說,取貨資源的名稱應採用 partners/{partner_id}/pickups/{pickup_id} 格式。實作項目「必須」移除所識別資源的快取版本。

LineItem

訂單中的單一項目 (單一時段中單一服務的預訂)。

欄位
service_id

string

商家服務的 ID。

start_sec

int64

預約時段的開始時間 (採用世界標準時間,自 Unix Epoch 紀元時間起算,以秒為單位)。

duration_sec

int64

預約時段的時間長度 (以秒為單位)。

tickets[]

OrderedTickets

按票券類型訂購的票券數量。

price

Price

這個明細項目的總價 (不含稅金)。

status

BookingStatus

委刊項狀態。

OrderedTickets

已訂購的票券數量 (按票券類型)。

欄位
ticket_id

string

票券類型的 ID。

count

int32

這個類型的訂購票券數量。

ListMerchantStatusesRequest

取得 MerchantStatus 清單的要求

欄位
parent

string

必要欄位。擁有這個商家狀態集合的父項。格式:partners/{partner_id}/merchants

page_size

int32

必要欄位。傳回的項目數量上限。請注意,伺服器可能會縮減網頁大小。

page_token

string

選用設定。先前的 ListMerchantStatusResponse 傳回的 nextPageToken 值 (如果有的話)。

booking_inventory_status_restrict

BookingInventoryStatus

選用設定。選用限制,可根據預訂廣告空間狀態篩選結果。

waitlist_inventory_status_restrict

WaitlistInventoryStatus

選用設定。選用的限制:按照等候名單庫存狀態篩選結果。

geo_match_restrict

GeoMatchingStatus

選用設定。選用的限制,可根據地理區域比對狀態篩選結果。

BookingInventoryStatus

端對端預訂廣告空間狀態。

列舉
BOOKING_INVENTORY_STATUS_UNSPECIFIED 不指定。
NO_VALID_FUTURE_INVENTORY 商家在未來 30 天內沒有預訂商品目錄。
HAS_VALID_FUTURE_INVENTORY 商家在未來 30 天內有預訂庫存。

GeoMatchingStatus

商家地理區域比對狀態。

列舉
GEO_MATCHING_STATUS_UNSPECIFIED 不指定。
GEO_UNMATCHED 商家不符合地理區域比對。
GEO_MATCHED 商家符合地理區域比對。

WaitlistInventoryStatus

端對端候位名單庫存狀態。

列舉
WAITLIST_INVENTORY_STATUS_UNSPECIFIED 不指定。
NO_VALID_WAITLIST_SERVICE 商家不提供支援候位名單的服務。
HAS_VALID_WAITLIST_SERVICE 商家有支援候位名單的服務。

ListMerchantStatusesResponse

列出 MerchantStatus 的回應。

欄位
merchant_statuses[]

MerchantStatus

符合篩選條件的商家狀態清單。

next_page_token

string

用於擷取下一頁結果的符記。如果空白,清單中沒有其他結果。

ListStatusRequest

要求擷取由集結網站平台上傳的多個動態饋給的 Status

欄位
name

string

動態饋給的資源名稱,格式為

  • partners/{partner_id}/feeds/merchants
  • partners/{partner_id}/feeds/services
  • partners/{partner_id}/feeds/availability
page_size

int32

傳回的項目數量上限。

page_token

string

先前的 List 要求 (如果有的話) 傳回的 next_page_token 值。

state_restrict

State

選用限制,按動態饋給狀態篩選結果。

time_range_restrict

TimeRange

選用的限制,可根據上限和下限篩選結果。如果未設定 start_time,則預設為 unix 時間的開端。如未設定 end_time,則預設為現在。

ListStatusResponse

要求擷取由集結網站平台上傳的多個動態饋給的 Status

欄位
status[]

FeedStatus

已上傳的動態饋給狀態清單,依時間前後反向排序。傳回項目的數量上限取決於要求中的 page_size 欄位。

next_page_token

string

用於擷取下一頁結果的符記。如果空白,清單中沒有其他結果。

LocalizedString

單一語言代碼字串的例項。

欄位
locale

string

IETF BCP 47 語言代碼,例如「en」、「mas」、「zh-Hant」、「de-CH-1901」。請參閱 http://www.w3.org/International/articles/language-tags/

value

string

上述語言代碼的訊息 (UTF-8)。

位置

特定位置的地理資訊。

欄位
place_id

string

Google 地方資訊資料庫和 Google 地圖上特定地點的地點 ID。請參閱 https://developers.google.com/places/web-service/place-id,進一步瞭解地點 ID。如果提供這項資訊,Google 就會將該位置與這個地點進行比對。

name

string

我們會使用位置名稱、電話、網址和地理區域來支援特定位置與 Google 地圖上現有的地點。

這是選填欄位,但在某些情況下可能需要填寫。舉例來說,沒有名稱的 Service.location 將不會與企業實體進行比對,即使這些企業實體位於相同的地址也一樣。(選填)

telephone

string

位置的公開電話號碼 (包含其所在國家/地區代碼),例如 +14567891234。(選填)

url

string

位置的公開網站網址。(選填)

geo

GeoCoordinates

位置的地理資訊,包括經緯度和地址。(選填)

location_type

LocationType

位置的類型;如果已針對「服務」提供位置,就必須提供該位置。

location_id

string

服務中該位置的專屬參照。此 ID 可用來在其他服務欄位中參照這個位置。例如:在自訂登記表單中,您可以使用一組位置 ID 來指定取貨地點選項。如果設定這個項目,同一服務中不得出現重複的 ID。(選填)

LocationType

這個位置的類型。

列舉
LOCATION_TYPE_UNSPECIFIED 未指定位置類型。
VISITED_LOCATION 這項服務造訪的地點。
START_LOCATION 這項服務開始進行的地點,也可做為 MEETING_LOCATION。
END_LOCATION 這項服務結束時的所在地點。

Merchant

集結網站平台上的商家相關資訊。

欄位
name

string

商家資源名稱,格式為 partners/{partner_id}/merchants/{merchant_id}

merchant_name

string

系統會利用 merchant_name、電話、網址和地理區域來合作夥伴庫存清單與 Google 地圖上現有的商家進行比對。這項資訊不會顯示。

此為商家名稱。

telephone

string

商家的公開電話號碼 (包括其國家/地區和區碼),例如+14567891234。

url

string

商家公開網站的網址。

geo

GeoCoordinates

商家的地理位置資訊,包括經緯度和地址。

category

string

集結網站平台中的商家類別。

num_bookings_30d
(deprecated)

int64

這個欄位現已淘汰。

tax_rate_basis_points
(deprecated)

uint32

商家的稅率,以基準點 (一個百分點的百分之一) 表示。舉例來說,如果稅率是 7.5%,這個欄位應設為 750。

如果這個欄位未設定或設為 0,則此商家就其提供的任何服務向使用者收取的總價格就是 Service.price 指定的實際價格。系統會假設服務價格為免稅或已包含適用稅金。系統不會在獨立的明細項目中向使用者顯示稅金。

如果將這個欄位設定為任何非零值,則此商家就其提供的任何服務向使用者收取的總價格,將包含服務價格加上以此處提供的稅率計算的稅金。最小貨幣單位的小數 (例如 1 美分後面的小數) 會採用銀行家捨入法。系統會在獨立的明細項目中向使用者顯示稅金。

這個欄位已淘汰,請改用 tax_rate。

tax_rate

TaxRate

商家的稅率。如有這個欄位,其內容會覆寫已淘汰的 tax_rate_basis_points 欄位。空白訊息 (即 tax_rate { }) 會將套用的稅率重設為零。

payment_restrictions

PaymentRestrictions

針對這個商家接受的付款方式的相關限制。如果未設定這個欄位,系統會假設沒有任何限制。

payment_option[]

PaymentOption

此為這個商家提供的付款方式;這個商家底下的服務可以個別限制其允許的付款方式。

payment_processor_config
(deprecated)

PaymentProcessorConfig

提供代碼化技術的付款處理方的設定 (如果商家能夠支援的話)。

tokenization_config

TokenizationConfig

提供代碼化技術的付款處理方的設定 (如果商家能夠支援的話)。

terms

Terms

如果使用者是「透過 Google 預訂」功能來預訂服務,則系統會向其顯示這項相關商家的《條款及細則》。除了上述這些集結網站合作夥伴的條款及細則之外,一律不得向使用者顯示。

brand_id

string

此為用來識別消費性品牌的隱晦字串,在顯示合作夥伴屬性時使用。這個欄位可讓擁有多個消費性品牌的合作夥伴,在同一份動態饋給內為所有品牌提供商家。

品牌是由多個向消費者顯示的元素 (例如名稱、標誌、服務條款和隱私權政策) 組成。

如果只有一個消費性合作夥伴品牌,就不需要設定這個欄位,可予以忽略。

請根據合作夥伴的情況決定:

合作夥伴沒有多個消費性品牌。--> 忽略此欄位

合作夥伴已設定多個品牌。

  If this field is set
    --> Associated consumer-facing brand attribution is used

  If this field is unset or the empty string
    --> Default consumer-facing brand attribution is used

注意事項:大多數合作夥伴都不需要設定這個欄位。如果合作夥伴想要使用這個欄位,請務必先聯絡我們設定個別品牌 (包括預設品牌)。

matching_hints

MerchantMatchingHints

協助 Google 比對商家與地圖上現有地點的提示。注意:大多數合作夥伴都不需要設定這個欄位,因為 Google 會使用上述欄位中提供的資訊來比對商家和 Google 地圖上的地點。(選填)

service_attribute[]

ServiceAttribute

任何服務屬性的定義,用於描述此商家提供的服務。(選填)

waitlist_advisement

Advisement

選用設定。特定商家針對透過「透過 Google 預訂」加入等候名單的使用者提供的一般建議。建議中的個別文字欄位長度上限為 100 個位元組。

MerchantMatchingHints

協助 Google 比對商家與地圖上現有地點的提示。

欄位
place_id

string

Google 地方資訊資料庫和 Google 地圖上特定地點的地點 ID。請參閱 https://developers.google.com/places/web-service/place-id,進一步瞭解地點 ID。

MerchantStatus

「透過 Google 預訂」平台中的商家狀態。

欄位
name

string

商家狀態資源名稱,格式為 partners/{partner_id}/merchants/{merchant_id}/status

merchant_name

string

合作夥伴提供的商家名稱。

input_geo_info

GeoCoordinates

合作夥伴提供商家的地理資訊。

processing_status

ProcessingStatus

商家處理狀態。

booking_status

BookingStatus

與端對端預訂整合相關的狀態。

waitlist_status

WaitlistStatus

與等候名單整合相關的狀態。

geo_match

PlaceInfo

這個商家的地理位置相符。如果商家與地理區域不相符,則為空白。

local_services_match

LocalServicesMatchInfo

在地生活服務廣告與這個商家的比對相符。如果此商家不是當地服務商家,或是與任何供應商不相符,則為空白。

direct_urls[]

DirectUrl

網址清單,用於呈現目前商家商品目錄的內容。請注意,這不代表系統確實放送廣告空間,且網址可能與公開顯示的網址不同。

BookingStatus

與端對端預訂整合相關的狀態。

欄位
has_valid_future_inventory

bool

如果商家在未來 30 天內有商品目錄,則為「是」。並不保證商家實際送達。

DirectUrl

顯示商家的網址。

欄位
type

UrlType

這個網址的類型。

url

string

可能會顯示此商家的網址。

UrlType

顯示網址的類型。

列舉
URL_TYPE_UNSPECIFIED 不指定。
BOOKING 端對端預訂網址。
WAITLIST 端對端等候名單網址。
LOCAL_SERVICES Google 在地生活服務網址。

LocalServicesMatchInfo

Google 在地生活服務資訊相符 (僅適用於在地生活服務商家)。

欄位
matched_providers[]

MatchedProvider

相符的服務供應商。單一商家可與多家服務供應商配對。

MatchedProvider

在地生活服務供應商。

欄位
customer_id

int64

Google 在地生活服務外部客戶 ID。

categories[]

string

在地生活服務類別 (產業)。例如:「水電工」和「carpet_cleaning」

PlaceInfo

相符地點的資訊。

欄位
name

string

地點名稱。

formatted_address

string

已格式化的當地語言地址。

place_id

string

這個地點的 Google 地點 ID。可用於建構 Google 地圖網址,或擷取地點的其他詳細資料。如需用法範例,請參閱 https://developers.google.com/places/web-service/place-id

ProcessingStatus

商家處理狀態。

列舉
PROCESSING_STATUS_UNSPECIFIED 未指定狀態。
IN_PROGRESS 雖然已交給小麥的商家,但系統仍在處理中。處於這個狀態的商家不會填入其他狀態。
COMPLETED 已計算出商家的其他狀態。

WaitlistStatus

與等候名單整合相關的狀態。

欄位
has_valid_waitlist_service

bool

如果商家提供等候名單服務,則為「是」。並不保證商家實際送達。

MoneyRange

金額範圍可以設定上限或無限制的包裝函式。至少須指定 min_amount 和 max_amount 其中一個。

欄位
min_amount

Money

最低金額。

max_amount

Money

最高金額。

NoShowFee

使用者預訂後未到場的話,可能需要支付的費用。

欄位
fee

Price

未到場使用預訂服務的使用者可能需要支付的金額。

fee_type

PriceType

定義如何根據供應情形決定費用。

訂單

向商家預約服務的訂單。

欄位
name

string

訂單的資源名稱:partners/{partner ID}/orders/{order ID}

client_information

ClientInformation

下訂單客戶的個人資訊。

payment_information

PaymentInformation

與訂單相關的付款交易資訊。

merchant_id

string

此訂單中所有服務所屬商家的 ID。

item[]

LineItem

這個訂單中的委刊項。

OrderOnlineMetadata

訂單線上動作連結的中繼資料。

欄位
fulfillment_option[]

FulfillmentOption

訂單線上動作連結的出貨選項。

PaymentInformation

與預訂相關的付款詳情

欄位
prepayment_status

PrepaymentStatus

預訂的預付狀態。如果 prepayment_status 是 PREPAYMENT_PROVIDED 或 PREPAYMENT_REFUNDED,則 payments_transaction_id 包含相關聯的專屬交易 ID。

payment_transaction_id

string

與預訂相關聯的唯一付款交易 ID。不適用時則為空白。

PaymentOption

用來支付商家服務費用的付款方式。付款方式可由多個商家共用 (例如隸屬於同一家連鎖企業的多個商家)。

欄位
payment_option_id

string

此 ID 用來識別這個付款方式。

在整個集結網站中通用。您可以針對多個商家重複使用同一個 ID 值,讓消費者以相同的付款方式向這些商家付費。

如果針對多個商家重複使用同一個 ID,則只要為其中一個商家更新付款方式的任何值,其他商家中所有使用相同 ID 的付款方式就會一併更新。因此,最佳做法是讓所有付款方式共用相同的 ID,並一律更新為相同的值,以避免發生任何非決定性的行為。

name

string

此為付款方式名稱,其他人可以看到這項資訊。

description

string

此為付款方式相關說明,其他人可以看到這項資訊。

price

Price

付款方式的價格。

tax_rate

TaxRate

此為這個付款方式的稅率。如果使用這個欄位,其內容會覆寫「商家」或「服務」中的 tax_rate 欄位。空白訊息 (即 tax_rate { }) 會將套用的稅率重設為零。

payment_option_type

PaymentOptionType

此為這個付款方式的類型。限用一次、可多次使用 (組合包),以及不限次數的會員。

session_count

int64

用來指定這個付款方式可用於幾個工作階段。僅適用於多重工作階段 / 資產包,其值應為 >1.

purchase_interval

TimeRange

可在這個期間內購買付款方式。

valid_interval

TimeRange

付款方式可在這個期間內 (例如 2017 年 1 月份限定優惠價) 使用。如果有出現,則會覆寫 valid_duration 和 activate_type。

valid_duration

Duration

此為付款方式的有效期間 (例如 30 天會員效期)。

activation_type

ActivationType

用來定義如何判定這個付款方式的開始生效日期。

user_restriction

UserPurchaseRestriction

用來限定哪些消費者有資格用此付款方式購物,可限制只向部分消費者顯示含促銷優惠的付款方式。如未設定,則所有的使用者都符合資格。

ActivationType

用來定義如何判定開始生效日期。

列舉
ACTIVATION_TYPE_UNSPECIFIED 未使用。
ACTIVATION_ON_PURCHASE 有效期自購買時開始算起。
ACTIVATION_ON_FIRST_USE 有效期自首次使用該付款方式開始算起。

PaymentOptionType

此為付款方式類型。

列舉
PAYMENT_OPTION_TYPE_UNSPECIFIED 未使用。
PAYMENT_OPTION_SINGLE_USE 付款方式只能使用一次。
PAYMENT_OPTION_MULTI_USE 工作階段計數大於 0 時可用的付款方式。
PAYMENT_OPTION_UNLIMITED 可在有效時間範圍內使用的付款方式 (不適用工作階段計數)。

PaymentProcessorConfig

付款處理方的設定,可依個別商家分別設置。

欄位
processor

Processor

定義要套用這項設定的付款處理方合作夥伴。

public_key

string

這個金鑰用來識別採用此付款處理方服務的商家。

Stripe 相關說明請參閱:https://stripe.com/docs/dashboard#api-keys;Braintree 相關說明請參閱:https://articles.braintreepayments.com/control-panel/important-gateway-credentials

version

string

傳送給付款處理方的 API 版本號碼,以及付款要求。

處理器

定義特定付款處理方合作夥伴。

列舉
PROCESSOR_UNSPECIFIED 未使用
PROCESSOR_STRIPE 透過 Stripe 付款的相關設定。
PROCESSOR_BRAINTREE 透過 Braintree 付款的相關設定。

PaymentRestrictions

針對這個商家接受的付款方式的相關限制。

欄位
credit_card_restrictions

CreditCardRestrictions

針對這個商家接受的信用卡的相關限制。如未設定此欄位,系統會假設商家接受所有信用卡。請注意,CreditCardType 支援的卡片清單會隨時間增加。也就是說,如果留空,系統將為日後的變更套用設定。

PerOrderFee

每筆訂單必須支付一次的費用,不限票券張數。

欄位
delivery_fee

Price

費用可能因運送方式而異。

processing_fee

Price

處理使用者付款方式的費用。

PerTicketFee

使用者購買每張票需要支付的費用。

欄位
service_charge

Price

服務收取的額外費用。

facility_fee

Price

場地/設施的費用。

taxes

Price

每張票券稅金。

PostalAddress

客戶或商家的地址。

欄位
address_country

string

國家/地區,使用 ISO 3166-1 alpha-2 國家/地區代碼指定,例如「US」(必填)

address_locality

string

縣市,例如「台北市」。(必填)

address_region

string

區域,例如「CA」。只有在地址通常包含區域名稱的國家/地區,才需要使用這個欄位。(選填)

postal_code

string

郵遞區號,例如「94043」。(必填)

street_address

string

街道地址,例如「八德路二段 1 號」。(必填)

PrepaymentStatus

某次預訂的預付狀態。

列舉
PREPAYMENT_STATUS_UNSPECIFIED 未指定,預設為 PREPAYMENT_NOT_PROVIDED。
PREPAYMENT_PROVIDED 預訂費用已預先支付。
PREPAYMENT_NOT_PROVIDED 預訂費用尚未預先支付。
PREPAYMENT_REFUNDED 費用先前為 PREPAYMENT_PROVIDED,但現在已退還。

Price

服務或費用的價格。

欄位
price_micros

int64

價格以微貨幣單位表示。最小貨幣單位的小數部分將採用銀行家捨入法 (舉例來說,2.5 美分會四捨五入為 2 美分,3.5 美分會四捨五入為 4 美分,0.5 美分會四捨五入為 0 美分,2.51 美分則捨入為 3 美分)。

currency_code

string

ISO 4217 定義的價格幣別。

pricing_option_tag

string

選填且不透明的字串,用於識別與延伸價格相關聯的定價選項。

PriceInterpretation

說明如何向使用者呈現及顯示價格。

列舉
PRICE_INTERPRETATION_UNSPECIFIED 未指定價格呈現細項,預設為 EXACT_AMOUNT。
EXACT_AMOUNT

適用於必須以特定值顯示價格的情況。

範例:瑜珈課程每堂 $20 美元、兒童剪髮每次 $15 美元

STARTS_AT

適用於服務價格會變動,但可向消費者顯示已知最低價格的情況。消費者選擇的服務項目可能會高於顯示的價格。

請注意,凡是使用這個 PriceInterpretation 的服務都必須使用 PrepaymentType NOT_SUPPORTED。

範例:愛犬美容服務 $30 美元,但消費者可能會加購其他項目,因此總價會增加

NOT_DISPLAYED

適用於服務價格會變動,但系統不會預先向消費者顯示價格資訊的情況。

請注意,凡是使用這個 PriceInterpretation 的服務都必須使用 PrepaymentType NOT_SUPPORTED,而且「Price」部分必須空白。

範例:居家服務諮詢

PriceType

定義如何根據供應情形計算總價。

列舉
FIXED_RATE_DEFAULT

價格為固定金額。這是未設定此欄位時的預設值。

範例:訂位的訂金為 $50 美元、瑜珈課程的逾時未到費用為 $20 美元

PER_PERSON

指定的價格是以每人為單位,總價格則是根據「資源」中指定的預訂人數來計算,計算方式為 price_micros * party_size。供應情形資源中的 PER_PERSON 價格必須與預訂人數一併指定;如果未指定,則會以「一人」做為預訂人數。

範例:博物館門票為每人 $10 美元

QuantitativeValue

可以是範圍或固定值的數值包裝函式。QuantitativeValue 範例:* 單數值:value: 10.5 * 邊界範圍:value_range {min_value: 5.5, max_value 10.5} * 下限:value_range {min_value: 5.5} * 上限:value_range {max_value: 10.5}

欄位
聯集欄位 value_options。(必要) value_options 只能採用下列其中一種設定:
value

double

單一值。例如:5.6

value_range

RangeValue

也可能是開放式或受限的值範圍。範例:* 至少 5.5 * 最多 5.5 * 5.5 至 6.5

RangeValue

值範圍,例如 min_value <max_value。至少須有 min_valuemax_value 其中之一。

欄位
min_value

double

最小值。

max_value

double

最大值。

Rating

為某實體定義「評分」標準。

欄位
value

double

平均評分值 (number_of_ratings 大於 0 時必填)。這個值必須在 [1, 5] 的範圍內,只有在 number_of_ratings 為零的情況下可省略。

number_of_ratings

uint64

用於計算值的評分次數 (必填)。

RelatedMedia

與這項服務相關的相片。Google 會檢索這些媒體,確保其正確向使用者顯示。(選用)

欄位
url

string

這個媒體來源的網址。Google 會檢索透過這個網址代管的媒體。

type

MediaType

這個媒體來源的類型。

localized_caption

Text

支援 i18n 的媒體說明文字,僅支援純文字格式。系統會移除所有 HTML 元件。(選填)

attribution

Attribution

媒體來源的作者資訊。請注意,如果必須提供出處,註明拍攝該媒體的攝影師或拍攝機構,就必須設定這個欄位。(選填)

caption
(deprecated)

string

已淘汰,建議使用 localized_caption。

Attribution

這個媒體的作者資訊。

欄位
localized_text

Text

註明媒體出處 (例如攝影師或拍攝機構名稱) 的文字,支援 i18n。這段文字會與來源媒體一起顯示。請注意,這個欄位只支援純文字,所有 HTML 元件都會被移除 (不支援以超連結為基礎的作者資訊)。

text
(deprecated)

string

已淘汰,建議使用 localized_text。

MediaType

以列舉方式指出這個媒體來源的類型。僅支援相片。如果需要支援相片以外的媒體,請與「透過 Google 預訂」團隊聯絡。

列舉
TYPE_UNSPECIFIED 未使用。
PHOTO 指出該網址提供的媒體是一張相片。

ReplaceServiceAvailabilityRequest

要求取代特定 Service 的供應情形。

欄位
service_availability

ServiceAvailability

用於取代現有服務的服務供應情形。

RequireCreditCard

定義是否必須使用信用卡才能進行預約。

列舉
REQUIRE_CREDIT_CARD_UNSPECIFIED 未明確指定信用卡規定,其行為與針對「CONDITIONAL」指定的行為相同。
REQUIRE_CREDIT_CARD_CONDITIONAL 只要符合以下任一條件,Google 就會要求必須提供信用卡才能預訂:* 供應情形設有價格,且 prepayment_type 設為 REQUIRED * 已設定 no_show_fee * 已設定訂金欄位。
REQUIRE_CREDIT_CARD_ALWAYS 無論其他欄位值為何,都必須要有信用卡才能預訂此供應時段。

Resources

如果可預訂時段的服務中含括不同的員工或房間,可用「資源」來做明確的區隔。時間間隔相同且提供相同服務的多個時段只要包含不同的資源,就可以同時存在。

欄位
staff_id

string

選用欄位,可指明提供服務員工的 ID。這個欄位用來識別所有商家、服務和預訂情形記錄中所有的員工,此外,這項資訊必須保持穩定一段時間,才能與過往的預訂建立關聯。如果已提供 employee_name,則此欄位為必要。

staff_name

string

選用欄位,用來指明提供服務員工的名字。這個欄位會向預訂者顯示,且應為使用者可理解的格式,而非隱晦 ID。如果已提供 employee_id,則必須使用這個欄位。

room_id

string

(選用) 服務進行時所在的空間的 ID。這個欄位可用於在所有商家、服務和供應情形記錄中識別空間。此外,這項資訊必須保持穩定一段時間,才能與過往的預訂建立關聯。如果已提供 room_name,則此欄位為必要項目。

room_name

string

(選用) 服務進行時所在空間的名稱。這個欄位會向預訂者顯示,且應為使用者可理解的格式,而非隱晦 ID。(如有「room_id」,則此為必填屬性) 餐廳名稱只應用於座位區,例如酒吧或露台,不能用於固定價格菜單、特殊活動或任何其他非客房價值 (例如預訂或晚餐)。強烈建議將預設座椅休息區設成無關聯的房間。

party_size

int32

僅適用於「餐飲業」:在此時段可接待的用餐人數。一間餐廳可同時與多個時段建立關聯,每個時段則指定不同的 party_size,例如預訂可以容納 2 人、3 人或 4 人。

SchedulingRules

服務的排程規則。

欄位
min_advance_online_canceling

int64

線上取消預約的最晚提前告知時間 (以秒為單位)。(選填)

late_cancellation_fee
(deprecated)

Price

在最晚提前告知期限內取消服務的費用。

noshow_fee
(deprecated)

Price

在未取消的情況下逾時未到的費用。

admission_policy

AdmissionPolicy

適用於這項服務的入場政策。如未設定,預設值為 TIME_STRICT。(選填)

cancellation_policy

CancellationPolicy

排程規則取消政策。(「觀光景點」的必要條件)

聯集欄位 min_booking_buffer。從最後可預訂時間算起,到供應時段開始或結束為止的期間 (以秒為單位)。

如果設定了「min_advance_booking」,則最晚可預訂時間的計算方式為 (<時段開始時間> -「min_advance_booking」)。如果設定了「min_booking_buffer_before_end_time」,則最晚可預定時間的計算方式為 (<時段結束時間> -「min_booking_buffer_before_end_time」)。請注意,如要設定「min_booking_buffer_before_end_time」,該值必須為正數。如果兩者都未設定,則在該時段開始時間之前,該時段都可供預訂。如果同時設定這兩個欄位,系統只會挑選一個值,並忽略另一個值,因此我們無法確實預測選取的值。

範例:

  • 至少要在開始時間前 1 小時預訂的剪髮服務:「scheduling_rules{ min_advance_booking: 3600 ...}」

  • 最後購票時間為閉館前 30 分鐘的博物館:「scheduling_rules{ min_booking_buffer_before_end_time: 1800 ...}」

  • 必須在開始時間前購買的電影票券:「scheduling_rules{ ...}」(此欄位留空) (選用) min_booking_buffer 只能是下列其中一項:

min_advance_booking

int64

從最晚可預訂時間算起,到供應時段開始為止的期間 (以秒為單位)。

min_booking_buffer_before_end_time

int64

從最晚可預訂時間算起,到供應時段結束為止的期間 (以秒為單位)。如果設定這個欄位,「admission_policy」欄位必須設為 TIME_FLEXIBLE,表示使用者可以在該時段開始後使用購買的票券。

AdmissionPolicy

此服務的入場政策。

列舉
ADMISSION_POLICY_UNSPECIFIED 未使用。
TIME_STRICT 客戶必須在供應時段的開始時間到場,且服務預計會在該時段的結束時間結束。TIME_STRICT 用途範例:* 上午 9 點開始的導覽行程,要求所有參加者在開始時間抵達,預計於中午 12 點返回。* 預約週六下午 3 點剪髮,需時大約 30 分鐘。* 晚上 6 點到 8 點的健身課程。
TIME_FLEXIBLE

客戶只要在供應時段的開始與結束時間之間的任何時間點抵達,就能使用本次預訂的服務。

TIME_FLEXIBLE 用途範例:* 在購買日期的任何時段都能使用的博物館票券。* 遊樂園午後入場券,可用時段為中午 12 點到晚上 9 點。

TIMED_ENTRY_WITH_FLEXIBLE_DURATION

客戶必須在供應時段的開始時間抵達商家,但隨時可以離開。

以博物館入場門票為例,如果使用者持有的是上午 10 點入場的限時門票,就必須在早上 10 點抵達博物館。這項服務供應時段的開始時間代表指定的入場時間。結束時間則僅用來當做識別可供預訂的供應時段的索引鍵。

服務

商家所提供服務的相關資訊,例如剪髮

欄位
name

string

服務資源名稱,格式為 partners/{partner_id}/merchants/{merchant_id}/services/{service_id}

service_name

string

服務的名稱,例如「男性剪髮」。已淘汰,請改用 localized_service_name。

localized_service_name

Text

服務的名稱,例如「男性剪髮」。可能使用多個語言代碼。

description

string

向使用者顯示的服務說明。已淘汰,請改用 localized_description。

localized_description

Text

向使用者顯示的服務說明。

這個欄位支援純文字和類 HTML 兩種格式。與純文字部分不同的是,您可以使用標題、段落、清單和一些詞組標記來建立自訂版面配置。請仔細閱讀下列操作說明和注意事項,確保為使用者提供最佳使用體驗。

支援的類 HTML 格式標記:

標題標記:<h1>、<h2>、<h3>、<h4>、<h5>、<h6>
標題標記可用於顯示標題和子標題。以「<h1>行程</h1>」為例,內嵌在之間的文字就會顯示為該部分最醒目的標題。請注意,系統會忽略所有內部 HTML 標記、樣式或屬性。舉例來說,系統會將 <h1 style=".."> 視為與 <h1> 相同,只保留純文字。

段落標記:<p>
段落標記可用來強調詳細的介紹或內容。系統會忽略所有內部標記、樣式或屬性,但有幾個例外:<br>、<strong> 和 <em>。詳情請參閱下文的「詞組標記」部分。

清單標記:<ul>、<ol>、<li>
<ul> 標記搭配 <li> 標記可顯示未排序的清單,而 <ol> 標記搭配 <li> 使用則可顯示已排序清單。這是顯示檢查清單、時間表或任何其他相關用途清單的好方法。
範例:顯示遊輪行程的地圖項目清單:
<ol>
<li>壯麗的海景和野生動物遊玩機會。</li>
<li>精心設計的旅遊安排和服務。</li>
<li>保證最低價。</li>
</ol>
請注意,只有 <li><ul> 歲以下兒童或 <ol>代碼之間會經過轉換所有其他子項都將會捨棄。此外,系統會忽略所有內部標記、屬性和樣式,只保留純文字內容。

分區標記:<div>
針對 <div> 標記中所有支援的內部標記,系統都會根據上述規則進行剖析,這表示 <div> 標記本身不代表任何分組或縮排。此外,系統也會忽略所有內部屬性和樣式。

詞組標記:<br>、<strong>、<em>:
僅支援上述三種標記。<br> 可以用於在段落中斷行,而 <strong>/<em> 則可用來標明重要文字。系統會忽略其他所有詞組標記。

不支援的標記:

  • 禁止使用 <html>、<header> 和 <body> 標記。
  • 上文中未提及的標記將不予支援 (例如 <table>、<td>...)。
    所有網址、錨定標記和連結都將移除,且一律不會向使用者顯示。如果您想利用相片打造豐富的使用者體驗,請使用下方的「related_media」欄位傳送相片網址。

重要注意事項:

  • 除了上述支援的標記以外,請盡量不要使用其他標記,因為系統會將不支援的標記中的內容移除,而這可能會影響使用者體驗。
  • 盡量避免使用深度巢狀結構,例如超過 3 個不同的標題層級或巢狀清單。建議使用扁平、簡潔且直觀的結構,有助改善使用者體驗。
  • 如果目前支援的版面配置無法滿足您的用途,請與「透過 Google 預訂」團隊聯絡。
  • 建議大小上限為 32,000 個字元。
price

Price

服務價格。

price_interpretation

PriceInterpretation

說明如何向使用者呈現及顯示價格。除了「餐飲」和「觀光景點」以外,其他任何產業皆可用來設定服務價格的顯示方式。

rules

SchedulingRules

預約/取消預約的規則。

prepayment_type

PrepaymentType

說明是否需要預付、選用或不支援。

prepayment_terms

PrepaymentTerms

預付完成後的相關條款。

form[]
(deprecated)

ServiceIntakeForm

已淘汰,請使用 intake_form 和 per_ticket_intake_form。

intake_form

ServiceIntakeForm

此表單用於在使用者預訂這項服務時,要求使用者提供額外的資訊。(選填)

per_ticket_intake_form

ServiceIntakeForm

此表單用於在使用者預訂這項服務時,要求使用者提供額外的資訊。針對每張預訂的票券,使用者都必須填寫一次。(選填)

tax_rate

TaxRate

服務的稅率。如果使用此欄位,其內容會覆寫商家層級的所有 tax_rate 設定。空白訊息 (即 tax_rate { }) 會將套用的稅率重設為零。

payment_option_id[]

string

針對可用於支付此服務費用的付款方式,列出其參照 ID。實際付款方式需在商家層級定義,而且可由多個商家共用。

deposit

Deposit

定義向使用者收取訂金的方式。指定此欄位將會覆寫該服務的訂金。如將此項設為空白的 Deposit 訊息,則系統會移除所有服務層級的訂金。(選填)

no_show_fee

NoShowFee

定義可能會向使用者收取的逾時未到費用。指定此欄位將會覆寫該服務的逾時未到費用。如將此項設為空白的 NoShowFee 訊息,則系統會移除所有服務層級的逾時未到費用。(選填)

require_credit_card

RequireCreditCard

指出使用者是否必須提供信用卡才能預訂這項服務。您可以在供應情形層級覆寫這個欄位。(選填)

type

ServiceType

這項服務的預先定義類型。(選填)

ticket_type[]

TicketType

這項服務可預訂/購買的票券類型 (如果支援票券的話)。(選填)

related_media[]

RelatedMedia

與這項服務相關的相片。Google 會檢索並儲存媒體,確保以最有效率的方式向使用者顯示相關內容。(選填)

service_attribute_value_id[]

ServiceAttributeValueId

適用於這項服務的服務屬性值 (選用)。每項「Service」對於在對應「Merchant」中定義的每個服務屬性都可設定零或多個值。(選填)

waitlist_rules

WaitlistRules

加入等候名單的規則。

ticketing_vertical_specific_data

TicketingVerticalSpecificData

活動售票業專用的額外資訊。(選填)

integration_type

IntegrationType

我們針對這項服務支援的整合深度。(選用) 不適用於採用新手整合的合作夥伴。這類合作夥伴的端對端功能將一律停用。

per_order_fee

PerOrderFee

購買這項服務的訂單層級費用。(選填)

tours_and_activities_content

ToursAndActivitiesContent

「導覽行程」和「活動」專用的內容欄位。

location[]

Location

與這項服務相關的位置。重要注意事項:如有多個造訪地點與這項服務有關,或是 START_LOCATION 與 VISITED_LOCATION 不同,則必須指定 START_LOCATION。範例:- 單車導覽行程,中間將停留三個景點,則必須指定起點。- 巴士導覽行程,在飯店大廳集合,然後前往參觀地點。必須指定會議地點。

rating

Rating

這項服務的使用者評分,視為所有評論的匯總指標。

home_service_data

HomeServiceData

適用於居家服務產業的額外資訊。(選填)

virtual_session

VirtualSession

選用設定。虛擬工作階段的相關資訊。如要啟用虛擬服務,此為必要條件。

direct_merchant_payment

DirectMerchantPayment

選用設定。如果服務要求使用者直接付款給商家,則必須加入額外資訊。重要注意事項:RwG 不會參與這筆交易。如果已定義 virtual_session,且服務不會免費或 prepayment_type 設為 REQUIRED,就必須提供這項屬性。

PrepaymentTerms

預付完成後的特定資訊。

欄位
charge_timing

ChargeTiming

收費時間是相對於購買時間。

charge_time_before_start_time_sec

int64

向使用者收取費用的時間 (以秒為單位)。只有在 ChargeTiming 為 CHARGE_LATER 時才需要設定這個欄位。

ChargeTiming

以預估時間相對於購買時間的收費。

列舉
CHARGE_TIMING_UNSPECIFIED 未使用。
CHARGE_NOW 系統會立即向「客戶」收費。
CHARGE_LATER 系統稍後會向客戶收費。

PrepaymentType

以列舉方式表示預付類型。

列舉
PREPAYMENT_TYPE_UNSPECIFIED 根據預設,我們會假設預付功能為 NOT_SUPPORTED。
REQUIRED 使用者必須在預訂時支付這項服務的費用。
OPTIONAL 使用者可以選擇在預訂時或稍後預付服務費用,但預訂此服務不一定要先預付費用。
NOT_SUPPORTED 這項服務不支援預付。

ServiceType

預先定義的服務類型。

列舉
SERVICE_TYPE_UNSPECIFIED 未使用。
SERVICE_TYPE_DINING_RESERVATION 餐廳預訂。
SERVICE_TYPE_FOOD_ORDERING 訂餐,可以包括餐點外送和/或外帶。
SERVICE_TYPE_FOOD_DELIVERY 餐點外送。
SERVICE_TYPE_FOOD_TAKEOUT 餐點外帶。
SERVICE_TYPE_EVENT_TICKET 活動票券。
SERVICE_TYPE_TRIP_TOUR 旅遊導覽行程。
SERVICE_TYPE_APPOINTMENT 課程或提供預約的服務。建議使用的類別:(1) 健康與健身,(2) SPA 與美容,以及 (3) 財務諮詢與評估服務。請參閱支援的服務類型:https://developers.google.com/maps-booking/guides/end-to-end-integration/overview
SERVICE_TYPE_ONLINE_APPOINTMENT 提供線上預約課程或課程的線上預約服務,這類服務都以虛擬方式進行。如果啟用虛擬服務預訂功能,就必須設定。
SERVICE_TYPE_SHOPPING 允許使用者向特定商家購物的服務。可以是外送或自取。

ServiceAttribute

服務屬性是合作夥伴定義的類別,用來說明「商家」提供的「服務」。舉例來說,銀行可以定義「帳戶類型」服務屬性,可能的值為「個人」和「公司」;而美髮沙龍可以定義「服務類型」服務屬性,可能的值為「剪髮」、「染髮」和「造型」。

欄位
attribute_id

string

用來在相同商家與其他商家之間識別出這個服務屬性的專屬 ID,例如「帳戶類型」。

attribute_name

string

使用者看到的屬性名稱,例如「帳戶類型」。

value[]

Value

這個服務屬性的所有可能值。

代表特定服務屬性的可能值。

欄位
value_id

string

此 ID 可在這個服務屬性的其他屬性中識別出這個值,例如「個人」。

value_name

string

使用者看到的值名稱,例如「個人」。

ServiceAttributeValueId

識別要套用到某項「服務」的特定服務屬性值。

欄位
attribute_id

string

Merchant.service_attribute 中定義的屬性 ID,例如「service-type」。

value_id

string

這項屬性值的 ID,例如「haircut」。必須與服務屬性定義中的 value_id 相符。

ServiceAvailability

供應情形和適用對象/時機清單。

欄位
name

string

要套用這個項目的服務的資源名稱。格式:partners/{partner_id}/merchants/{merchant_id}/services/{service_id}

start_time_restrict

Timestamp

如有提供,我們會將實體提供的供應情形視為於 [start_time_restrict, end_time_restrict] 擷取的完整快照。也就是說,如果以下條件皆成立,則所有現有的供應情形資料都將會刪除:

   start_time_restrict <= availability.start_sec &&
   availability.start_sec < end_time_restrict

如果設定了 duration 訊息,則條件會進一步受到限制:

  availability.duration == duration_restrict

如果設定了 resources_restrict 訊息,則條件會進一步受到限制:

   availability.resources.staff_id == resources_restrict.staff_id &&
   availability.resources.room_id == resources_restrict.room_id

這些欄位通常用來提供指定時間範圍內的供應情形完整更新。

如果設定 start_time_restrict 而不設定 end_time_restrict,系統會解讀為一律從 start_time_restrict 開始。

end_time_restrict

Timestamp

如果設定 end_time_restrict 而不設定 start_time_restrict,系統會解讀為一律到 end_time_restrict 為止。

duration_restrict

Duration

設定 duration 會進一步將更新範圍限制在相符期間內的供應情形。

resources_restrict

Resources

設定 resources_restrict 會進一步將更新範圍限制在這組資源。資源的所有 ID 欄位都必須完全相符。

availability[]

Availability

新的供應情形清單。

ServiceIntakeForm

定義用來自訂商家所提供服務的登記表單。

欄位
field[]

ServiceIntakeFormField

要向使用者顯示的欄位。

first_time_customers
(deprecated)

bool

如果為「是」,系統會向初次光顧的客戶顯示這份表單。已淘汰。登記表單不支援這項功能。

returning_customers
(deprecated)

bool

如果為「是」,系統會向回流客戶顯示這份表單。已淘汰。登記表單不支援這項功能。

ServiceIntakeFormField

定義包含在 ServiceIntakeForm 中的欄位。

欄位
id

string

來自集結網站合作夥伴的字串,用來識別個別表單欄位。這個 ID 應與對應表單欄位答案中的 ID 相同,且在服務層級和所有票券登記表單中均不得重複。(必填)

type

FieldType

這個欄位的類型。

label

string

這個欄位向使用者顯示的文字。已淘汰,請改用 localized_label

localized_label

Text

這個欄位向使用者顯示的文字。此欄位支援多種語言代碼 (能以多種語言填入內容)。(必填)

value[]

string

只在欄位類型為 LOCATION_SEARCH 時設定。請使用「location_id」位於「位置」欄位,指定位置值。

choice_text[]

Text

只在欄位類型為 MULTIPLE_CHOICE、CHECKBOXES 或 DROPDOWN 時設定。用來列舉可能的選項。

is_required

bool

指出使用者是否需要回答此欄位。

allow_custom_answer

bool

指出除了預先定義的答案外,是否允許自訂值。只有在欄位類型為 LOCATION_SEARCH 時才能使用此屬性。(選填)

additional_option[]

Text

除了提供的值以外,我們還提供其他選項。只有在欄位類型為 LOCATION_SEARCH 時適用。例如:除了提供的地點清單外,您還可以選取「我稍後與供應商聯絡」選項。(選填)

ticket_type_restrict[]

string

如果這個問題只應在使用者預訂特定票券類型時顯示,則此欄位應設為一組適用的票券類型 ID。如果問題一律適用,請將這個欄位留空。

hint

Text

輸入內容的提示文字,以文字預留位置的形式顯示。這僅適用於欄位類型為 SHORT_ANSWER 或 PARAGRAPH 的情況。(選填)

FieldType

以列舉方式表示欄位類型。

列舉
FIELD_TYPE_UNSPECIFIED 系統會忽略未指定或不明類型的欄位。
SHORT_ANSWER 單行文字輸入欄位。
PARAGRAPH 多行文字輸入欄位。
MULTIPLE_CHOICE 一組圓形按鈕,使用者必須從多個選項中選擇一個。
CHECKBOXES 一或多個搭配核取方塊顯示的列舉項目。
DROPDOWN 下拉式選單中的選項。
BOOLEAN 「是/否」按鈕。

TaxRate

向使用者收取服務費用時適用的稅率,可依個別商家或服務進行設定。

欄位
micro_percent

int32

稅率以一個百分比的百萬為單位,有效位數可達 6 位的精確度。舉例來說,如果稅率是 7.253%,這個欄位就應設定為 7253000。

如果這個欄位未設定或設為 0,則此商家就其提供的任何服務向使用者收取的總價格就是 Service.price 指定的實際價格。系統會假設服務價格為免稅或已包含適用稅金。系統不會在獨立的明細項目中向使用者顯示稅金。

如果將這個欄位設定為任何非零值,則此商家就其提供的任何服務向使用者收取的總價格,將包含服務價格加上以此處提供的稅率計算的稅金。最小貨幣單位的小數 (例如 1 美分後面的小數) 會採用銀行家捨入法。系統會在獨立的明細項目中向使用者顯示稅金。

Terms

向使用者顯示的一組規則與規範,必須遵守才能經由「透過 Google 預訂」進行預訂。

欄位
url

string

(選用) 條款及細則的網址。

text

string

此為要向消費者顯示的文字內容。新的整合方式請使用下方的 localized_text。

localized_text

Text

要向使用者顯示的本地化文字。

文字

可能已本地化的文字酬載。部分文字欄位可能包含加上標記的內容。

欄位
value

string

語言代碼不明的文字值。只有在 localized_value 空白時才需要提供。這個值的語言代碼可能因合作夥伴或服務供應商而異,不應假設為任何特定語言。

localized_value[]

LocalizedString

依據語言代碼本地化的文字值。選填。

TicketType

TicketType 用來區分價格和/或供應情形各不相同的票券;價格和/或供應情形取決於使用者類型、服務屬性或選購項目/附加服務。

一張票券是指特定服務的最小可預訂單位,例如泛舟名額、博物館入場券、雙人皮艇一日租用券。

欄位
ticket_type_id

string

票券 ID 可用來區分同一服務的不同票券類型,且每項服務中均不得重複。

short_description

string

這個 TicketType 的簡短說明。

這項內容可向使用者顯示,例如「成人」、「兒童」、「退伍軍人」、「J 排」等。這是必要項目,每種票券類型都應向使用者顯示說明。已淘汰,請改用 localized_short_description。

localized_short_description

Text

這個 TicketType 的簡短說明,支援 i18n。

這項內容可向使用者顯示,例如「成人」、「兒童」、「退伍軍人」、「J 排」等。這是必要項目,每種票券類型都應向使用者顯示說明。您可以針對各個語言代碼提供不同的值。

price

Price

這個類型一張票券的價格,不含任何稅金。票券會套用「服務」稅率。

per_ticket_fee

PerTicketFee

購買此票券需要的額外費用。(選填)

option_description

string

這個票券類型代表的任何其他選項的說明 (如適用)。已淘汰,請改用 localized_option_description。

localized_option_description

Text

這個票券類型代表的任何其他選項的說明 (如適用)。您可以針對各個語言代碼提供不同的值。

如果票券類型代表多個維度,額外選項就能派上用場。

範例 1:入場券有不同的類型 (「成人」、「兒童」) 和語言額外選項,TicketType 清單應如下所示:- { ticket_type_id: "ticket_type_1" localized_short_description { value: "成人" } localized_option_description { value: "英文" } } - { ticket_type_id: "ticket_type_2" localized_short_description { value: "成人" } localized_option_description { value: "西班牙文" } } - { ticket_type_id: "ticket_type_3" localized_short_description { value: "兒童" } localized_option_description { value: "英文" } } - { ticket_type_id: "ticket_type_4" localized_short_description { value: "兒童" } localized_option_description { value: "西班牙文" } }

範例 2:皮艇出租 (按小時計),可加選防水袋,short_description 可以是「3 小時」,而 option_description 可以是「含防水袋」或「不含防水袋」:- { ticket_type_id: "ticket_type_1" localized_short_description { value: "2 小時" } localized_option_description { value: "英文" } } - { ticket_type_id: "ticket_type_2" localized_short_description { value: "2 小時" } localized_option_description { value: "西班牙文" } } - { ticket_type_id: "ticket_type_3" localized_short_description { value: "3 小時" } localized_option_description { value: "英文" } } - { ticket_type_id: "ticket_type_4" localized_short_description { value: "3 小時" } localized_option_description { value: "西班牙文" } }

(選用) 不過如果服務中有任何票券類型設定了這個欄位,我們會預期所有其他票券類型也都設定了這個欄位 (可使用預設的 option_description)。舉例來說,[{ticket_type_1, 成人, 英文}, {ticket_type_1, 成人, ''}] 就不是有效清單。

僅支援兩種 HTML 格式標記:
。這兩者是用來指定含有標題和詳細說明的選項,例如:「高級座位
這個選項提供私人包廂座位,附全軟墊座椅、私人電視、座位餐飲服務。這些座位能將如畫的美景盡收眼底。」

TicketingVerticalSpecificData

活動售票業專用的額外資訊。

欄位
event_category

EventCategory

活動的類別。只有在活動屬於其中一個預先定義的類別時,才設定此項目。(選填)

event_url

string

合作夥伴網站上的活動網址。(選填)

entity[]

Entity

與活動相關的實體清單。(選填)

event_attendance_mode

AttendanceMode

必要欄位。活動出席狀況的類型。

event_virtual_location_url[]

string

選用設定。可查看事件的網址。

event_organizer

Text

選用設定。活動主辦人。

event_organizer_url

string

選用設定。活動主辦人的網址。

event_organizer_type

OrganizerType

選用設定。發起人類型。

event_source_url[]

string

必要欄位。含有活動資訊或說明的網頁網址。

event_state

EventState

選用設定。事件狀態。

AttendanceMode

活動出席狀況的類型。

列舉
ATTENDANCE_MODE_UNSPECIFIED 不指定。
ONLINE 用於虛擬活動。
PHYSICAL 用於實體活動。
PHYSICAL_ONLINE_MIXED 適用於同時屬於實體和虛擬活動。

實體

代表與活動相關的實體。

欄位
id

string

合作夥伴資料庫中實體的專屬 ID。(選填)

name

string

實體名稱。(必填)

url

string

明確描述實體的網頁網址。這是合作夥伴網站上針對該實體 (如果有的話) 的網頁;至於該實體的其他公開網址,請使用 public_identification_data 中的 relevant_url。(選填)

entity_type

EntityType

實體的類型。(選填)

entity_role

EntityRole

活動中實體扮演的角色。(選填)

public_identification_data

PublicIdentificationData

實體的公開參照。(選填)

EntityRole

活動中實體扮演的角色。

列舉
ENTITY_ROLE_UNSPECIFIED 未指定。
ENTITY_ROLE_HEADLINER 實體代表活動的主角或首席演出者。
ENTITY_ROLE_SUPPORTER 實體代表活動的配角。
ENTITY_ROLE_HOME_TEAM 實體代表 (體育) 賽事活動中的主隊。
ENTITY_ROLE_AWAY_TEAM 實體代表 (體育) 賽事活動中的客隊。

EntityType

實體的類型。注意:這不會用來當做通用本體。

列舉
ENTITY_TYPE_UNSPECIFIED 未指定。請勿使用。
ENTITY_TYPE_PERFORMER 實體代表在演唱會/音樂會或節目中演出的演出者或團體。只有在活動類別是 CONCERT 或 THEATRE 的時候才適用。
ENTITY_TYPE_PLAYER 實體代表活動中的隊伍或選手。只有在活動類別是 SPORTS 的時候才適用。
ENTITY_TYPE_CONCERT_TOUR 實體代表這個活動所屬的導覽行程。只有在活動類別是 CONCERT 的時候才適用。
ENTITY_TYPE_SPORTS_SERIES 實體代表此活動所屬的體育錦標賽。只有在活動類別是 SPORTS 的時候才適用。
ENTITY_TYPE_PLAY 實體代表活動中演出的節目類型 (例如音樂劇、喜劇、芭蕾等)。只有在活動類別是 THEATRE 的時候才適用。

EventCategory

一部分的活動類別,可供我們自訂產品體驗。注意:這不會用來當做活動的通用本體。

列舉
EVENT_CATEGORY_UNSPECIFIED 未指定。請勿使用。
EVENT_CATEGORY_CONCERT 音樂會/演唱會。
EVENT_CATEGORY_SPORTS 運動賽事。
EVENT_CATEGORY_THEATRE 戲劇活動。
EVENT_CATEGORY_EXHIBITS 展覽。
EVENT_CATEGORY_WORKSHOPS_AND_CLASSES 研討會和課程。

EventState

事件狀態。

列舉
EVENT_STATE_UNSPECIFIED 不指定。
SCHEDULED 活動已排定。
RESCHEDULED 已重新安排活動。
CANCELLED 活動已取消。
POSTPONED 活動已延期。

OrganizerType

發起人類型。

列舉
ORGANIZER_TYPE_UNSPECIFIED 不指定。
PERSON 適用對象為個人或發起人。
ORGANIZATION 適用於機構的發起人。

PublicIdentificationData

ID、網頁,或任何其他參照實體的公開來源。

欄位
relevant_url[]

string

主題專用的任何網頁的公開網址。這類內容可能包括官方網站、discogs、社交媒體平台、維基百科或 imdb 頁面,例如 https://www.discogs.com/artist/1124645-Taylor-Swifthttps://www.wikidata.org/wiki/Q19320959https://twitter.com/acmilan。(選填)

musicbrainz_id

string

演出者或其他音樂實體的 36 個字元 musicbrainz ID (如有)。請參閱 https://musicbrainz.org/doc/MusicBrainz_Identifier。(選填)

TimeRange

封閉式開放時間範圍,即 [start_time, end_time]。

欄位
start_time

Timestamp

時間範圍的下限。

end_time

Timestamp

時間範圍的上限。

TokenizationConfig

付款處理方的代碼化技術設定,為個別商家分別設置。

欄位
tokenization_parameter

map<string, string>

代碼化技術的設定通常會有一個 tokenization_parameter,其金鑰為「gateway」,其值則是處理方的名稱。

其餘參數則視處理方而定。請參閱 Google Pay 的說明文件,進一步瞭解詳情。

Braintree 範例:tokenization_parameter { key: "gateway" value: "braintree" } tokenization_parameter { key: "braintree:apiVersion" value: "v1" } tokenization_parameter { key: "braintree:sdkVersion" value: "2.30.0" } tokenization_parameter { key: "braintree:merchantId" value: "abcdef" } tokenization_parameter { key: "braintree:clientKey" value: "production_xxx_yyy" }

Stripe 範例:tokenization_parameter { key: "gateway" value: "stripe" } tokenization_parameter { key: "stripe:version" value: "2018-02-28" } tokenization_parameter { key: "stripe:publishableKey" value: "pk_1234" }

Adyen 範例:tokenization_parameter { key: "gateway" value: "adyen" } tokenization_parameter { key: "gatewayMerchantId" value: "yourId" }

billing_information_format

BillingInformationFormat

在付款代碼中納入消費者在 Google Pay 中為付款方式提供的帳單資訊 (請見上方說明)。將此欄位留空等同於指定 MIN。

BillingInformationFormat

指明消費者需要提供的帳單地址資訊詳細程度,以及要在代碼中納入多細的帳單地址資訊。此列舉值與 Google Pay API 中的參數相同 (詳情請參閱 https://developers.google.com/pay/api/web/reference/object#BillingAddressParameters)

列舉
BILLING_INFORMATION_FORMAT_UNSPECIFIED 未指定,由系統預設為 MIN。
MIN 姓名、國家/地區代碼和郵遞區號 (Google Pay 預設設定)。
FULL 姓名、街道地址、縣市、地區、國家/地區代碼與郵遞區號。

ToursAndActivitiesContent

「導覽行程」和「活動」專用的內容欄位。在重複欄位中的每個元素都應該是獨立的,以便分開顯示 (例如以項目符號條列)。

強烈建議您為「導覽行程」和「活動」填入 ToursAndActivitiesContent (但不強制)。所有欄位都支援純文字和類 HTML 文字這兩種基本格式。支援的類 HTML 格式標記:

詞組標記:
:僅支援上述三種標記。
可以用於在段落中斷行,而 // 則可用來標明重要文字。系統會忽略其他所有詞組標記。

系統不允許其他所有標記和自訂樣式,而且會將其移除。所有網址、錨定標記和連結都將移除,一律不會向使用者顯示。

重要注意事項:*在 highlightsexclusion 和服務說明中其他更詳盡的欄位已提供的資料,請勿再重複提供。* 除了上述支援的標記以外,請避免使用其他標記,因為系統會將不支援的標記中的內容移除,而這可能會影響使用者體驗。

欄位
highlights[]

Text

向使用者顯示的重點清單。

inclusions[]

Text

向使用者顯示的包含項目清單。

exclusions[]

Text

向使用者顯示的排除項目清單。

must_know[]

Text

向使用者顯示的重要記事清單,用於提供詳細資料,例如年齡限製或其他不適合使用這項服務的條件。

UnsupportedPartySizeOption

超出範圍的派對選項。

欄位
call_merchant

CallMerchant

如果用餐人數超出範圍,可以打電話給商家。使用者會看到預先定義的訊息。要顯示的文字範例:「如果參與者人數超過 {waitlist_rules.max_party_size},請致電 {phone} 上的餐廳。」CallMerchant 必須設定,但將會空白。

UpdateBookingRequest

更新 google.maps.booking.v1alpha.Booking 的要求

欄位
update_mask

FieldMask

所有要更新的預訂欄位的欄位遮罩

booking

Booking

要更新的預訂

booking_failure

BookingFailure

如果非同步確認的預訂要求處理失敗,且預訂狀態已更新為「失敗」,這個欄位應反映出商業邏輯錯誤 (例如使用者目前已有的預訂項目時間太接近這個時間)。只有在將預訂狀態更新為「失敗」時,才需要設定這個欄位,否則系統會忽略此欄位。

UpdateMerchantRequest

更新 Merchant 的要求。

欄位
merchant

Merchant

新的商家資料。

update_mask

FieldMask

要為商家更新的特定欄位。

UpdateOrderRequest

更新 google.maps.booking.v1alpha.Order 的要求

欄位
update_mask

FieldMask

所有要更新的訂單欄位的欄位遮罩

order

Order

要更新的訂單

UpdateServiceRequest

更新 Service 的要求。

欄位
service

Service

新服務資料。

update_mask

FieldMask

要為服務更新的特定欄位。

UserPurchaseRestriction

用來限定哪些使用者有資格用此付款方式購物。

欄位
new_to_merchant

bool

只有先前從未向同一個商家購物的使用者,才能使用這種付款方式。

new_to_payment_option

bool

只有先前從未購買同一種付款方式的使用者,才能購買該付款方式。

VirtualSession

線上/線上工作階段相關資訊。例如:線上瑜珈課程、虛擬烹飪課程等

欄位
session_instructions

Text

設定這個虛擬課程的操作說明。如果合作夥伴預訂時沒有提供影片網址,則這段文字必須包含影片網址,以便向使用者分享。例如:「縮放網址將在課程開始前 30 分鐘收到。」(建議選項)

session_requirements

Text

特定虛擬工作階段的需求。例如:瑜珈墊、烹飪用具等 (建議)

virtual_platform_info

VirtualPlatformInfo

此工作階段中使用的虛擬平台相關資訊。(啟用虛擬服務時必須啟用)

is_session_prerecorded

bool

必要欄位。如果虛擬工作階段未直播且已預先錄製,請設為 true。

VirtualPlatformInfo

將用於這個虛擬工作階段的平台相關資訊。

欄位
platform

Platform

用於虛擬工作階段的平台。

other_platform_name

Text

平台名稱 (如果平台設為 OTHER)。(如果平台設為 OTHER,則為必要欄位)

平台

以列舉方式表示商家要使用的虛擬平台。

列舉
PLATFORM_UNSPECIFIED 未使用。
FLEXIBLE 商家可以靈活運用影片平台,
GOOGLE_HANGOUTS Google Hangouts 產品。
GOOGLE_MEET Google Meet 產品。
ZOOM Zoom 視訊通訊。
SKYPE Skype。
YOUTUBE 在 YouTube 中直播。
OTHER 如果使用的影片平台與本文未提及的平台不同,則應設定。

WaitlistRules

加入等候名單的相關規則。

欄位
min_party_size

int32

必要。適用於提供等候名單功能的服務,必須填入正整數。如果服務或商家未提供等候名單功能,就不能填入這個欄位。

max_party_size

int32

必要欄位。適用於提供等候名單功能的服務,必須填入正整數。如果服務或商家未提供等候名單功能,就不能填入這個欄位。

supports_additional_request

bool

如果設為「true」,使用者加入這項服務的等候名單時,將可以傳送任意形式的額外文字要求。

above_max_party_size_options[]

UnsupportedPartySizeOption

為大於設定的 max_party_size 派對設定選項。如果大型方不應提供加入等候名單的替代選項,請將這個欄位留空。