基本類型
購物車
包含訂單詳細資料，以及要求是取貨還是送貨。購物車也會包含運送詳細資料、小費和運送地址。Cart 物件是在 Checkout AppRequest 中定義。您可以在 Checkout AppResponse 中加入購物車的副本。下表列出 Cart 類型的屬性：
| 屬性 | 類型 | 說明 | |
|---|---|---|---|
@type |
Const |
這個物件的類型。如果父項 Cart 物件是 ProposedOrder 的一部分，請省略這個欄位。 值： |
|
id |
String |
購物車的選用 ID。 |
|
merchant |
Merchant |
與此購物車相關的商家。 |
|
lineItems |
List<LineItem> |
必填。 使用者訂購的商品或服務清單。 必須至少包含 1 個項目。 |
|
promotions |
List<Promotion> |
這個購物車中適用的促銷活動。目前僅支援一項促銷活動。 |
|
notes |
String |
訂單或運送指示的附註。 |
|
extension |
FoodCartExtension |
定義使用者詳細資料，例如訂單履行偏好設定。 |
|
以下範例顯示 Cart 元素：
範例 1
{
"@type": "type.googleapis.com/google.actions.v2.orders.Cart",
"merchant": {
"id": "https://www.exampleprovider.com/merchant/id1",
"name": "Cucina Venti"
},
"lineItems": [
{
"name": "Sizzling Prawns Dinner",
"type": "REGULAR",
"id": "sample_item_offer_id_1",
"offerId": "https://www.exampleprovider.com/menu/item/offer/id1",
"quantity": 1,
"price": {
"type": "ESTIMATE",
"amount": {
"currencyCode": "USD",
"units": "16",
"nanos": 750000000
}
},
"subLines": [
{
"note": "Notes for this item."
}
],
"extension": {
"@type": "type.googleapis.com/google.actions.v2.orders.FoodItemExtension",
"options": [
{
"id": "sample_addon_offer_id_1",
"offerId": "https://www.exampleprovider.com/menu/item/addon/offer/id1",
"name": "Honey Mustard",
"price": {
"currencyCode": "USD"
},
"quantity": 1
},
{
"id": "sample_addon_offer_id_2",
"offerId": "https://www.exampleprovider.com/menu/item/addon/offer/id2",
"name": "BBQ Sauce",
"price": {
"currencyCode": "USD",
"nanos": 500000000
},
"quantity": 1
}
]
}
}
],
"extension": {
"@type": "type.googleapis.com/google.actions.v2.orders.FoodCartExtension",
"fulfillmentPreference": {
"fulfillmentInfo": {
"delivery": {
"deliveryTimeIso8601": "P0M"
}
}
},
"location": {
"coordinates": {
"latitude": 37.788783,
"longitude": -122.41384
},
"formattedAddress": "1350 CHARLESTON ROAD, MOUNTAIN VIEW, CA, United States",
"zipCode": "94043",
"city": "Mountain View",
"postalAddress": {
"regionCode": "US",
"postalCode": "94043",
"administrativeArea": "CA",
"locality": "Mountain View",
"addressLines": [
"1350 Charleston Road"
]
},
"notes": "Gate code is #111"
}
}
}
範例 2
{
"merchant": {
"id": "https://www.exampleprovider.com/merchant/id1",
"name": "Falafel Bite"
},
"lineItems": [
{
"name": "Pita Chips",
"type": "REGULAR",
"id": "sample_item_offer_id_1",
"offerId": "https://www.exampleprovider.com/menu/item/offer/id1",
"quantity": 1,
"price": {
"type": "ESTIMATE",
"amount": {
"currencyCode": "USD",
"units": "2",
"nanos": 750000000
}
},
"subLines": [
{
"note": "Notes for this item."
}
],
"extension": {
"@type": "type.googleapis.com/google.actions.v2.orders.FoodItemExtension",
"options": [
{
"id": "sample_addon_offer_id_1",
"offerId": "https://www.exampleprovider.com/menu/item/addon/offer/id1",
"name": "Honey Mustard",
"price": {
"currencyCode": "USD"
},
"quantity": 1
},
{
"id": "sample_addon_offer_id_2",
"offerId": "https://www.exampleprovider.com/menu/item/addon/offer/id2",
"name": "BBQ Sauce",
"price": {
"currencyCode": "USD",
"nanos": 500000000
},
"quantity": 1
}
]
}
},
{
"name": "Chicken Shwarma Wrap",
"type": "REGULAR",
"id": "sample_item_offer_id_2",
"offerId": "https://www.exampleprovider.com/menu/item/offer/id2",
"quantity": 1,
"price": {
"type": "ESTIMATE",
"amount": {
"currencyCode": "USD",
"units": "8"
}
},
"extension": {
"@type": "type.googleapis.com/google.actions.v2.orders.FoodItemExtension"
}
},
{
"name": "Greek Salad",
"type": "REGULAR",
"id": "sample_item_offer_id_3",
"offerId": "https://www.exampleprovider.com/menu/item/offer/id3",
"quantity": 1,
"price": {
"type": "ESTIMATE",
"amount": {
"currencyCode": "USD",
"units": "9",
"nanos": 990000000
}
},
"extension": {
"@type": "type.googleapis.com/google.actions.v2.orders.FoodItemExtension"
}
},
{
"name": "Prawns Biryani",
"type": "REGULAR",
"id": "sample_item_offer_id_4",
"offerId": "https://www.exampleprovider.com/menu/item/offer/id4",
"quantity": 1,
"price": {
"type": "ESTIMATE",
"amount": {
"currencyCode": "USD",
"units": "15",
"nanos": 990000000
}
},
"extension": {
"@type": "type.googleapis.com/google.actions.v2.orders.FoodItemExtension"
}
}
],
"extension": {
"@type": "type.googleapis.com/google.actions.v2.orders.FoodCartExtension",
"fulfillmentPreference": {
"fulfillmentInfo": {
"delivery": {
"deliveryTimeIso8601": "P90M"
}
}
},
"location": {
"coordinates": {
"latitude": 37.788783,
"longitude": -122.41384
},
"formattedAddress": "1350 CHARLESTON ROAD, MOUNTAIN VIEW, CA, United States",
"zipCode": "94043",
"city": "Mountain View",
"postalAddress": {
"regionCode": "US",
"postalCode": "94043",
"administrativeArea": "CA",
"locality": "Mountain View",
"addressLines": [
"1350 Charleston Road"
]
},
"notes": "Gate code is #111"
}
}
}
聯絡
指定訂單收件人的詳細資料。這項功能僅適用於AppResponse。下表列出 Contact 類型的屬性：
| 屬性 | 類型 | 說明 | |
|---|---|---|---|
displayName |
String |
收貨人的姓名，請依照你希望顯示的方式輸入。如果未指定 firstName 和 lastName，請使用這個欄位。 範例： |
|
email |
String |
訂單收件者的電子郵件地址。 範例： |
|
firstName |
String |
收取訂單的人員姓氏。 範例： |
|
lastName |
String |
收到訂單的收件者姓氏。 範例： |
|
phoneNumber |
String |
訂單收件人的電話號碼，包括國家/地區代碼。 範例： |
|
emailVerified |
布林值 |
指出接收訂單的使用者是否已登入 Google 帳戶。 |
|
以下範例顯示 Contact 元素：
範例
{
"displayName": "Lovefood Ordering",
"email": "ilovefood@example.com",
"phoneNumber": "+16501234567"
}
CustomPushMessage
包含要求的OrderUpdate。下表列出 CustomPushMessage 類型的屬性：
| 屬性 | 類型 | 說明 | |
|---|---|---|---|
orderUpdate |
OrderUpdate |
必填。 訂單的最新資訊。 |
|
以下範例顯示 CustomPushMessage 元素：
範例
{
"orderUpdate": {
"actionOrderId": "sample_action_order_id",
"orderState": {
"state": "IN_TRANSIT",
"label": "Order is on the way"
},
"inTransitInfo": {
"updatedTime": "2017-07-17T12:00:00Z"
},
"updateTime": "2017-07-17T12:00:00Z",
"orderManagementActions": [
{
"type": "CUSTOMER_SERVICE",
"button": {
"title": "Contact customer service",
"openUrlAction": {
"url": "mailto:support@example.com"
}
}
},
{
"type": "EMAIL",
"button": {
"title": "Email restaurant",
"openUrlAction": {
"url": "mailto:person@example.com"
}
}
},
{
"type": "CALL_RESTAURANT",
"button": {
"title": "Call restaurant",
"openUrlAction": {
"url": "tel:+16505554679"
}
}
}
],
"receipt": {
"userVisibleOrderId": "userVisibleId1234"
},
"infoExtension": {
"@type": "type.googleapis.com/google.actions.v2.orders.FoodOrderUpdateExtension",
"estimatedFulfillmentTimeIso8601": "2017-07-17T13:00:00Z/2017-07-17T13:30:00Z"
}
}
}
DeliveryInfo
下表列出 DeliveryInfo 類型的屬性：
| 屬性 | 類型 | 說明 | |
|---|---|---|---|
deliveryTimeIso8601 |
String |
預估送達時間，採用 ISO 8601 時間戳記格式：「{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z」或持續時間格式：「P(n)Y(n)M(n)DT(n)H(n)M(n)S」。舉例來說，PT90M 代表 90 分鐘的時間長度。預設值「PT0M」表示偏好的提交時間是盡快提交。參考資料：https://en.wikipedia.org/wiki/ISO_8601#Combined_date_and_time_representations. 在結帳回應期間，使用這項參數更新預估送達時間。 範例： |
|
以下範例顯示 DeliveryInfo 元素：
範例
{
"deliveryTimeIso8601": "PT90M"
}
免責事項
下表列出 Disclaimer 類型的屬性：
| 屬性 | 類型 | 說明 | |
|---|---|---|---|
predefinedMessage |
PredefinedMessage |
必填。 在結帳時顯示預先定義的免責事項訊息。 |
|
feeAmount |
Money |
合作夥伴會向商家收取這筆訂單的 N 元費用。 |
|
feeAmountRange |
FeeAmountRange |
合作夥伴會向餐廳收取每筆訂單 N 到 M 的費用。 |
|
feePercent |
Number |
合作夥伴會向商家收取這筆訂單的 N% 費用。 |
|
feePercentRange |
FeePercentRange |
合作夥伴會向商家收取每筆訂單 N% 到 M% 的費用。 |
|
以下範例顯示 Disclaimer 元素：
範例 1
{
"predefinedMessage": "NEW_YORK_DELIVERY_FEE_TIP_DISCLAIMER"
}
範例 2
{
"predefinedMessage": "FEE_CHARGED_TO_RESTAURANT_DISCLOSURE"
}
範例 3
{
"predefinedMessage": "FEE_CHARGED_TO_RESTAURANT_DISCLOSURE",
"feePercent": 25
}
示例 4
{
"predefinedMessage": "FEE_CHARGED_TO_RESTAURANT_DISCLOSURE",
"feePercentRange": {
"minFeePercent": 20,
"maxFeePercent": 30
}
}
範例 5
{
"predefinedMessage": "FEE_CHARGED_TO_RESTAURANT_DISCLOSURE",
"feeAmount": {
"currencyCode": "AUD",
"units": 2,
"nanos": 500000000
}
}
範例 6
{
"predefinedMessage": "FEE_CHARGED_TO_RESTAURANT_DISCLOSURE",
"feeAmountRange": {
"minFeeAmount": {
"currencyCode": "AUD",
"units": 2,
"nanos": 500000000
},
"maxFeeAmount": {
"currencyCode": "AUD",
"units": 10,
"nanos": 0
}
}
}
錯誤
Error 類型可用的值如下：
CLOSED：餐廳在下單時間營業時間結束。NO_CAPACITY：沒有可用的服務容量 (例如，因尖峰時段而暫時停機)。NO_COURIER_AVAILABLE：由於送貨人員人數有限，無法處理訂單。REQUIREMENTS_NOT_MET：未符合接受訂單的限制條件 (例如，購物車的最低金額)。UNAVAILABLE_SLOT：訂單無法在 DeliveryInfo 或 PickupInfo 指定的預訂時間內完成。OUT_OF_SERVICE_AREA：訂單無法送達使用者的地址。PROMO_EXPIRED：促銷活動已過期，無法套用。PROMO_NOT_APPLICABLE：通用錯誤代碼，用於偵測所有無法套用促銷代碼的情況 (如果其他促銷代碼錯誤代碼都不符合)。PROMO_NOT_RECOGNIZED：系統無法辨識優待券代碼。PROMO_ORDER_INELIGIBLE：目前的訂單不符合這張優待券的使用資格。PROMO_USER_INELIGIBLE：目前使用者不符合這張優待券的使用資格。AVAILABILITY_CHANGED：商品已售完，或商品數量不足以滿足要求。INCORRECT_PRICE：費用或總價有價格錯誤。INVALID：LineItem、FulfillmentOption 或 Promotion 含有無效資料。NOT_FOUND：找不到明細項目、執行選項或促銷活動。PRICE_CHANGED：商品價格已變更。
FeeAmountRange
下表列出 FeeAmountRange 類型的屬性：
| 屬性 | 類型 | 說明 | |
|---|---|---|---|
minFeeAmount |
Money |
收取的費用金額下限。 |
|
maxFeeAmount |
Money |
收取的費用金額上限。 |
|
FeePercentRange
下表列出 FeePercentRange 類型的屬性：
| 屬性 | 類型 | 說明 | |
|---|---|---|---|
minFeePercent |
Number |
收取的費用百分比下限。 |
|
maxFeePercent |
Number |
收取的費用百分比上限。 |
|
FoodCartExtension
包含使用者詳細資料，例如訂單履行偏好設定。
下表列出 FoodCartExtension 類型的屬性：
| 屬性 | 類型 | 說明 | |
|---|---|---|---|
@type |
Const |
這個擴充功能的類型。這個欄位一律設為「type.googleapis.com/google.actions.v2.orders.FoodCartExtension」。 值： |
|
contact |
Contact |
訂單收件者的聯絡資訊。詳細資料包括使用者名稱、電話號碼和電子郵件地址。 |
|
fulfillmentPreference |
FulfillmentOption |
必填。 使用者的出貨偏好設定。 |
|
location |
Location |
在 CheckoutRequestMessage 中，這個欄位會指定運送地址，如果訂單需要運送，則必須提供這個欄位。如果是外帶或自取訂單，訊息中不會包含這個欄位。 |
|
以下範例顯示 FoodCartExtension 元素：
範例 1
{
"@type": "type.googleapis.com/google.actions.v2.orders.FoodCartExtension",
"fulfillmentPreference": {
"fulfillmentInfo": {
"delivery": {
"deliveryTimeIso8601": "P0M"
}
}
},
"location": {
"coordinates": {
"latitude": 37.788783,
"longitude": -122.41384
},
"formattedAddress": "1350 CHARLESTON ROAD, MOUNTAIN VIEW, CA, United States",
"zipCode": "94043",
"city": "Mountain View",
"postalAddress": {
"regionCode": "US",
"postalCode": "94043",
"administrativeArea": "CA",
"locality": "Mountain View",
"addressLines": [
"1350 Charleston Road"
]
},
"notes": "Gate code is #111"
}
}
範例 2
{
"@type": "type.googleapis.com/google.actions.v2.orders.FoodCartExtension",
"fulfillmentPreference": {
"fulfillmentInfo": {
"pickup": {
"pickupTimeIso8601": "P0M"
}
}
},
"contact": {
"displayName": "Lovefood Ordering",
"email": "ilovefood@example.com",
"phoneNumber": "+16501234567"
}
}
FoodErrorExtension
指出處理要求時發生一或多個錯誤。下表說明FoodErrorExtension 類型的欄位。您可以透過 CheckoutResponse 傳送錯誤。
下表列出 FoodErrorExtension 類型的屬性：
| 屬性 | 類型 | 說明 | |
|---|---|---|---|
@type |
Const | 必填。 這個擴充功能的類型。 值： |
|
foodOrderErrors |
List<FoodOrderError> |
必填。 描述發生錯誤的 FoodOrderError 物件陣列。建議每個購物車或每項商品只出現一個錯誤。 必須至少包含 1 個項目。 |
|
correctedProposedOrder |
ProposedOrder |
修正後的新 ProposedOrder。如果原始 ProposedOrder 中有可復原的錯誤，就會傳回這個物件。舉例來說，購物車中一或多個委刊項的價格變更，就是可復原的錯誤。針對有效的 ProposedOrder，可復原的錯誤會提前至確認階段，而不會要求使用者查看購物車。 |
|
paymentOptions |
PaymentOptions |
為使用者選取的預設付款方式。 |
|
additionalPaymentOptions |
List<PaymentOptions> |
使用者可使用的其他付款方式。 |
|
以下範例顯示 FoodErrorExtension 元素：
範例
{
"@type": "type.googleapis.com/google.actions.v2.orders.FoodErrorExtension",
"foodOrderErrors": [
{
"error": "PRICE_CHANGED",
"id": "sample_item_offer_id_1",
"description": "The price has changed.",
"updatedPrice": {
"currencyCode": "USD",
"units": "2",
"nanos": 750000000
}
},
{
"error": "PRICE_CHANGED",
"id": "sample_item_offer_id_2",
"description": "The price has changed.",
"updatedPrice": {
"currencyCode": "USD",
"units": "8"
}
}
],
"correctedProposedOrder": {
"id": "sample_corrected_proposed_order_id_1",
"otherItems": [
{
"name": "New customer discount",
"price": {
"type": "ESTIMATE",
"amount": {
"currencyCode": "USD",
"units": "-5",
"nanos": -500000000
}
},
"type": "DISCOUNT"
},
{
"name": "Delivery fee",
"price": {
"type": "ESTIMATE",
"amount": {
"currencyCode": "USD",
"units": "3",
"nanos": 500000000
}
},
"type": "DELIVERY"
},
{
"name": "Tax",
"price": {
"type": "ESTIMATE",
"amount": {
"currencyCode": "USD",
"units": "1",
"nanos": 500000000
}
},
"type": "TAX"
}
],
"cart": {
"merchant": {
"id": "https://www.exampleprovider.com/merchant/id1",
"name": "Falafel Bite"
},
"lineItems": [
{
"name": "Pita Chips",
"type": "REGULAR",
"id": "sample_item_offer_id_1",
"offerId": "https://www.exampleprovider.com/menu/item/offer/id1",
"quantity": 1,
"price": {
"type": "ESTIMATE",
"amount": {
"currencyCode": "USD",
"units": "2",
"nanos": 750000000
}
},
"subLines": [
{
"note": "Notes for this item."
}
],
"extension": {
"@type": "type.googleapis.com/google.actions.v2.orders.FoodItemExtension",
"options": [
{
"id": "sample_addon_offer_id_1",
"offerId": "https://www.exampleprovider.com/menu/item/addon/offer/id1",
"name": "Honey Mustard",
"price": {
"currencyCode": "USD"
},
"quantity": 1
},
{
"id": "sample_addon_offer_id_2",
"offerId": "https://www.exampleprovider.com/menu/item/addon/offer/id2",
"name": "BBQ Sauce",
"price": {
"currencyCode": "USD",
"nanos": 500000000
},
"quantity": 1
}
]
}
},
{
"name": "Chicken Shwarma Wrap",
"type": "REGULAR",
"id": "sample_item_offer_id_2",
"offerId": "https://www.exampleprovider.com/menu/item/offer/id2",
"quantity": 1,
"price": {
"type": "ESTIMATE",
"amount": {
"currencyCode": "USD",
"units": "8"
}
},
"extension": {
"@type": "type.googleapis.com/google.actions.v2.orders.FoodItemExtension"
}
},
{
"name": "Greek Salad",
"type": "REGULAR",
"id": "sample_item_offer_id_3",
"offerId": "https://www.exampleprovider.com/menu/item/offer/id3",
"quantity": 1,
"price": {
"type": "ESTIMATE",
"amount": {
"currencyCode": "USD",
"units": "9",
"nanos": 990000000
}
},
"extension": {
"@type": "type.googleapis.com/google.actions.v2.orders.FoodItemExtension"
}
},
{
"name": "Prawns Biryani",
"type": "REGULAR",
"id": "sample_item_offer_id_4",
"offerId": "https://www.exampleprovider.com/menu/item/offer/id4",
"quantity": 1,
"price": {
"type": "ESTIMATE",
"amount": {
"currencyCode": "USD",
"units": "15",
"nanos": 990000000
}
},
"extension": {
"@type": "type.googleapis.com/google.actions.v2.orders.FoodItemExtension"
}
}
],
"extension": {
"@type": "type.googleapis.com/google.actions.v2.orders.FoodCartExtension",
"fulfillmentPreference": {
"fulfillmentInfo": {
"delivery": {
"deliveryTimeIso8601": "P90M"
}
}
},
"location": {
"coordinates": {
"latitude": 37.788783,
"longitude": -122.41384
},
"formattedAddress": "1350 CHARLESTON ROAD, MOUNTAIN VIEW, CA, United States",
"zipCode": "94043",
"city": "Mountain View",
"postalAddress": {
"regionCode": "US",
"postalCode": "94043",
"administrativeArea": "CA",
"locality": "Mountain View",
"addressLines": [
"1350 Charleston Road"
]
},
"notes": "Gate code is #111"
}
}
},
"totalPrice": {
"type": "ESTIMATE",
"amount": {
"currencyCode": "USD",
"units": "36",
"nanos": 730000000
}
},
"extension": {
"@type": "type.googleapis.com/google.actions.v2.orders.FoodOrderExtension",
"availableFulfillmentOptions": [
{
"fulfillmentInfo": {
"delivery": {
"deliveryTimeIso8601": "P90M"
}
},
"expiresAt": "2017-07-17T12:30:00Z"
}
]
}
},
"paymentOptions": {
"googleProvidedOptions": {
"tokenizationParameters": {
"tokenizationType": "PAYMENT_GATEWAY",
"parameters": {
"gateway": "stripe",
"stripe:publishableKey": "pk_live_stripe_client_key",
"stripe:version": "2017-04-06"
}
},
"supportedCardNetworks": [
"AMEX",
"DISCOVER",
"MASTERCARD",
"JCB",
"VISA"
],
"prepaidCardDisallowed": true
}
}
}
FoodItemExtension
定義食品項目的加料。
下表列出 FoodItemExtension 類型的屬性：
| 屬性 | 類型 | 說明 | |
|---|---|---|---|
@type |
Const | 必填。 這個擴充功能的類型。這個欄位一律設為「type.googleapis.com/google.actions.v2.orders.FoodItemExtension」。 值： |
|
options |
List<FoodItemOption> |
選項可以是附加商品項目，也可以是包含一組附加商品的附加商品群組。 |
|
以下範例顯示 FoodItemExtension 元素：
範例
{
"@type": "type.googleapis.com/google.actions.v2.orders.FoodItemExtension",
"options": [
{
"id": "sample_addon_offer_id_1",
"offerId": "https://www.exampleprovider.com/menu/item/addon/offer/id1",
"name": "Honey Mustard",
"price": {
"currencyCode": "USD"
},
"quantity": 1
},
{
"id": "sample_addon_offer_id_2",
"offerId": "https://www.exampleprovider.com/menu/item/addon/offer/id2",
"name": "BBQ Sauce",
"price": {
"currencyCode": "USD",
"nanos": 500000000
},
"quantity": 1,
"subOptions": [
{
"id": "10239138",
"offerId": "912391723",
"name": "Fries",
"price": {
"currencyCode": "USD",
"units": "2",
"nanos": 230000000
},
"quantity": 1
}
]
}
]
}
FoodItemOption
下表列出 FoodItemOption 類型的屬性：
| 屬性 | 類型 | 說明 | |
|---|---|---|---|
id |
String |
Google 指派的專屬 ID。傳送 FoodOrderError 或 AsyncOrderUpdateRequest 時，如果購物車中有多個 offerId 相同的項目，請使用這個欄位進行區分。 範例： |
|
offerId |
String |
商品的優惠 ID。 範例： |
|
name |
String |
選項名稱。 範例： |
|
price |
Money |
||
note |
String |
與選項相關的註解。 |
|
quantity |
Number |
如果選項是項目，則為項目數。 範例： |
|
subOptions |
List<FoodItemOption> |
選項的子選項 (如有)。 範例： |
|
以下範例顯示 FoodItemOption 元素：
範例 1
{
"id": "10293231",
"offerId": "1918491",
"name": "Honey Mustard",
"price": {
"currencyCode": "USD",
"units": "1",
"nanos": 250000000
},
"quantity": 5
}
範例 2
{
"id": "123166552",
"offerId": "912849184",
"name": "Make It A Meal",
"price": {
"currencyCode": "USD",
"units": "3",
"nanos": 730000000
},
"quantity": 1,
"subOptions": [
{
"id": "10239138",
"offerId": "912391723",
"name": "Fries",
"price": {
"currencyCode": "USD",
"units": "2",
"nanos": 230000000
},
"quantity": 1
},
{
"id": "57159183",
"offerId": "81837123",
"name": "Drink",
"price": {
"currencyCode": "USD",
"units": "3",
"nanos": 130000000
},
"quantity": 1
}
]
}
FoodOrderError
包含CheckoutResponse 中的錯誤詳細資料。
下表列出 FoodOrderError 類型的屬性：
| 屬性 | 類型 | 說明 | |
|---|---|---|---|
error |
Error |
必填。 |
|
id |
String |
這是商品層級錯誤的必填欄位。對於菜單項目，這是 Google 指派的 LineItem.id；對於加購商品，則是 FoodItemOption.id。 |
|
description |
String |
錯誤說明。這項說明是供內部記錄使用，不會向使用者顯示。 |
|
updatedPrice |
Money |
導致錯誤的商品新價格。只有在錯誤為「PRICE_CHANGED」時，才需要這個值。 |
|
availableQuantity |
整數 |
導致錯誤的商品新可用數量。只有在錯誤為「INVALID」或「NOT_FOUND」時，才需要提供這個屬性。如果是「INVALID」和「NOT_FOUND」，則值應為零。 |
|
以下範例顯示 FoodOrderError 元素：
範例 1
{
"error": "CLOSED",
"description": "This store is currently reachable. Please try again later."
}
範例 2
{
"error": "PRICE_CHANGED",
"id": "french_fries",
"description": "The price has changed.",
"updatedPrice": {
"currencyCode": "USD",
"units": "2",
"nanos": 750000000
}
}
FoodOrderExtension
包含訂單的執行資訊。
下表列出 FoodOrderExtension 類型的屬性：
| 屬性 | 類型 | 說明 | |
|---|---|---|---|
@type |
Const |
這個擴充功能的類型。這個欄位一律設為「type.googleapis.com/google.actions.v2.orders.FoodOrderExtension」。 值： |
|
availableFulfillmentOptions |
List<FulfillmentOption> |
代表訂單的可用出貨選項。 |
|
optinForRemarketing |
布林值 |
使用者要求加入行銷管道。根據預設，您必須取得使用者同意，才能傳送行銷內容。如果 optinForRemarketing 為 true，您可以訂閱使用者。如果 optinForRemarketing 為 false 或不存在，您必須在系統中維持訂閱狀態。使用者無法透過 Google 選擇退出，只能透過行銷管道提供的取消訂閱功能。這個旗標僅會出現在 SubmitOrderRequestMessage 中。 |
|
以下範例顯示 FoodOrderExtension 元素：
範例 1
{
"@type": "type.googleapis.com/google.actions.v2.orders.FoodOrderExtension",
"availableFulfillmentOptions": [
{
"fulfillmentInfo": {
"delivery": {
"deliveryTimeIso8601": "P0M"
}
},
"expiresAt": "2017-07-17T12:30:00Z"
}
]
}
範例 2
{
"@type": "type.googleapis.com/google.actions.v2.orders.FoodOrderExtension",
"availableFulfillmentOptions": [
{
"fulfillmentInfo": {
"pickup": {
"pickupTimeIso8601": "P0M"
}
},
"expiresAt": "2020-08-20T11:41:00Z"
}
],
"optinForRemarketing": true
}
FulfillmentOption
您可以透過以下方式使用FulfillmentOption 物件：
-
在
Checkout AppRequest和Submit AppRequest中，Cart.extension.fulfillmentPreference：儲存使用者的偏好設定 (外送或自取)。傳送結帳要求時，價格一律為 0。 -
在
Checkout AppResponse中，ProposedOrder.extension.availableFulfillmentOptions會定義一或多個提交選項 (目前僅支援一個選項)。您可以在ProposedOrder.otherItems中將預設選項指定為LineItem。FulfillmentOption的offerId應與ProposedOrder.otherItems中指定的LineItemID 相符。
下表列出 FulfillmentOption 類型的屬性：
| 屬性 | 類型 | 說明 | |
|---|---|---|---|
offerId |
String |
這個履行選項的專屬 ID (如果有的話)。 |
|
fulfillmentInfo |
FulfillmentOptionInfo |
必填。 |
|
expiresAt |
ISO 時間戳記 |
這個執行要求選項的到期時間。 |
|
price |
Money |
這個選項的費用。 |
|
以下範例顯示 FulfillmentOption 元素：
範例
{
"offerId": "offer5",
"fulfillmentInfo": {
"pickup": {
"pickupTimeIso8601": "P0M"
}
},
"expiresAt": "2019-05-02T00:00:00-07:00",
"price": {
"currencyCode": "USD",
"units": "5",
"nanos": 230000000
}
}
FulfillmentOptionInfo
定義與FulfillmentInfo 相關的資訊。下表列出 FulfillmentOptionInfo 類型的屬性：
| 屬性 | 類型 | 說明 | |
|---|---|---|---|
| 必須提供下列其中一個屬性組合。 | |||
delivery |
群組 1 | DeliveryInfo |
如果有的話，表示運送順序。 |
pickup |
群組 2 | PickupInfo |
如果存在，則表示取貨訂單。 |
圖片
下表列出 Image 類型的屬性：
| 屬性 | 類型 | 說明 | |
|---|---|---|---|
sourceUrl |
String | 必填。 圖片的網址。圖片至少應為 72x72 像素。為達最佳效果，請使用至少 216 x 216 像素的圖片。圖片大小必須小於 6 MB 且小於 6,400 萬像素。 |
|
LineItem
定義購物車內容 (Cart.lineItems) 或訂單的額外費用 (ProposedOrder.otherItems)。下表列出 LineItem 類型的屬性：
| 屬性 | 類型 | 說明 | |
|---|---|---|---|
id |
String |
就購物車中的商品而言 (ProposedOrder.cart.lineItems[0].id)，這是 Google 在建立訂單時建立的專屬 ID。針對 ProposedOrder 中的 LineItem (ProposedOrder.otherItems[0].id)，也就是用於新增運費和稅金等項目，ID 值是由供應商定義。舉例來說，購物車中含有兩項相同商品，但兩者有不同的製作說明 (例如兩個中型比薩，配料不同)。在這種情況下，兩個項目都具有相同的基本 offerId。當您傳送訂單更新要求，表示某項商品遭到拒絕時，請使用這個 ID 做為歧義解除器。換句話說，如果其中一個披薩因缺少特定配料而遭拒，ID 可協助 Google 判斷你所指的是訂單中的哪項商品。除了 otherItems 以外，這是必填欄位。 |
|
name |
String | 必填。 委刊項的名稱。這是向使用者顯示的字串，因此應盡可能使用句子大小寫 (例如「運費」、「服務費」、「稅金」)。這個欄位會截斷至使用者輸入的 100 個半形字元。 |
|
type |
LineItemType |
必填。 |
|
quantity |
整數 |
所含項目數量。不適用於 ProposedOrder.otherItems。 |
|
description |
String |
項目說明。 |
|
price |
Price |
必填。 商品的價格。這個值代表此委刊項所有商品或服務的總價 (也就是將所有加購商品的費用加總，再乘以數量)。舉例來說，如果商品價格為 $10 美元，數量為 3，則價格為 $30 美元。一個披薩的基本價格為 $5 美元，加購 $1 美元的配料，總價為 $6 美元。假設有兩個披薩 (數量 = 2)，基本價格為 $5 美元，每個額外項目的價格為 $1 美元，則總價為 $12 美元。每個 LineItem 都應有價格，即使價格為「0」也一樣。如果類型為 DISCOUNT，請將值指定為負值 (例如「-2」)。 |
|
subLines |
List<SublineNote> |
選用，僅在類型為「REGULAR」時有效。使用者可能會在結帳要求和提交訂單要求的這個欄位中，傳送商品相關的備註。請務必在提供備註時，確保商家收到備註。在要求中，這個值會以 subLines[0].note 的形式出現，這是在要求中出現時，這個欄位中唯一提供的值。 項目數量不得超過 1 個。 |
|
offerId |
String |
商品的 MenuItem 優惠 ID。不適用於 ProposedOrder.otherItems。 |
|
extension |
FoodItemExtension |
定義食品項目的加料。 |
|
以下範例顯示 LineItem 元素：
範例 1
{
"name": "New customer discount",
"price": {
"type": "ESTIMATE",
"amount": {
"currencyCode": "USD",
"units": "-5",
"nanos": -500000000
}
},
"type": "DISCOUNT"
}
範例 2
{
"name": "Pita Chips",
"type": "REGULAR",
"id": "sample_item_offer_id_1",
"offerId": "https://www.exampleprovider.com/menu/item/offer/id1",
"quantity": 1,
"price": {
"type": "ESTIMATE",
"amount": {
"currencyCode": "USD",
"units": "2",
"nanos": 750000000
}
},
"subLines": [
{
"note": "Notes for this item."
}
],
"extension": {
"@type": "type.googleapis.com/google.actions.v2.orders.FoodItemExtension",
"options": [
{
"id": "sample_addon_offer_id_1",
"offerId": "https://www.exampleprovider.com/menu/item/addon/offer/id1",
"name": "Honey Mustard",
"price": {
"currencyCode": "USD"
},
"quantity": 1
},
{
"id": "sample_addon_offer_id_2",
"offerId": "https://www.exampleprovider.com/menu/item/addon/offer/id2",
"name": "BBQ Sauce",
"price": {
"currencyCode": "USD",
"nanos": 500000000
},
"quantity": 1
}
]
}
}
LineItemType
LineItemType 類型可用的值如下：
REGULAR：商品明細。適用於 Cart.lineItems。TAX：稅金明細項目。適用於 ProposedOrder.otherItems。DISCOUNT：折扣明細。請注意，價格應為負數。適用於 ProposedOrder.otherItems。GRATUITY：小費委刊項。通常是為使用者選取的小費保留給 SubmitOrderRequestMessage。適用於 ProposedOrder.otherItems。DELIVERY：放送委刊項。適用於 ProposedOrder.otherItems。SUBTOTAL：小計明細。適用於 ProposedOrder.otherItems。FEE：其他類型未涵蓋的其他委刊項。適用於 ProposedOrder.otherItems。
位置
指定訂餐地址。Location 類型用於 Cart，僅用於表示運送訂單的目的地。如果使用者下單，系統也會在 TransactionDecisionValue 中顯示最終位置。如果訂單指定自取，則完全不會納入位置 (空白位置也不例外)。
下表列出 Location 類型的屬性：
| 屬性 | 類型 | 說明 | |
|---|---|---|---|
coordinates |
Coordinates |
||
formattedAddress |
String |
顯示地點的地址。 範例： |
|
postalAddress |
PostalAddress |
||
zipCode |
String |
範例： |
|
city |
String |
城市名稱。 範例： |
|
notes |
String |
關於地點的附註，例如門禁密碼。長度不得超過 500 個字元。 範例： |
|
以下範例顯示 Location 元素：
範例
{
"coordinates": {
"latitude": 37.788783,
"longitude": -122.41384
},
"formattedAddress": "1350 CHARLESTON ROAD, MOUNTAIN VIEW, CA, United States",
"zipCode": "94043",
"city": "Mountain View",
"postalAddress": {
"regionCode": "US",
"postalCode": "94043",
"administrativeArea": "CA",
"locality": "Mountain View",
"addressLines": [
"1350 Charleston Road"
]
},
"notes": "Gate code is #111"
}
商家
下表列出 Merchant 類型的屬性：
| 屬性 | 類型 | 說明 | |
|---|---|---|---|
id |
String |
商家 ID。如果指定，則會與餐廳動態饋給中的 Restaurant.@id 相符。 範例： |
|
name |
String | 必填。 使用者可查看的商家名稱。 範例： |
|
以下範例顯示 Merchant 元素：
範例
{
"id": "https://www.exampleprovider.com/merchant/id1",
"name": "Falafel Bite"
}
金額
下表列出 Money 類型的屬性：
| 屬性 | 類型 | 說明 | |
|---|---|---|---|
currencyCode |
String | 必填。 以 ISO 4217 格式表示的 3 個英文字母貨幣代碼。 範例： |
|
units |
String |
金額的整數單位。舉例來說，如果 currencyCode 為「USD」，則「1」單位為 1 美元。 範例： |
|
nanos |
整數 |
金額的十億分之一 (10^-9) 單位數量。這個值必須介於 -999,999,999 和 +999,999,999 (含) 之間。請遵守下列規則：如果 units 為正值，nanos 必須為正值或零；如果 units 為零，則 nanos 可為正值、零或負值；如果 units 為負值，nanos 就必須為負值或零。例如，$-1.75 美元的表記方式為 units = -1 和 nanos = -750,000,000。 範例： |
|
以下範例顯示 Money 元素：
範例 1
{
"currencyCode": "USD",
"units": "36",
"nanos": 730000000
}
範例 2
{
"currencyCode": "EUR",
"units": "10"
}
訂單
包含最終訂單，包括稅金、費用和運費，以及付款資訊。您的Submit AppRequest 會接收這個物件。下表列出 Order 類型的屬性：
| 屬性 | 類型 | 說明 | |
|---|---|---|---|
finalOrder |
ProposedOrder |
必填。 導致訂單產生的提案訂單。 |
|
googleOrderId |
String | 必填。 Google 指派的訂單 ID。這個 ID 應在訂單的整個生命週期中保持穩定。使用者不會看到這個 ID。 |
|
orderDate |
ISO 時間戳記 | 必填。 訂單建立的日期和時間。 |
|
paymentInfo |
PaymentInfo |
必填。 與這筆訂單付款相關的付款資訊。 |
|
以下範例顯示 Order 元素：
範例
{
"finalOrder": {
"cart": {
"notes": "Guest prefers their food to be hot when it is delivered.",
"merchant": {
"id": "https://www.exampleprovider.com/merchant/id1",
"name": "Cucina Venti"
},
"lineItems": [
{
"name": "Sizzling Prawns Dinner",
"type": "REGULAR",
"id": "sample_item_offer_id_1",
"offerId": "https://www.exampleprovider.com/menu/item/offer/id1",
"quantity": 1,
"price": {
"type": "ESTIMATE",
"amount": {
"currencyCode": "USD",
"units": "16",
"nanos": 750000000
}
},
"subLines": [
{
"note": "Notes for this item."
}
],
"extension": {
"@type": "type.googleapis.com/google.actions.v2.orders.FoodItemExtension",
"options": [
{
"id": "sample_addon_offer_id_1",
"offerId": "https://www.exampleprovider.com/menu/item/addon/offer/id1",
"name": "Honey Mustard",
"price": {
"currencyCode": "USD"
},
"quantity": 1
},
{
"id": "sample_addon_offer_id_2",
"offerId": "https://www.exampleprovider.com/menu/item/addon/offer/id2",
"name": "BBQ Sauce",
"price": {
"currencyCode": "USD",
"nanos": 500000000
},
"quantity": 1
}
]
}
}
],
"extension": {
"@type": "type.googleapis.com/google.actions.v2.orders.FoodCartExtension",
"fulfillmentPreference": {
"fulfillmentInfo": {
"pickup": {
"pickupTimeIso8601": "P0M"
}
}
},
"contact": {
"displayName": "Lovefood Ordering",
"email": "ilovefood@example.com",
"phoneNumber": "+16501234567"
}
}
},
"otherItems": [
{
"name": "Service fee",
"type": "FEE",
"price": {
"type": "ESTIMATE",
"amount": {
"currencyCode": "USD",
"units": "3",
"nanos": 500000000
}
}
},
{
"name": "Tax",
"type": "TAX",
"price": {
"type": "ESTIMATE",
"amount": {
"currencyCode": "USD",
"units": "1",
"nanos": 370000000
}
}
},
{
"name": "Tip",
"type": "GRATUITY",
"price": {
"type": "ESTIMATE",
"amount": {
"currencyCode": "USD",
"units": "2",
"nanos": 590000000
}
}
}
],
"totalPrice": {
"type": "ESTIMATE",
"amount": {
"currencyCode": "USD",
"units": "23",
"nanos": 710000000
}
},
"id": "sample_final_order_id",
"extension": {
"@type": "type.googleapis.com/google.actions.v2.orders.FoodOrderExtension",
"availableFulfillmentOptions": [
{
"fulfillmentInfo": {
"pickup": {
"pickupTimeIso8601": "P0M"
}
},
"expiresAt": "2017-07-17T12:30:00Z"
}
],
"optinForRemarketing": true
}
},
"googleOrderId": "sample_google_order_id",
"orderDate": "2017-07-17T12:00:00Z",
"paymentInfo": {
"displayName": "Visa\u2006****\u20061111",
"googleProvidedPaymentInstrument": {
"instrumentToken": "abcd"
},
"paymentType": "PAYMENT_CARD"
}
}
OrderUpdate
下表說明AppResponse 中包含的 OrderUpdate 類型欄位。下表列出 OrderUpdate 類型的屬性：
| 屬性 | 類型 | 說明 | |
|---|---|---|---|
actionOrderId |
String | 必填。 整合服務供應商系統中訂單的專屬 ID，用於識別要傳送更新的訂單。如果在「CREATED」訂單的 OrderUpdate 中，至少未提供一次 receipt.user_visible_order_id，則這個 ID 會是 Google 訂單資訊卡中顯示的輸入使用者可見 ID。 |
|
orderState |
OrderState |
必填。 訂單的新狀態。 |
|
lineItemUpdates |
Map<String, LineItemUpdate> |
||
updateTime |
ISO 時間戳記 | 必填。 更新訂單的時間。 |
|
orderManagementActions |
List<OrderManagementAction> |
訂單後續動作，例如聯絡支援團隊和查看訂單詳細資料。 必須包含至少 1 個項目，且最多 6 個項目。 |
|
rejectionInfo |
RejectionInfo |
|
|
cancellationInfo |
CancellationInfo |
|
|
inTransitInfo |
InTransitInfo |
這個欄位已淘汰。 |
|
fulfillmentInfo |
FulfillmentInfo |
這個欄位已淘汰。 |
|
receipt |
Receipt |
在收據中提供可供使用者查看的訂單 ID。 |
|
totalPrice |
Price |
訂單總價。 |
|
infoExtension |
FoodOrderUpdateExtension |
定義訂單更新的更多詳細資料，例如預估送達或取貨的間隔。 |
|
以下範例顯示 OrderUpdate 元素：
範例
{
"actionOrderId": "sample_action_order_id",
"orderState": {
"state": "CONFIRMED",
"label": "Provider confirmed"
},
"totalPrice": {
"type": "ESTIMATE",
"amount": {
"currencyCode": "USD",
"units": "41",
"nanos": 600000000
}
},
"lineItemUpdates": {
"sample_item_id_1": {
"price": {
"type": "ESTIMATE",
"amount": {
"currencyCode": "USD",
"units": "3",
"nanos": 500000000
}
},
"reason": "This item has an updated price."
}
},
"receipt": {
"userVisibleOrderId": "userVisibleId1234"
},
"updateTime": "2017-07-17T12:00:00Z",
"orderManagementActions": [
{
"type": "CUSTOMER_SERVICE",
"button": {
"title": "Contact customer service",
"openUrlAction": {
"url": "mailto:support@example.com"
}
}
},
{
"type": "EMAIL",
"button": {
"title": "Email restaurant",
"openUrlAction": {
"url": "mailto:person@example.com"
}
}
},
{
"type": "CALL_RESTAURANT",
"button": {
"title": "Call restaurant",
"openUrlAction": {
"url": "tel:+16505554679"
}
}
}
],
"infoExtension": {
"@type": "type.googleapis.com/google.actions.v2.orders.FoodOrderUpdateExtension",
"estimatedFulfillmentTimeIso8601": "2017-07-17T13:00:00Z/2017-07-17T13:30:00Z"
}
}
PickupInfo
下表列出 PickupInfo 類型的屬性：
| 屬性 | 類型 | 說明 | |
|---|---|---|---|
pickupTimeIso8601 |
String |
預估上車時間，格式為 ISO 8601 時間戳記格式：「{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z」或時間長度格式：「P(n)Y(n)M(n)DT(n)H(n)M(n)S」。舉例來說，PT90M 代表 90 分鐘的時間長度。預設值「PT0M」表示偏好的上車時間是盡快。參考資料：https://en.wikipedia.org/wiki/ISO_8601#Combined_date_and_time_representations. 在結帳回應中使用此參數，更新預估上車時間。 範例： |
|
以下範例顯示 PickupInfo 元素：
範例
{
"pickupTimeIso8601": "PT90M"
}
PostalAddress
下表列出 PostalAddress 類型的屬性：
| 屬性 | 類型 | 說明 | |
|---|---|---|---|
regionCode |
String | 必填。 包含兩個英文字母的國家/地區代碼。 範例： |
|
postalCode |
String |
郵遞區號。 範例： |
|
administrativeArea |
String |
最高行政區，用於國家/地區的郵遞地址。例如州、省或縣。 範例： |
|
locality |
String |
這個地點的城市或城鎮。如為未明確定義縣市或其縣市不適用此結構的地區，請不要指定縣市，改用 addressLines 欄位。 範例： |
|
addressLines |
List<String> |
一或多行可用來指定街道地址。這個欄位可能包含不清楚的地區，因此不應修改。 範例： |
|
recipients |
List<String> |
訂單的收件者清單。這個欄位僅適用於 billingAddress。 |
|
以下範例顯示 PostalAddress 元素：
範例
{
"regionCode": "US",
"postalCode": "94043",
"administrativeArea": "CA",
"locality": "Mountain View",
"addressLines": [
"1350 Charleston Road"
]
}
價格
下表列出 Price 類型的屬性：
| 屬性 | 類型 | 說明 | |
|---|---|---|---|
type |
Enum [
"ESTIMATE",
"ACTUAL"
] |
必填。 促銷優待券代碼。 |
|
amount |
Money |
必填。 |
|
宣傳
下表列出 Promotion 類型的屬性：
| 屬性 | 類型 | 說明 | |
|---|---|---|---|
coupon |
String | 必填。 促銷優待券代碼。 |
|
ProposedOrder
下表列出 ProposedOrder 類型的屬性：
| 屬性 | 類型 | 說明 | |
|---|---|---|---|
id |
String |
建議訂單的選用 ID。 |
|
cart |
Cart |
必填。 使用者的商品。 |
|
otherItems |
List<LineItem> |
供應商新增的項目，例如運費、其他費用和稅金。otherItems 也可能包含使用者新增的小費和/或折扣。 最多只能包含 10 個項目。 |
|
image |
Image |
與提案訂單相關聯的圖片。 |
|
totalPrice |
Price |
必填。 提案訂單的總價。 |
|
extension |
FoodOrderExtension |
必填。 定義餐點訂單的履行資訊。 |
|
disclaimers |
List<Disclaimer> |
對應至在下單前，會在 UI 中顯示的免責事項訊息。 |
|
以下範例顯示 ProposedOrder 元素：
範例
{
"id": "sample_proposed_order_id_1",
"otherItems": [
{
"name": "New customer discount",
"price": {
"type": "ESTIMATE",
"amount": {
"currencyCode": "USD",
"units": "-5",
"nanos": -500000000
}
},
"type": "DISCOUNT"
},
{
"name": "Delivery fee",
"price": {
"type": "ESTIMATE",
"amount": {
"currencyCode": "USD",
"units": "3",
"nanos": 500000000
}
},
"type": "DELIVERY"
},
{
"name": "Tax",
"price": {
"type": "ESTIMATE",
"amount": {
"currencyCode": "USD",
"units": "1",
"nanos": 500000000
}
},
"type": "TAX"
}
],
"cart": {
"merchant": {
"id": "https://www.exampleprovider.com/merchant/id1",
"name": "Falafel Bite"
},
"lineItems": [
{
"name": "Pita Chips",
"type": "REGULAR",
"id": "sample_item_offer_id_1",
"offerId": "https://www.exampleprovider.com/menu/item/offer/id1",
"quantity": 1,
"price": {
"type": "ESTIMATE",
"amount": {
"currencyCode": "USD",
"units": "2",
"nanos": 750000000
}
},
"subLines": [
{
"note": "Notes for this item."
}
],
"extension": {
"@type": "type.googleapis.com/google.actions.v2.orders.FoodItemExtension",
"options": [
{
"id": "sample_addon_offer_id_1",
"offerId": "https://www.exampleprovider.com/menu/item/addon/offer/id1",
"name": "Honey Mustard",
"price": {
"currencyCode": "USD"
},
"quantity": 1
},
{
"id": "sample_addon_offer_id_2",
"offerId": "https://www.exampleprovider.com/menu/item/addon/offer/id2",
"name": "BBQ Sauce",
"price": {
"currencyCode": "USD",
"nanos": 500000000
},
"quantity": 1
}
]
}
},
{
"name": "Chicken Shwarma Wrap",
"type": "REGULAR",
"id": "sample_item_offer_id_2",
"offerId": "https://www.exampleprovider.com/menu/item/offer/id2",
"quantity": 1,
"price": {
"type": "ESTIMATE",
"amount": {
"currencyCode": "USD",
"units": "8"
}
},
"extension": {
"@type": "type.googleapis.com/google.actions.v2.orders.FoodItemExtension"
}
},
{
"name": "Greek Salad",
"type": "REGULAR",
"id": "sample_item_offer_id_3",
"offerId": "https://www.exampleprovider.com/menu/item/offer/id3",
"quantity": 1,
"price": {
"type": "ESTIMATE",
"amount": {
"currencyCode": "USD",
"units": "9",
"nanos": 990000000
}
},
"extension": {
"@type": "type.googleapis.com/google.actions.v2.orders.FoodItemExtension"
}
},
{
"name": "Prawns Biryani",
"type": "REGULAR",
"id": "sample_item_offer_id_4",
"offerId": "https://www.exampleprovider.com/menu/item/offer/id4",
"quantity": 1,
"price": {
"type": "ESTIMATE",
"amount": {
"currencyCode": "USD",
"units": "15",
"nanos": 990000000
}
},
"extension": {
"@type": "type.googleapis.com/google.actions.v2.orders.FoodItemExtension"
}
}
],
"extension": {
"@type": "type.googleapis.com/google.actions.v2.orders.FoodCartExtension",
"fulfillmentPreference": {
"fulfillmentInfo": {
"delivery": {
"deliveryTimeIso8601": "P90M"
}
}
},
"location": {
"coordinates": {
"latitude": 37.788783,
"longitude": -122.41384
},
"formattedAddress": "1350 CHARLESTON ROAD, MOUNTAIN VIEW, CA, United States",
"zipCode": "94043",
"city": "Mountain View",
"postalAddress": {
"regionCode": "US",
"postalCode": "94043",
"administrativeArea": "CA",
"locality": "Mountain View",
"addressLines": [
"1350 Charleston Road"
]
},
"notes": "Gate code is #111"
}
}
},
"totalPrice": {
"type": "ESTIMATE",
"amount": {
"currencyCode": "USD",
"units": "36",
"nanos": 730000000
}
},
"extension": {
"@type": "type.googleapis.com/google.actions.v2.orders.FoodOrderExtension",
"availableFulfillmentOptions": [
{
"fulfillmentInfo": {
"delivery": {
"deliveryTimeIso8601": "P0M"
}
},
"expiresAt": "2017-07-17T12:30:00Z"
}
]
}
}
SublineNote
下表列出 SublineNote 類型的屬性：
| 屬性 | 類型 | 說明 | |
|---|---|---|---|
note |
String | 必填。 |
|
時間戳記
日期和時間，格式如下：
"{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z"
TransactionDecisionValue
包含Order。下表列出 TransactionDecisionValue 類型的屬性：
| 屬性 | 類型 | 說明 | |
|---|---|---|---|
order |
Order |
必填。 要下單的訂單，並附上付款詳細資料。 |
|
以下範例顯示 TransactionDecisionValue 元素：
範例
{
"order": {
"finalOrder": {
"cart": {
"notes": "Guest prefers their food to be hot when it is delivered.",
"merchant": {
"id": "https://www.exampleprovider.com/merchant/id1",
"name": "Cucina Venti"
},
"lineItems": [
{
"name": "Sizzling Prawns Dinner",
"type": "REGULAR",
"id": "sample_item_offer_id_1",
"offerId": "https://www.exampleprovider.com/menu/item/offer/id1",
"quantity": 1,
"price": {
"type": "ESTIMATE",
"amount": {
"currencyCode": "USD",
"units": "16",
"nanos": 750000000
}
},
"subLines": [
{
"note": "Notes for this item."
}
],
"extension": {
"@type": "type.googleapis.com/google.actions.v2.orders.FoodItemExtension",
"options": [
{
"id": "sample_addon_offer_id_1",
"offerId": "https://www.exampleprovider.com/menu/item/addon/offer/id1",
"name": "Honey Mustard",
"price": {
"currencyCode": "USD"
},
"quantity": 1
},
{
"id": "sample_addon_offer_id_2",
"offerId": "https://www.exampleprovider.com/menu/item/addon/offer/id2",
"name": "BBQ Sauce",
"price": {
"currencyCode": "USD",
"nanos": 500000000
},
"quantity": 1
}
]
}
}
],
"extension": {
"@type": "type.googleapis.com/google.actions.v2.orders.FoodCartExtension",
"fulfillmentPreference": {
"fulfillmentInfo": {
"pickup": {
"pickupTimeIso8601": "P0M"
}
}
},
"contact": {
"displayName": "Lovefood Ordering",
"email": "ilovefood@example.com",
"phoneNumber": "+16501234567"
}
}
},
"otherItems": [
{
"name": "Service fee",
"type": "FEE",
"price": {
"type": "ESTIMATE",
"amount": {
"currencyCode": "USD",
"units": "3",
"nanos": 500000000
}
}
},
{
"name": "Tax",
"type": "TAX",
"price": {
"type": "ESTIMATE",
"amount": {
"currencyCode": "USD",
"units": "1",
"nanos": 370000000
}
}
},
{
"name": "Tip",
"type": "GRATUITY",
"price": {
"type": "ESTIMATE",
"amount": {
"currencyCode": "USD",
"units": "2",
"nanos": 590000000
}
}
}
],
"totalPrice": {
"type": "ESTIMATE",
"amount": {
"currencyCode": "USD",
"units": "23",
"nanos": 710000000
}
},
"id": "sample_final_order_id",
"extension": {
"@type": "type.googleapis.com/google.actions.v2.orders.FoodOrderExtension",
"availableFulfillmentOptions": [
{
"fulfillmentInfo": {
"pickup": {
"pickupTimeIso8601": "P0M"
}
},
"expiresAt": "2017-07-17T12:30:00Z"
}
],
"optinForRemarketing": true
}
},
"googleOrderId": "sample_google_order_id",
"orderDate": "2017-07-17T12:00:00Z",
"paymentInfo": {
"displayName": "Visa\u2006****\u20061111",
"googleProvidedPaymentInstrument": {
"instrumentToken": "abcd"
},
"paymentType": "PAYMENT_CARD"
}
}
}
履行要求
AppRequest
下表列出 AppRequest 類型的屬性：
| 屬性 | 類型 | 說明 | |
|---|---|---|---|
isInSandbox |
布林值 |
指出後續交易是否在沙箱環境中完成。 |
|
conversation |
Conversation |
||
inputs |
List<Input> |
必填。 包含結帳購物車的預期引數。 必須有 1 個項目。 |
|
以下範例顯示 AppRequest 元素：
範例 1
{
"isInSandbox": true,
"inputs": [
{
"intent": "actions.foodordering.intent.CHECKOUT",
"arguments": [
{
"extension": {
"@type": "type.googleapis.com/google.actions.v2.orders.Cart",
"merchant": {
"id": "https://www.exampleprovider.com/merchant/id1",
"name": "Cucina Venti"
},
"lineItems": [
{
"name": "Sizzling Prawns Dinner",
"type": "REGULAR",
"id": "sample_item_offer_id_1",
"offerId": "https://www.exampleprovider.com/menu/item/offer/id1",
"quantity": 1,
"price": {
"type": "ESTIMATE",
"amount": {
"currencyCode": "USD",
"units": "16",
"nanos": 750000000
}
},
"subLines": [
{
"note": "Notes for this item."
}
],
"extension": {
"@type": "type.googleapis.com/google.actions.v2.orders.FoodItemExtension",
"options": [
{
"id": "sample_addon_offer_id_1",
"offerId": "https://www.exampleprovider.com/menu/item/addon/offer/id1",
"name": "Honey Mustard",
"price": {
"currencyCode": "USD"
},
"quantity": 1
},
{
"id": "sample_addon_offer_id_2",
"offerId": "https://www.exampleprovider.com/menu/item/addon/offer/id2",
"name": "BBQ Sauce",
"price": {
"currencyCode": "USD",
"nanos": 500000000
},
"quantity": 1
}
]
}
}
],
"extension": {
"@type": "type.googleapis.com/google.actions.v2.orders.FoodCartExtension",
"fulfillmentPreference": {
"fulfillmentInfo": {
"delivery": {
"deliveryTimeIso8601": "P0M"
}
}
},
"location": {
"coordinates": {
"latitude": 37.788783,
"longitude": -122.41384
},
"formattedAddress": "1350 CHARLESTON ROAD, MOUNTAIN VIEW, CA, United States",
"zipCode": "94043",
"city": "Mountain View",
"postalAddress": {
"regionCode": "US",
"postalCode": "94043",
"administrativeArea": "CA",
"locality": "Mountain View",
"addressLines": [
"1350 Charleston Road"
]
},
"notes": "Gate code is #111"
}
}
}
}
]
}
]
}
範例 2
{
"isInSandbox": true,
"inputs": [
{
"intent": "actions.intent.TRANSACTION_DECISION",
"arguments": [
{
"transactionDecisionValue": {
"order": {
"finalOrder": {
"cart": {
"notes": "Guest prefers their food to be hot when it is delivered.",
"merchant": {
"id": "https://www.exampleprovider.com/merchant/id1",
"name": "Cucina Venti"
},
"lineItems": [
{
"name": "Sizzling Prawns Dinner",
"type": "REGULAR",
"id": "sample_item_offer_id_1",
"offerId": "https://www.exampleprovider.com/menu/item/offer/id1",
"quantity": 1,
"price": {
"type": "ESTIMATE",
"amount": {
"currencyCode": "USD",
"units": "16",
"nanos": 750000000
}
},
"subLines": [
{
"note": "Notes for this item."
}
],
"extension": {
"@type": "type.googleapis.com/google.actions.v2.orders.FoodItemExtension",
"options": [
{
"id": "sample_addon_offer_id_1",
"offerId": "https://www.exampleprovider.com/menu/item/addon/offer/id1",
"name": "Honey Mustard",
"price": {
"currencyCode": "USD"
},
"quantity": 1
},
{
"id": "sample_addon_offer_id_2",
"offerId": "https://www.exampleprovider.com/menu/item/addon/offer/id2",
"name": "BBQ Sauce",
"price": {
"currencyCode": "USD",
"nanos": 500000000
},
"quantity": 1
}
]
}
}
],
"extension": {
"@type": "type.googleapis.com/google.actions.v2.orders.FoodCartExtension",
"fulfillmentPreference": {
"fulfillmentInfo": {
"pickup": {
"pickupTimeIso8601": "P0M"
}
}
},
"contact": {
"displayName": "Lovefood Ordering",
"email": "ilovefood@example.com",
"phoneNumber": "+16501234567"
}
}
},
"otherItems": [
{
"name": "Service fee",
"type": "FEE",
"price": {
"type": "ESTIMATE",
"amount": {
"currencyCode": "USD",
"units": "3",
"nanos": 500000000
}
}
},
{
"name": "Tax",
"type": "TAX",
"price": {
"type": "ESTIMATE",
"amount": {
"currencyCode": "USD",
"units": "1",
"nanos": 370000000
}
}
},
{
"name": "Tip",
"type": "GRATUITY",
"price": {
"type": "ESTIMATE",
"amount": {
"currencyCode": "USD",
"units": "2",
"nanos": 590000000
}
}
}
],
"totalPrice": {
"type": "ESTIMATE",
"amount": {
"currencyCode": "USD",
"units": "23",
"nanos": 710000000
}
},
"id": "sample_final_order_id",
"extension": {
"@type": "type.googleapis.com/google.actions.v2.orders.FoodOrderExtension",
"availableFulfillmentOptions": [
{
"fulfillmentInfo": {
"pickup": {
"pickupTimeIso8601": "P0M"
}
},
"expiresAt": "2017-07-17T12:30:00Z"
}
],
"optinForRemarketing": true
}
},
"googleOrderId": "sample_google_order_id",
"orderDate": "2017-07-17T12:00:00Z",
"paymentInfo": {
"displayName": "Visa\u2006****\u20061111",
"googleProvidedPaymentInstrument": {
"instrumentToken": "abcd"
},
"paymentType": "PAYMENT_CARD"
}
}
}
}
]
}
]
}
CheckoutRequestMessage
CheckoutRequestMessage 是具有 actions.foodordering.intent.CHECKOUT 意圖的 AppRequest。SubmitOrderRequestMessage
SubmitOrderRequestMessage 是具有 actions.foodordering.intent.TRANSACTION_DECISION 意圖的 AppRequest。對話
Conversation 只會出現在一個工作階段。您可以視需要使用此方法連結多個 Checkout 和 SubmitOrder 動作。下表列出 Conversation 類型的屬性：
| 屬性 | 類型 | 說明 | |
|---|---|---|---|
conversationId |
String | 必填。 對話的專屬 ID。 |
|
以下範例顯示 Conversation 元素：
範例
{
"conversationId": "CQnJ7Z4i7UmvEZ9ph3AxyZRJ"
}
輸入
結帳時應使用的引數。
下表列出 Input 類型的屬性：
| 屬性 | 類型 | 說明 | |
|---|---|---|---|
intent |
Enum [
"actions.foodordering.intent.CHECKOUT",
"actions.intent.TRANSACTION_DECISION"
] |
必填。 如要傳送結帳要求訊息，請將其設為「actions.foodordering.intent.CHECKOUT」；如要傳送提交訂單要求訊息，請設為「actions.intent.TRANSACTION_DECISION」。 |
|
arguments |
List<Argument> |
必填。 包含要結帳的購物車或要下單的訂單 必須有 1 個項目。 |
|
引數
包含使用者想結帳的餐點詳細資料。結帳時，只能使用額外資訊。如要提交訂單，請使用 transactionDecisionValue
下表列出 Argument 類型的屬性：
| 屬性 | 類型 | 說明 | |
|---|---|---|---|
| 必須提供下列其中一個屬性組合。 | |||
extension |
群組 1 | Cart |
詳細說明使用者要結帳的餐點。 |
transactionDecisionValue |
群組 2 | TransactionDecisionValue |
包含要下單的訂單和付款詳細資料。 |
執行要求回應
AppResponse
下表列出 AppResponse 類型的屬性：
| 屬性 | 類型 | 說明 | |
|---|---|---|---|
expectUserResponse |
Const |
設為 false。 值： |
|
finalResponse |
FinalResponse |
必填。 包含你對購物車結帳的回應。 |
|
以下範例顯示 AppResponse 元素：
範例 1
{
"expectUserResponse": false,
"finalResponse": {
"richResponse": {
"items": [
{
"structuredResponse": {
"checkoutResponse": {
"proposedOrder": {
"id": "sample_proposed_order_id_1",
"otherItems": [
{
"name": "New customer discount",
"price": {
"type": "ESTIMATE",
"amount": {
"currencyCode": "USD",
"units": "-5",
"nanos": -500000000
}
},
"type": "DISCOUNT"
},
{
"name": "Delivery fee",
"price": {
"type": "ESTIMATE",
"amount": {
"currencyCode": "USD",
"units": "3",
"nanos": 500000000
}
},
"type": "DELIVERY"
},
{
"name": "Tax",
"price": {
"type": "ESTIMATE",
"amount": {
"currencyCode": "USD",
"units": "1",
"nanos": 500000000
}
},
"type": "TAX"
}
],
"cart": {
"merchant": {
"id": "https://www.exampleprovider.com/merchant/id1",
"name": "Falafel Bite"
},
"lineItems": [
{
"name": "Pita Chips",
"type": "REGULAR",
"id": "sample_item_offer_id_1",
"offerId": "https://www.exampleprovider.com/menu/item/offer/id1",
"quantity": 1,
"price": {
"type": "ESTIMATE",
"amount": {
"currencyCode": "USD",
"units": "2",
"nanos": 750000000
}
},
"subLines": [
{
"note": "Notes for this item."
}
],
"extension": {
"@type": "type.googleapis.com/google.actions.v2.orders.FoodItemExtension",
"options": [
{
"id": "sample_addon_offer_id_1",
"offerId": "https://www.exampleprovider.com/menu/item/addon/offer/id1",
"name": "Honey Mustard",
"price": {
"currencyCode": "USD"
},
"quantity": 1
},
{
"id": "sample_addon_offer_id_2",
"offerId": "https://www.exampleprovider.com/menu/item/addon/offer/id2",
"name": "BBQ Sauce",
"price": {
"currencyCode": "USD",
"nanos": 500000000
},
"quantity": 1
}
]
}
},
{
"name": "Chicken Shwarma Wrap",
"type": "REGULAR",
"id": "sample_item_offer_id_2",
"offerId": "https://www.exampleprovider.com/menu/item/offer/id2",
"quantity": 1,
"price": {
"type": "ESTIMATE",
"amount": {
"currencyCode": "USD",
"units": "8"
}
},
"extension": {
"@type": "type.googleapis.com/google.actions.v2.orders.FoodItemExtension"
}
},
{
"name": "Greek Salad",
"type": "REGULAR",
"id": "sample_item_offer_id_3",
"offerId": "https://www.exampleprovider.com/menu/item/offer/id3",
"quantity": 1,
"price": {
"type": "ESTIMATE",
"amount": {
"currencyCode": "USD",
"units": "9",
"nanos": 990000000
}
},
"extension": {
"@type": "type.googleapis.com/google.actions.v2.orders.FoodItemExtension"
}
},
{
"name": "Prawns Biryani",
"type": "REGULAR",
"id": "sample_item_offer_id_4",
"offerId": "https://www.exampleprovider.com/menu/item/offer/id4",
"quantity": 1,
"price": {
"type": "ESTIMATE",
"amount": {
"currencyCode": "USD",
"units": "15",
"nanos": 990000000
}
},
"extension": {
"@type": "type.googleapis.com/google.actions.v2.orders.FoodItemExtension"
}
}
],
"extension": {
"@type": "type.googleapis.com/google.actions.v2.orders.FoodCartExtension",
"fulfillmentPreference": {
"fulfillmentInfo": {
"delivery": {
"deliveryTimeIso8601": "P90M"
}
}
},
"location": {
"coordinates": {
"latitude": 37.788783,
"longitude": -122.41384
},
"formattedAddress": "1350 CHARLESTON ROAD, MOUNTAIN VIEW, CA, United States",
"zipCode": "94043",
"city": "Mountain View",
"postalAddress": {
"regionCode": "US",
"postalCode": "94043",
"administrativeArea": "CA",
"locality": "Mountain View",
"addressLines": [
"1350 Charleston Road"
]
},
"notes": "Gate code is #111"
}
}
},
"totalPrice": {
"type": "ESTIMATE",
"amount": {
"currencyCode": "USD",
"units": "36",
"nanos": 730000000
}
},
"extension": {
"@type": "type.googleapis.com/google.actions.v2.orders.FoodOrderExtension",
"availableFulfillmentOptions": [
{
"fulfillmentInfo": {
"delivery": {
"deliveryTimeIso8601": "P0M"
}
},
"expiresAt": "2017-07-17T12:30:00Z"
}
]
}
},
"paymentOptions": {
"googleProvidedOptions": {
"facilitationSpecification": "{\"apiVersion\": 2,\"apiVersionMinor\": 0,\"merchantInfo\": { \"merchantId\": \"Merchant ID\", \"merchantName\": \"Merchant Name\"},\"allowedPaymentMethods\": [ { \"type\": \"CARD\", \"parameters\": { \"allowedAuthMethods\": [ \"PAN_ONLY\" ], \"allowedCardNetworks\": [ \"VISA\", \"AMEX\", \"MASTERCARD\" ], \"billingAddressRequired\": false }, \"tokenizationSpecification\": { \"type\": \"PAYMENT_GATEWAY\", \"parameters\": { \"stripe:publishableKey\": \"pk_test_OoPcJNnxI1rDXhBq8BiXO2wz00s1Xc92dA\", \"gateway\": \"stripe\", \"stripe:version\": \"2019-05-16\" } } }],\"transactionInfo\": { \"currencyCode\": \"AUD\", \"totalPriceStatus\": \"ESTIMATED\", \"totalPrice\": \"1.0\"}}"
}
},
"additionalPaymentOptions": [
{
"actionProvidedOptions": {
"paymentType": "ON_FULFILLMENT",
"displayName": "Cash on delivery."
}
}
]
}
}
}
]
}
}
}
範例 2
{
"expectUserResponse": false,
"finalResponse": {
"richResponse": {
"items": [
{
"structuredResponse": {
"orderUpdate": {
"actionOrderId": "sample_action_order_id",
"orderState": {
"state": "CONFIRMED",
"label": "Provider confirmed"
},
"receipt": {
"userVisibleOrderId": "userVisibleId1234"
},
"updateTime": "2017-07-17T12:00:00Z",
"orderManagementActions": [
{
"type": "CUSTOMER_SERVICE",
"button": {
"title": "Contact customer service",
"openUrlAction": {
"url": "mailto:support@example.com"
}
}
},
{
"type": "CUSTOMER_SERVICE",
"button": {
"title": "Call customer service",
"openUrlAction": {
"url": "tel:+18005554679"
}
}
},
{
"type": "EMAIL",
"button": {
"title": "Email restaurant",
"openUrlAction": {
"url": "mailto:person@example.com"
}
}
},
{
"type": "CALL_RESTAURANT",
"button": {
"title": "Call restaurant",
"openUrlAction": {
"url": "tel:+16505554679"
}
}
}
],
"infoExtension": {
"@type": "type.googleapis.com/google.actions.v2.orders.FoodOrderUpdateExtension",
"estimatedFulfillmentTimeIso8601": "2017-07-17T13:00:00Z/2017-07-17T13:30:00Z"
}
}
}
}
]
}
}
}
範例 3
{
"expectUserResponse": false,
"finalResponse": {
"richResponse": {
"items": [
{
"structuredResponse": {
"error": {
"@type": "type.googleapis.com/google.actions.v2.orders.FoodErrorExtension",
"foodOrderErrors": [
{
"error": "CLOSED",
"description": "The restaurant is closed."
}
]
}
}
}
]
}
}
}
示例 4
{
"expectUserResponse": false,
"finalResponse": {
"richResponse": {
"items": [
{
"structuredResponse": {
"checkoutResponse": {
"proposedOrder": {
"otherItems": [
{
"name": "Delivery Fees",
"subLines": [],
"price": {
"type": "ESTIMATE",
"amount": {
"currencyCode": "USD",
"units": "3",
"nanos": 500000000
}
},
"type": "DELIVERY"
},
{
"name": "Tax",
"subLines": [],
"price": {
"type": "ESTIMATE",
"amount": {
"currencyCode": "USD",
"units": "1",
"nanos": 370000000
}
},
"type": "TAX"
},
{
"name": "Promotion",
"subLines": [],
"price": {
"type": "ESTIMATE",
"amount": {
"currencyCode": "USD",
"units": "-5",
"nanos": 0
}
},
"id": "OWG_ACTIVE_CODE",
"type": "DISCOUNT"
}
],
"cart": {
"merchant": {
"id": "https://www.exampleprovider.com/merchant/id1",
"name": "Falafel Bite"
},
"lineItems": [
{
"name": "Pita Chips",
"type": "REGULAR",
"id": "sample_item_offer_id_1",
"quantity": 1,
"price": {
"type": "ESTIMATE",
"amount": {
"currencyCode": "USD",
"units": "2",
"nanos": 750000000
}
},
"offerId": "https://www.exampleprovider.com/menu/item/addon/offer/id1",
"extension": {
"@type": "type.googleapis.com/google.actions.v2.orders.FoodItemExtension"
}
}
],
"promotions": [
{
"coupon": "OWG_ACTIVE_CODE"
}
],
"extension": {
"@type": "type.googleapis.com/google.actions.v2.orders.FoodCartExtension",
"fulfillmentPreference": {
"fulfillmentInfo": {
"pickup": {
"pickupTimeIso8601": "P0M"
}
}
}
}
},
"totalPrice": {
"type": "ESTIMATE",
"amount": {
"currencyCode": "USD",
"units": "14",
"nanos": 860000000
}
},
"extension": {
"@type": "type.googleapis.com/google.actions.v2.orders.FoodOrderExtension",
"availableFulfillmentOptions": [
{
"fulfillmentInfo": {
"pickup": {
"pickupTimeIso8601": "P0M"
}
},
"expiresAt": "2018-04-10T01:20:08.471Z"
}
]
}
},
"paymentOptions": {
"googleProvidedOptions": {
"tokenizationParameters": {
"tokenizationType": "PAYMENT_GATEWAY",
"parameters": {
"gateway": "stripe",
"stripe:publishableKey": "pk_live_stripe_client_key",
"stripe:version": "2017-04-06"
}
},
"supportedCardNetworks": [
"AMEX",
"DISCOVER",
"MASTERCARD",
"VISA",
"JCB"
],
"prepaidCardDisallowed": true,
"billingAddressRequired": true
}
}
}
}
}
]
}
}
}
CheckoutResponseMessage
CheckoutResponseMessage 是 AppResponse，在 StructuredResponse 中包含 checkoutResponse 或 error。SubmitOrderResponseMessage
SubmitOrderResponseMessage 是 AppResponse，在 StructuredResponse 中具有 orderUpdate。FinalResponse
您對購物車結帳或 SubmitOrderRequestMessage 的回應。
下表列出 FinalResponse 類型的屬性：
| 屬性 | 類型 | 說明 | |
|---|---|---|---|
richResponse |
RichResponse |
必填。 包含您對 CheckoutRequestMessage 或 SubmitOrderRequestMessage 的回應。 |
|
CheckoutResponse
下表列出 CheckoutResponse 類型的屬性：
| 屬性 | 類型 | 說明 | |
|---|---|---|---|
proposedOrder |
ProposedOrder |
必填。 建議用於交易的訂單。 |
|
paymentOptions |
PaymentOptions |
必填。 使用者選取的預設付款方式。 |
|
additionalPaymentOptions |
List<PaymentOptions> |
使用者可使用的其他付款方式。 |
|
以下範例顯示 CheckoutResponse 元素：
範例
{
"proposedOrder": {
"id": "sample_proposed_order_id_1",
"otherItems": [
{
"name": "New customer discount",
"price": {
"type": "ESTIMATE",
"amount": {
"currencyCode": "USD",
"units": "-5",
"nanos": -500000000
}
},
"type": "DISCOUNT"
},
{
"name": "Delivery fee",
"price": {
"type": "ESTIMATE",
"amount": {
"currencyCode": "USD",
"units": "3",
"nanos": 500000000
}
},
"type": "DELIVERY"
},
{
"name": "Tax",
"price": {
"type": "ESTIMATE",
"amount": {
"currencyCode": "USD",
"units": "1",
"nanos": 500000000
}
},
"type": "TAX"
}
],
"cart": {
"merchant": {
"id": "https://www.exampleprovider.com/merchant/id1",
"name": "Falafel Bite"
},
"lineItems": [
{
"name": "Pita Chips",
"type": "REGULAR",
"id": "sample_item_offer_id_1",
"offerId": "https://www.exampleprovider.com/menu/item/offer/id1",
"quantity": 1,
"price": {
"type": "ESTIMATE",
"amount": {
"currencyCode": "USD",
"units": "2",
"nanos": 750000000
}
},
"subLines": [
{
"note": "Notes for this item."
}
],
"extension": {
"@type": "type.googleapis.com/google.actions.v2.orders.FoodItemExtension",
"options": [
{
"id": "sample_addon_offer_id_1",
"offerId": "https://www.exampleprovider.com/menu/item/addon/offer/id1",
"name": "Honey Mustard",
"price": {
"currencyCode": "USD"
},
"quantity": 1
},
{
"id": "sample_addon_offer_id_2",
"offerId": "https://www.exampleprovider.com/menu/item/addon/offer/id2",
"name": "BBQ Sauce",
"price": {
"currencyCode": "USD",
"nanos": 500000000
},
"quantity": 1
}
]
}
},
{
"name": "Chicken Shwarma Wrap",
"type": "REGULAR",
"id": "sample_item_offer_id_2",
"offerId": "https://www.exampleprovider.com/menu/item/offer/id2",
"quantity": 1,
"price": {
"type": "ESTIMATE",
"amount": {
"currencyCode": "USD",
"units": "8"
}
},
"extension": {
"@type": "type.googleapis.com/google.actions.v2.orders.FoodItemExtension"
}
},
{
"name": "Greek Salad",
"type": "REGULAR",
"id": "sample_item_offer_id_3",
"offerId": "https://www.exampleprovider.com/menu/item/offer/id3",
"quantity": 1,
"price": {
"type": "ESTIMATE",
"amount": {
"currencyCode": "USD",
"units": "9",
"nanos": 990000000
}
},
"extension": {
"@type": "type.googleapis.com/google.actions.v2.orders.FoodItemExtension"
}
},
{
"name": "Prawns Biryani",
"type": "REGULAR",
"id": "sample_item_offer_id_4",
"offerId": "https://www.exampleprovider.com/menu/item/offer/id4",
"quantity": 1,
"price": {
"type": "ESTIMATE",
"amount": {
"currencyCode": "USD",
"units": "15",
"nanos": 990000000
}
},
"extension": {
"@type": "type.googleapis.com/google.actions.v2.orders.FoodItemExtension"
}
}
],
"extension": {
"@type": "type.googleapis.com/google.actions.v2.orders.FoodCartExtension",
"fulfillmentPreference": {
"fulfillmentInfo": {
"delivery": {
"deliveryTimeIso8601": "P90M"
}
}
},
"location": {
"coordinates": {
"latitude": 37.788783,
"longitude": -122.41384
},
"formattedAddress": "1350 CHARLESTON ROAD, MOUNTAIN VIEW, CA, United States",
"zipCode": "94043",
"city": "Mountain View",
"postalAddress": {
"regionCode": "US",
"postalCode": "94043",
"administrativeArea": "CA",
"locality": "Mountain View",
"addressLines": [
"1350 Charleston Road"
]
},
"notes": "Gate code is #111"
}
}
},
"totalPrice": {
"type": "ESTIMATE",
"amount": {
"currencyCode": "USD",
"units": "36",
"nanos": 730000000
}
},
"extension": {
"@type": "type.googleapis.com/google.actions.v2.orders.FoodOrderExtension",
"availableFulfillmentOptions": [
{
"fulfillmentInfo": {
"delivery": {
"deliveryTimeIso8601": "P0M"
}
},
"expiresAt": "2017-07-17T12:30:00Z"
}
]
}
},
"paymentOptions": {
"googleProvidedOptions": {
"facilitationSpecification": "{\"apiVersion\": 2,\"apiVersionMinor\": 0,\"merchantInfo\": { \"merchantId\": \"Merchant ID\", \"merchantName\": \"Merchant Name\"},\"allowedPaymentMethods\": [ { \"type\": \"CARD\", \"parameters\": { \"allowedAuthMethods\": [ \"PAN_ONLY\" ], \"allowedCardNetworks\": [ \"VISA\", \"AMEX\", \"MASTERCARD\" ], \"billingAddressRequired\": false }, \"tokenizationSpecification\": { \"type\": \"PAYMENT_GATEWAY\", \"parameters\": { \"stripe:publishableKey\": \"pk_test_OoPcJNnxI1rDXhBq8BiXO2wz00s1Xc92dA\", \"gateway\": \"stripe\", \"stripe:version\": \"2019-05-16\" } } }],\"transactionInfo\": { \"currencyCode\": \"AUD\", \"totalPriceStatus\": \"ESTIMATED\", \"totalPrice\": \"1.0\"}}"
}
},
"additionalPaymentOptions": [
{
"actionProvidedOptions": {
"paymentType": "ON_FULFILLMENT",
"displayName": "Cash on delivery."
}
}
]
}
項目
包含你對購物車結帳或 SubmitOrderRequestMessage 的回應。
下表列出 Item 類型的屬性：
| 屬性 | 類型 | 說明 | |
|---|---|---|---|
structuredResponse |
StructuredResponse |
必填。 |
|
RichResponse
包含你對購物車結帳的回應。
下表列出 RichResponse 類型的屬性：
| 屬性 | 類型 | 說明 | |
|---|---|---|---|
items |
List<Item> |
必填。 必須有 1 個項目。 |
|
StructuredResponse
對於 CheckoutResponseMessage，這可以是下列任一項：CheckoutResponse 表示結帳成功。OR FoodErrorExtension：表示結帳期間發生錯誤。回應可能包含已修正的 ProposedOrder 和 PaymentOptions，或是沒有 PaymentOptions 的錯誤訊息。針對 SubmitOrderResponseMessage，僅適用 orderUpdate。
下表列出 StructuredResponse 類型的屬性：
| 屬性 | 類型 | 說明 | |
|---|---|---|---|
| 必須提供下列其中一個屬性組合。 | |||
checkoutResponse |
群組 1 | CheckoutResponse |
已結帳的商品，加上稅金和折扣。 |
error |
群組 2 | FoodErrorExtension |
購物車商品發生錯誤。視錯誤性質而定，這項屬性可能包含已修正的 ProposedOrder 和 PaymentOptions，也可能只包含錯誤訊息，而沒有 PaymentOptions。 |
orderUpdate |
群組 3 | OrderUpdate |
|
非同步訂單更新
本節說明組成一般餐點訂購內建動作互動動作的一般類型。AsyncOrderUpdateRequestMessage
在提交及確認訂單後，通知使用者變更。舉例來說，您可以通知使用者訂單正在運送中，或是價格有變動。詳情請參閱下表列出 AsyncOrderUpdateRequestMessage 類型的屬性：
| 屬性 | 類型 | 說明 | |
|---|---|---|---|
isInSandbox |
布林值 |
表示這項更新是針對沙箱付款訂單傳送。 |
|
customPushMessage |
CustomPushMessage |
必填。 包含要求的 OrderUpdate。 |
|
以下範例顯示 AsyncOrderUpdateRequestMessage 元素：
範例
{
"isInSandbox": true,
"customPushMessage": {
"orderUpdate": {
"actionOrderId": "sample_action_order_id",
"orderState": {
"state": "IN_TRANSIT",
"label": "Order is on the way"
},
"inTransitInfo": {
"updatedTime": "2017-07-17T12:00:00Z"
},
"updateTime": "2017-07-17T12:00:00Z",
"receipt": {
"userVisibleOrderId": "userVisibleId1234"
},
"orderManagementActions": [
{
"type": "CUSTOMER_SERVICE",
"button": {
"title": "Contact customer service",
"openUrlAction": {
"url": "mailto:support@example.com"
}
}
},
{
"type": "EMAIL",
"button": {
"title": "Email restaurant",
"openUrlAction": {
"url": "mailto:person@example.com"
}
}
},
{
"type": "CALL_RESTAURANT",
"button": {
"title": "Call restaurant",
"openUrlAction": {
"url": "tel:+16505554679"
}
}
}
],
"infoExtension": {
"@type": "type.googleapis.com/google.actions.v2.orders.FoodOrderUpdateExtension",
"estimatedFulfillmentTimeIso8601": "2017-07-17T13:00:00Z/2017-07-17T13:30:00Z"
}
}
}
}
AsyncOrderUpdateResponseMessage
成功傳送AsyncOrderUpdateRequestMessage 後，Google 會傳回 HTTP 200 狀態和空白內文。如果更新失敗，Google 會回覆訂單更新失敗的原因。
訂單更新類型
按鈕
定義可新增的使用者介面元素，以提供使用者互動。
下表列出 Button 類型的屬性：
| 屬性 | 類型 | 說明 | |
|---|---|---|---|
title |
String | 必填。 顯示標籤。請使用句首字母大寫的字串，長度不得超過 30 個半形字元，以確保正確顯示。 範例： |
|
openUrlAction |
OpenUrlAction |
必填。 |
|
以下範例顯示 Button 元素：
範例
{
"title": "Send us feedback",
"openUrlAction": {
"url": "mailto:person@example.com"
}
}
CancellationInfo
下表列出 CancellationInfo 類型的屬性：
| 屬性 | 類型 | 說明 | |
|---|---|---|---|
reason |
String | 必填。 當 OrderState.state 為「CANCELLED」時，顯示拒絕原因的文字。 範例： |
|
以下範例顯示 CancellationInfo 元素：
範例
{
"reason": "Insufficient inventory"
}
FoodOrderUpdateExtension
這類型會向使用者提供訂單送達或可供取貨的預估時間間隔。只要資訊可用，或自上次傳送後有所變更，就應在 OrderUpdate 中傳送這項擴充資料。
請提供較保守的執行間隔預估值，以便始終符合使用者預期。舉例來說，如果系統預估訂單會在今天 13:00 送達，您應傳送的預估間隔應與交通狀況變化一致，例如今天 12:45 到 13:15。
ISO 8601 時間長度或時間戳記的解讀方式是指從 OrderUpdate 的 updateTime (本質上是「現在」) 到 updateTime 加上 duration 的間隔。除非「現在」確實是合理的預期時間，否則請勿使用這個格式。
ISO 8601 間隔的解讀方式是指從間隔開始到結束的間隔。
下表列出 FoodOrderUpdateExtension 類型的屬性：
| 屬性 | 類型 | 說明 | |
|---|---|---|---|
@type |
Const |
這個擴充功能的類型。這個欄位一律設為「type.googleapis.com/google.actions.v2.orders.FoodOrderUpdateExtension」。 值： |
|
estimatedFulfillmentTimeIso8601 |
String |
訂單送達或可供取貨的預估時間。字串必須採用 ISO 8601 格式，且必須對應至一段時間，而非單一固定時間。可接受的慣用規則包括：間隔、時間長度和日期/時間。當資訊可用或發生變更 (例如提早或延遲抵達) 時，您可以透過 SubmitOrderResponseMessage 或 AsyncOrderUpdateRequestMessage 傳送這個欄位。 範例： |
|
foodOrderErrors |
List<FoodOrderError> |
說明後續訂單發生的錯誤。建議每個購物車或每項商品只出現一個錯誤。如有 RejectionInfo 未涵蓋的任何錯誤，請使用 FoodOrderUpdateExtension.FoodOrderErrors。 必須至少包含 1 個項目。 |
|
以下範例顯示 FoodOrderUpdateExtension 元素：
範例 1
{
"@type": "type.googleapis.com/google.actions.v2.orders.FoodOrderUpdateExtension",
"estimatedFulfillmentTimeIso8601": "2017-07-17T13:00:00Z/2017-07-17T13:30:00Z"
}
範例 2
{
"@type": "type.googleapis.com/google.actions.v2.orders.FoodOrderUpdateExtension",
"foodOrderErrors": [
{
"error": "NO_CAPACITY",
"description": "Sorry, the restaurant cannot take your order right now."
}
]
}
FulfillmentInfo
下表列出 FulfillmentInfo 類型的屬性：
| 屬性 | 類型 | 說明 | |
|---|---|---|---|
| 必須提供下列其中一個屬性組合。 | |||
deliveryTime |
群組 1 | ISO 時間戳記 |
在 FoodOrderingUpdateExtension 訊息中使用 estimatedFulfillmentTimeIso8601 |
pickupTime |
群組 2 | ISO 時間戳記 |
在 FoodOrderingUpdateExtension 訊息中使用 estimatedFulfillmentTimeIso8601 |
以下範例顯示 FulfillmentInfo 元素：
範例 1
{
"deliveryTime": "2017-05-10T02:36:38.803Z"
}
範例 2
{
"pickupTime": "2019-12-26T07:24:27.803Z"
}
InTransitInfo
下表列出 InTransitInfo 類型的屬性：
| 屬性 | 類型 | 說明 | |
|---|---|---|---|
updatedTime |
ISO 時間戳記 |
在 FoodOrderingUpdateExtension 訊息中使用 estimatedFulfillmentTimeIso8601 |
|
以下範例顯示 InTransitInfo 元素：
範例
{
"updatedTime": "2017-05-10T02:36:38.803Z"
}
LineItemUpdate
下表列出 LineItemUpdate 類型的屬性：
| 屬性 | 類型 | 說明 | |
|---|---|---|---|
orderState |
OrderState |
||
price |
Price |
||
reason |
String |
變更原因。如要變更價格，請務必填寫。 |
|
以下範例顯示 LineItemUpdate 元素：
範例
{
"orderState": {
"state": "CONFIRMED",
"label": "Provider confirmed"
},
"price": {
"type": "ESTIMATE",
"amount": {
"currencyCode": "USD",
"units": "5",
"nanos": 500000000
}
},
"reason": "Menu updated prices."
}
OpenUrlAction
下表列出 OpenUrlAction 類型的屬性：
| 屬性 | 類型 | 說明 | |
|---|---|---|---|
url |
String | 必填。 點按或輕觸按鈕時觸發的動作。適用的前置字元清單取決於 orderManagementActionType。「EMAIL」：前置字元必須是「mailto」。「CALL」：前置字元必須是「tel」。「CUSTOMER_SERVICE」：前置字元必須是「mailto」、「tel」、「http」或「https」。 範例： |
|
OrderManagementAction
訂單管理功能可讓使用者取得訂單後支援服務，並應在提交訂單 AppResponse 和後續每個 AsyncOrderUpdateRequestMessage 中傳送每個 OrderUpdate。針對特定訂單傳送的訂單管理動作可能因狀態而異。
舉例來說，在「CREATED」狀態下，CUSTOMER_SERVICE 可能會參照客戶服務電話。接著，在「CONFIRMED」狀態下，如果餐廳電話是客戶聯絡的最佳管道，CUSTOMER_SERVICE 可以變更為餐廳的電話號碼。同樣地，當訂單處於「已完成」狀態時，CUSTOMER_SERVICE 可以參照支援電子郵件地址。
下表列出 OrderManagementAction 類型的屬性：
| 屬性 | 類型 | 說明 | |
|---|---|---|---|
type |
OrderManagementActionType |
必填。 |
|
button |
Button |
必填。 |
|
以下範例顯示 OrderManagementAction 元素：
範例 1
{
"type": "CUSTOMER_SERVICE",
"button": {
"title": "Contact customer service",
"openUrlAction": {
"url": "mailto:support@example.com"
}
}
}
範例 2
{
"type": "EMAIL",
"button": {
"title": "Email restaurant",
"openUrlAction": {
"url": "mailto:person@example.com"
}
}
}
OrderManagementActionType
定義與OrderManagementAction 相關的類型。OrderManagementActionType 類型可用的值如下：
CUSTOMER_SERVICE：在訂單確認頁面上顯示的客戶服務電子郵件和/或聯絡電話號碼。這是必要項目。openUrlAction.url 前置字元必須是「mailto」、「tel」、「http」或「https」。EMAIL：僅適用於訂單詳細資料頁面的電子郵件動作。openUrlAction.url 前置字串必須為「mailto」。CALL_DRIVER：僅適用於訂單詳細資料頁面的呼叫動作。openUrlAction.url 前置字元必須為「tel」。CALL_RESTAURANT：僅適用於訂單詳細資料頁面的呼叫動作。openUrlAction.url 前置字元必須為「tel」。
OrderState
訂單目前的狀態。OrderState 的每個 state 值也對應至 myaccount.google.com 上的購買狀態。
下表列出 OrderState 類型的屬性：
| 屬性 | 類型 | 說明 | |
|---|---|---|---|
state |
OrderStateEnum |
必填。 |
|
label |
String | 必填。 狀態的使用者可見顯示字串。英文標題應採用句首字母大寫格式。 範例： |
|
以下範例顯示 OrderState 元素：
範例
{
"state": "CONFIRMED",
"label": "Provider confirmed"
}
OrderStateEnum
定義與OrderState 相關的類型。OrderStateEnum 類型可用的值如下：
CREATED：由整合服務供應商建立的訂單，目前正在等待供應商確認。對應於「已下單」的購買狀態。CONFIRMED：訂單已由供應商確認並生效。對應至「已接受」的購買狀態。REJECTED：訂單遭到整合業者或供應商拒絕。對應於「Declined」(拒絕) 購買狀態。CANCELLED：使用者取消訂單。對應於「已取消」的購買狀態。IN_PREPARATION：餐點正在準備中。對應於「狀態不明」的購買狀態。READY_FOR_PICKUP：餐點已準備好供你取件。對應於「已準備取貨」的購買狀態。IN_TRANSIT：訂單正在送達。對應於「進行中」的購買狀態。FULFILLED：使用者收到訂購的商品。對應至「已取貨」的購買狀態。
收據
在提交訂單AppResponse 中傳送此類型，其中 OrderState 為「CONFIRMED」、「FULFILLED」或「IN_TRANSIT」。在 userVisibleOrderId 可用時傳送收據。您不需要在後續更新中持續傳送收據。
下表列出 Receipt 類型的屬性：
| 屬性 | 類型 | 說明 | |
|---|---|---|---|
userVisibleOrderId |
String | 必填。 如果訂單狀態為「CONFIRMED」、「IN_TRANSIT」或「FULFILLED」，則為必填屬性。這個欄位是這筆訂單的單一使用者 ID (通常是餐廳的訂單 ID)，會顯示在整合商的收據和 Google 訂單資訊卡中。使用者必須能夠使用這個 ID 向供應商和整合服務供應商提供訂單，以便取得客戶服務。您只需在任何 OrderUpdate 中提供一次這個 ID。在提供該值之前，actionOrderId 就是 userVisibleOrderId。舉例來說，您可能必須等到餐廳確認訂單後，才能取得 userVisibleOrderId。確認後，您必須傳送 AsyncOrderUpdateRequestMessage，其中包含 OrderUpdate 和 Receipt。 |
|
以下範例顯示 Receipt 元素：
範例
{
"userVisibleOrderId": "userVisibleId1234"
}
RejectionInfo
下表列出 RejectionInfo 類型的屬性：
| 屬性 | 類型 | 說明 | |
|---|---|---|---|
type |
RejectionType |
必填。 |
|
reason |
String |
用於內部記錄的拒絕原因。使用者不會看到這個欄位。 |
|
以下範例顯示 RejectionInfo 元素：
範例
{
"type": "PAYMENT_DECLINED",
"reason": "There is an issue with payment processing."
}
RejectionType
RejectionType 類型可用的值如下：
INELIGIBLE：使用者因政策或風險相關問題而無法使用服務。PAYMENT_DECLINED：付款處理作業發生問題。UNAVAILABLE_SLOT：訂單無法在 DeliveryInfo 或 PickupInfo 指定的預訂時間內完成。PROMO_NOT_APPLICABLE：促銷活動發生問題。UNKNOWN：任何其他原因。
付款相關類型
本節說明用於處理餐點訂購的付款相關類型。ActionProvidedPaymentOptions
行動提供的付款方式相關規定。
下表列出 ActionProvidedPaymentOptions 類型的屬性：
| 屬性 | 類型 | 說明 | |
|---|---|---|---|
paymentType |
PaymentType |
必填。 |
|
displayName |
String | 必填。 收據上顯示的付款工具名稱。 範例： |
|
onFulfillmentPaymentData |
OnFulfillmentPaymentData |
付款類型為「ON_FULFILLMENT」的其他資料。舉例來說，您可以使用這個欄位指定是否支援現金或卡片付款。 |
|
以下範例顯示 ActionProvidedPaymentOptions 元素：
範例
{
"paymentType": "ON_FULFILLMENT",
"displayName": "Pay when you get your food.",
"onFulfillmentPaymentData": {
"supportedPaymentOptions": [
"Cash",
"Card"
]
}
}
AllowedAuthMethods
AllowedAuthMethods 類型可用的值如下：
PAN_ONLY：這種驗證方式與使用者 Google 帳戶中儲存的付款卡相關聯。傳回的付款資料包括個人帳號 (PAN) 和到期月份及年份。
AllowedCardNetworks
AllowedCardNetworks 類型可用的值如下：
AMEXDISCOVERINTERACJCBMASTERCARDVISA
BillingAddressParameters
這個物件可讓您為要求的帳單地址設定要傳回的額外欄位。
下表列出 BillingAddressParameters 類型的屬性：
| 屬性 | 類型 | 說明 | |
|---|---|---|---|
format |
String |
完成交易所需的帳單地址格式。MIN：姓名、國家/地區代碼和郵遞區號。FULL：姓名、街道地址、縣市、地區、國家/地區代碼與郵遞區號。 |
|
以下範例顯示 BillingAddressParameters 元素：
範例 1
{
"format": "MIN"
}
範例 2
{
"format": "FULL"
}
CardParameters
使用這個物件設定網站對 Google Pay API 的支援。
下表列出 CardParameters 類型的屬性：
| 屬性 | 類型 | 說明 | |
|---|---|---|---|
allowedAuthMethods |
List<Const> | 必填。 驗證卡片交易時支援的欄位。 必須至少包含 1 個項目。 |
|
allowedCardNetworks |
List<AllowedCardNetworks> |
必填。 Google Pay API 也支援您所支援的一或多個發卡機構。 必須至少包含 1 個項目。 |
|
billingAddressRequired |
布林值 |
如果您需要帳單地址，請設為 true。只有在需要帳單地址來處理交易時，才要求提供。要求額外的資料可能會增加結帳程序的不便，並且導致轉換率下降。 |
|
billingAddressParameters |
BillingAddressParameters |
將 billingAddressRequired 設為 true 時傳回的預期欄位。 |
|
cvcRequired |
布林值 |
如果使用 TimesofMoney，請將這個值設為 true；如果使用其他付款處理服務，請設為 false。 |
|
以下範例顯示 CardParameters 元素：
範例 1
{
"allowedAuthMethods": [
"PAN_ONLY"
],
"allowedCardNetworks": [
"AMEX",
"DISCOVER"
],
"billingAddressRequired": false,
"cvcRequired": false
}
範例 2
{
"allowedAuthMethods": [
"PAN_ONLY"
],
"allowedCardNetworks": [
"AMEX",
"DISCOVER"
],
"billingAddressRequired": true,
"billingAddressParameters": {
"format": "MIN"
},
"cvcRequired": false
}
GoogleProvidedPaymentInstrument
下表列出 GoogleProvidedPaymentInstrument 類型的屬性：
| 屬性 | 類型 | 說明 | |
|---|---|---|---|
instrumentToken |
String | 必填。 採用 Base 64 編碼的字串，其中包含付款權杖，可根據先前指定的 GoogleProvidedPaymentOptions，透過合作的 Google Pay 處理工具向使用者收費。 |
|
billingAddress |
PostalAddress |
付款的帳單地址。 |
|
以下範例顯示 GoogleProvidedPaymentInstrument 元素：
範例
{
"instrumentToken": "abcd",
"billingAddress": {
"regionCode": "US",
"postalCode": "94043",
"administrativeArea": "CA",
"locality": "Mountain View",
"addressLines": [
"1350 Charleston Road"
]
}
}
GoogleProvidedPaymentOptions
Google 提供的付款方式相關規定。
下表列出 GoogleProvidedPaymentOptions 類型的屬性：
| 屬性 | 類型 | 說明 | |
|---|---|---|---|
facilitationSpecification |
String |
PaymentDataRequest JSON 做為字串。使用這個物件設定網站對 Google Pay API 的支援。 |
|
supportedCardNetworks |
List<SupportedCardNetworks> |
請改用 facilitationSpecification。代理人支援的發卡機構類型。 這個欄位已淘汰。 |
|
prepaidCardDisallowed |
布林值 |
請改用 facilitationSpecification。是否允許使用預付卡付款。 這個欄位已淘汰。 |
|
billingAddressRequired |
布林值 |
請改用 facilitationSpecification。是否需要帳單地址。 這個欄位已淘汰。 |
|
tokenizationParameters |
TokenizationParameters |
這個欄位已淘汰。 |
|
以下範例顯示 GoogleProvidedPaymentOptions 元素：
範例 1
{
"facilitationSpecification": "{\"apiVersion\": 2,\"apiVersionMinor\": 0,\"merchantInfo\": { \"merchantId\": \"Merchant ID\", \"merchantName\": \"Merchant Name\"},\"allowedPaymentMethods\": [ { \"type\": \"CARD\", \"parameters\": { \"allowedAuthMethods\": [ \"PAN_ONLY\" ], \"allowedCardNetworks\": [ \"VISA\", \"AMEX\", \"MASTERCARD\" ], \"billingAddressRequired\": false }, \"tokenizationSpecification\": { \"type\": \"PAYMENT_GATEWAY\", \"parameters\": { \"stripe:publishableKey\": \"pk_test_OoPcJNnxI1rDXhBq8BiXO2wz00s1Xc92dA\", \"gateway\": \"stripe\", \"stripe:version\": \"2019-05-16\" } } }],\"transactionInfo\": { \"currencyCode\": \"AUD\", \"totalPriceStatus\": \"ESTIMATED\", \"totalPrice\": \"1.0\"}}"
}
範例 2
{
"tokenizationParameters": {
"tokenizationType": "PAYMENT_GATEWAY",
"parameters": {
"gateway": "braintree",
"braintree:apiVersion": "v1",
"braintree:sdkVersion": "1.4.0",
"braintree:merchantId": "a1b2c3d4e5",
"braintree:clientKey": "production_braintree_client_key",
"braintree:authorizationFingerprint": "same_as_client_key"
}
},
"supportedCardNetworks": [
"AMEX",
"DISCOVER",
"MASTERCARD",
"JCB",
"VISA"
],
"prepaidCardDisallowed": true
}
範例 3
{
"tokenizationParameters": {
"tokenizationType": "PAYMENT_GATEWAY",
"parameters": {
"gateway": "stripe",
"stripe:publishableKey": "pk_live_stripe_client_key",
"stripe:version": "2017-04-06"
}
},
"supportedCardNetworks": [
"AMEX",
"DISCOVER",
"MASTERCARD",
"VISA",
"JCB"
],
"prepaidCardDisallowed": true,
"billingAddressRequired": true
}
MerchantInfo
使用這個物件設定網站對 Google Pay API 的支援。
下表列出 MerchantInfo 類型的屬性：
| 屬性 | 類型 | 說明 | |
|---|---|---|---|
merchantId |
String |
Google Pay 核發給你的 Google 商家識別碼。 |
|
merchantName |
String | 必填。 採用 UTF-8 編碼的商家名稱，商家名稱會顯示在付款畫面中。 |
|
OnFulfillmentPaymentData
使用這個物件，針對 PaymentType 傳送「ON_FULFILLMENT」的其他資料。
下表列出 OnFulfillmentPaymentData 類型的屬性：
| 屬性 | 類型 | 說明 | |
|---|---|---|---|
supportedPaymentOptions |
List<PaymentOptionsEnums> |
使用者在訂單履行時可用的付款方式清單。 |
|
以下範例顯示 OnFulfillmentPaymentData 元素：
範例
{
"supportedPaymentOptions": [
"Cash",
"Card"
]
}
參數
定義與 TokenizationParameters 相關的類型。
下表列出 Parameters 類型的屬性：
| 屬性 | 類型 | 說明 | |
|---|---|---|---|
gateway |
String | 必填。 範例： |
|
gatewayMerchantId |
String | ||
[additionalKey: string] |
String | 其他鍵/值組合 | |
以下範例顯示 Parameters 元素：
範例 1
{
"gatewayMerchantId": "90412491",
"gateway": "olo"
}
範例 2
{
"gateway": "braintree",
"braintree:apiVersion": "v1",
"braintree:sdkVersion": "1.4.0",
"braintree:merchantId": "YOUR_MERCHANT_ID",
"braintree:clientKey": "YOUR_BRAINTREE_SANDVOX_OR_PRODUCTION_KEY"
}
PaymentDataRequest
使用這個物件設定網站對 Google Pay API 的支援。
下表列出 PaymentDataRequest 類型的屬性：
| 屬性 | 類型 | 說明 | |
|---|---|---|---|
apiVersion |
Const | 必填。 API 主要版本。 值： |
|
apiVersionMinor |
Const | 必填。 API 次要版本。 值： |
|
merchantInfo |
MerchantInfo |
必填。 (Google Pay 商家 ID) 要求付款資料的商家相關資訊。 |
|
allowedPaymentMethods |
List<PaymentMethod> |
必填。 指定支援 Google Pay API 所支援的一或多種付款方式。 |
|
transactionInfo |
TransactionInfo |
必填。 根據使用者是否同意交易，提供有關交易授權的詳細資料，這個欄位包含總價和價格狀態。 |
|
以下範例顯示 PaymentDataRequest 元素：
範例
{
"apiVersion": 2,
"apiVersionMinor": 0,
"merchantInfo": {
"merchantId": "10391231",
"merchantName": "Burrito Town"
},
"allowedPaymentMethods": [
{
"type": "CARD",
"parameters": {
"allowedAuthMethods": [
"PAN_ONLY"
],
"allowedCardNetworks": [
"VISA",
"AMEX",
"MASTERCARD"
],
"billingAddressRequired": true,
"billingAddressParameters": {
"format": "FULL"
},
"cvcRequired": false
},
"tokenizationSpecification": {
"type": "PAYMENT_GATEWAY",
"parameters": {
"gateway": "stripe",
"stripe:version": "2019-05-16",
"stripe:publishableKey": "pk_test_OoPcJNnxI1rDXhBq8BiXO2wz00s1Xc92dA"
}
}
}
],
"transactionInfo": {
"currencyCode": "INR",
"totalPriceStatus": "ESTIMATED",
"totalPrice": "185.00"
}
}
PaymentInfo
訂單的付款相關資訊。
下表列出 PaymentInfo 類型的屬性：
| 屬性 | 類型 | 說明 | |
|---|---|---|---|
displayName |
String | 必填。 收據上顯示的付款工具名稱，供使用者查看。 |
|
paymentType |
PaymentType |
必填。 |
|
googleProvidedPaymentInstrument |
GoogleProvidedPaymentInstrument |
動作可使用的符記。只有在 CheckoutResponseMessage 中將 GoogleProvidedPaymentOptions 指定為付款選項時，才需要指定這項屬性。 |
|
以下範例顯示 PaymentInfo 元素：
範例 1
{
"displayName": "Visa\u2006****\u20061111",
"googleProvidedPaymentInstrument": {
"instrumentToken": "abcd"
},
"paymentType": "PAYMENT_CARD"
}
範例 2
{
"displayName": "Visa\u2006****\u20061111",
"googleProvidedPaymentInstrument": {
"instrumentToken": "abcd",
"billingAddress": {
"regionCode": "US",
"postalCode": "94043",
"administrativeArea": "CA",
"locality": "Mountain View",
"addressLines": [
"123 Random Street",
"Unit ABC"
],
"recipients": [
"sample_receipient"
]
}
},
"paymentType": "PAYMENT_CARD"
}
PaymentMethod
使用這個物件設定網站對 Google Pay API 的支援。
下表列出 PaymentMethod 類型的屬性：
| 屬性 | 類型 | 說明 | |
|---|---|---|---|
type |
Const | 必填。 支援的付款方式簡短 ID。目前僅支援 CARD。 值： |
|
parameters |
CardParameters |
必填。 設定所提供的付款方式類型時所需的參數。 |
|
tokenizationSpecification |
TokenizationSpecification |
必填。 設定要接收付款資訊的帳戶或解密供應商。如為 CARD 付款方式，則此為必要屬性。 |
|
以下範例顯示 PaymentMethod 元素：
範例
{
"type": "CARD",
"parameters": {
"allowedAuthMethods": [
"PAN_ONLY"
],
"allowedCardNetworks": [
"VISA",
"AMEX",
"MASTERCARD"
],
"billingAddressRequired": false
},
"tokenizationSpecification": {
"type": "PAYMENT_GATEWAY",
"parameters": {
"gatewayMerchantId": "90412491",
"gateway": "olo"
}
}
}
PaymentOptions
下表列出 PaymentOptions 類型的屬性：
| 屬性 | 類型 | 說明 | |
|---|---|---|---|
| 必須提供下列其中一個屬性組合。 | |||
googleProvidedOptions |
群組 1 | GoogleProvidedPaymentOptions |
與 actionProvidedOptions 互斥。使用 Google Pay 進行線上付款時，請使用這組資訊。 |
actionProvidedOptions |
群組 2 | ActionProvidedPaymentOptions |
與 googleProvidedOptions 互斥。適用於「貨到付款」或「出貨付款」。 |
以下範例顯示 PaymentOptions 元素：
範例 1
{
"googleProvidedOptions": {
"facilitationSpecification": "{\"apiVersion\": 2,\"apiVersionMinor\": 0,\"merchantInfo\": { \"merchantId\": \"Merchant ID\", \"merchantName\": \"Merchant Name\"},\"allowedPaymentMethods\": [ { \"type\": \"CARD\", \"parameters\": { \"allowedAuthMethods\": [ \"PAN_ONLY\" ], \"allowedCardNetworks\": [ \"VISA\", \"AMEX\", \"MASTERCARD\" ], \"billingAddressRequired\": false }, \"tokenizationSpecification\": { \"type\": \"PAYMENT_GATEWAY\", \"parameters\": { \"stripe:publishableKey\": \"pk_test_OoPcJNnxI1rDXhBq8BiXO2wz00s1Xc92dA\", \"gateway\": \"stripe\", \"stripe:version\": \"2019-05-16\" } } }],\"transactionInfo\": { \"currencyCode\": \"AUD\", \"totalPriceStatus\": \"ESTIMATED\", \"totalPrice\": \"1.0\"}}"
}
}
範例 2
{
"googleProvidedOptions": {
"facilitationSpecification": "{\"apiVersion\": 2,\"apiVersionMinor\": 0,\"merchantInfo\": { \"merchantId\": \"Merchant ID\", \"merchantName\": \"Merchant Name\"},\"allowedPaymentMethods\": [ { \"type\": \"CARD\", \"parameters\": { \"allowedAuthMethods\": [ \"PAN_ONLY\" ], \"allowedCardNetworks\": [ \"VISA\", \"AMEX\", \"MASTERCARD\" ], \"billingAddressRequired\":true, \"billingAddressParameters\": { \"format\":\"MIN\" } }, \"tokenizationSpecification\": { \"type\": \"PAYMENT_GATEWAY\", \"parameters\": { \"stripe:publishableKey\": \"pk_test_OoPcJNnxI1rDXhBq8BiXO2wz00s1Xc92dA\", \"gateway\": \"stripe\", \"stripe:version\": \"2019-05-16\" } } }],\"transactionInfo\": { \"currencyCode\": \"AUD\", \"totalPriceStatus\": \"ESTIMATED\", \"totalPrice\": \"1.0\"}}"
}
}
範例 3
{
"actionProvidedOptions": {
"paymentType": "ON_FULFILLMENT",
"displayName": "Pay when you get your food.",
"onFulfillmentPaymentData": {
"supportedPaymentOptions": [
"Cash",
"Card"
]
}
}
}
PaymentOptionsEnums
PaymentOptionsEnums 類型可用的值如下：
CashCardUPIPaytm
PaymentType
PaymentType 類型可用的值如下：
PAYMENT_CARD：適用於 GoogleProvidedPaymentOptions。ON_FULFILLMENT：適用於 ActionProvidedPaymentOptions。
SupportedCardNetworks
定義與GoogleProvidedPaymentOptions 相關的類型。SupportedCardNetworks 類型可用的值如下：
UNSPECIFIED_CARD_NETWORKAMEXDISCOVERJCBMASTERCARDVISA
TokenizationParameters
定義與GoogleProvidedPaymentOptions 相關的類型。
下表列出 TokenizationParameters 類型的屬性：
| 屬性 | 類型 | 說明 | |
|---|---|---|---|
tokenizationType |
Enum [
"UNSPECIFIED_TOKENIZATION_TYPE",
"PAYMENT_GATEWAY"
] |
必填。 請改用 facilitationSpecification。可接受的符記類型。 |
|
parameters |
Parameters |
請改用 facilitationSpecification。 |
|
TokenizationSpecification
這個物件可讓您設定要接收可扣款付款資訊的帳戶。
下表列出 TokenizationSpecification 類型的屬性：
| 屬性 | 類型 | 說明 | |
|---|---|---|---|
type |
Const | 必填。 |
|
parameters |
Parameters |
必填。 |
|
以下範例顯示 TokenizationSpecification 元素：
範例 1
{
"type": "PAYMENT_GATEWAY",
"parameters": {
"gatewayMerchantId": "1247192",
"gateway": "cybersource"
}
}
範例 2
{
"type": "PAYMENT_GATEWAY",
"parameters": {
"gateway": "stripe",
"stripe:version": "2018-10-31",
"stripe:publishableKey": "12378127"
}
}
TransactionInfo
這個物件說明交易內容，藉此判斷付款人能否付款。這個物件可用來顯示付款授權對話方塊。
下表列出 TransactionInfo 類型的屬性：
| 屬性 | 類型 | 說明 | |
|---|---|---|---|
currencyCode |
String | 必填。 ISO 4217 以英文字母構成的貨幣代碼。 |
|
transactionId |
String |
識別交易嘗試的專屬 ID。商家可以使用現有 ID，或為 Google Pay 交易嘗試產生特定 ID。將回呼傳送至 Google Transaction Events API 時，這是必填欄位。 |
|
totalPriceStatus |
Const | 必填。 預設值為「ESTIMATED」。總價可能會根據回應詳情調整，例如根據帳單地址收取的銷售稅。 值： |
|
totalPrice |
String | 必填。 交易總金額，可選用位數至小數點後兩位。這個欄位的值應與 cart.totalPrice 相同。 |
|
以下範例顯示 TransactionInfo 元素：
範例
{
"totalPriceStatus": "ESTIMATED",
"totalPrice": "12.34",
"currencyCode": "USD"
}