執行動作結構定義

這個頁面說明使用 Ordering End-to-End Built-in Action API 時的執行要求網路服務 (排序端對端 API) 的酬載。如需此資訊的機器可讀取版本，可以下載 JSON 結構定義。

底座類型

購物車

包含訂單的詳細資料，以及要求是提供自取或外送。購物車也包含寄送詳細資料、重物和寄送地址。Cart 物件是在 Checkout AppRequest.f 中定義 您可以在 Checkout AppResponse 中加入購物車副本

下表列出 Cart 類型的屬性：

屬性 類型 說明
@type 缺點

這個物件的類型。如果父項購物車物件屬於 ProposedOrder，請省略這個欄位。

值：type.googleapis.com/google.actions.v2.orders.Cart
id String

購物車的選用 ID，
merchant Merchant

與這個購物車相關聯的商家。
lineItems 清單<LineItem>

這是必填欄位。

使用者訂購的商品或服務清單。

不得少於 1 個項目。
promotions 清單<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，請使用這個欄位。

範例：Lovefood Ordering
email String

訂單接收者的電子郵件地址。

範例：ilovefood@example.com
firstName String

訂單接收者的名字。

範例：Lovefood
lastName String

訂單接收者的姓氏。

範例：Ordering
phoneNumber String

訂單收件人員的電話號碼，包括國家/地區代碼。

範例：+16501234567
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)HT(n)M(n)M(n)S」。舉例來說，PT90M 代表時間長度為 90 分鐘。預設值「PT0M」代表偏好的送達時間是盡快的。參考資料：https://en.wikipedia.org/wiki/ISO_8601#Merged_date_and_time_representations。在結帳回應中使用這項資訊即可更新預估送達時間。

範例：PT90M

以下範例為 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：找不到 LineItem、FulfillmentOption 或「Promotion」。
  • PRICE_CHANGED：商品價格已變更。

FeeAmountRange

下表列出 FeeAmountRange 類型的屬性：

屬性 類型 說明
minFeeAmount Money

收費金額下限。
maxFeeAmount Money

收費金額上限。

FeePercentRange

下表列出 FeePercentRange 類型的屬性：

屬性 類型 說明
minFeePercent Number

充電費用百分比下限。
maxFeePercent Number

充電費用百分比上限。

FoodCartExtension

包含使用者的詳細資料，例如執行要求偏好設定。

下表列出 FoodCartExtension 類型的屬性：

屬性 類型 說明
@type 缺點

這項額外資訊的類型。這個欄位一律會設為「type.googleapis.com/google.actions.v2.orders.FoodCartExtension」。

值：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 缺點

這是必填欄位。

這項額外資訊的類型。

值：type.googleapis.com/google.actions.v2.orders.FoodErrorExtension
foodOrderErrors 清單<FoodOrderError>

這是必填欄位。

說明發生錯誤的 FoodOrderError 物件陣列。建議每個購物車或每項商品執行一次錯誤。

不得少於 1 個項目。
correctedProposedOrder ProposedOrder

如為 foodOrderErrors.error = "UNAVAILABLE_SLOT", "PROMO_EXPIRED", "PROMO_NOT_APPLICABLE", "PROMO_NOT_RECOGNIZED", "PROMO_ORDER_INELIGIBLE", "PROMO_USER_INELIGIBLE", "AVAILABILITY_CHANGED", "INCORRECT_PRICE", "INVALID", "NOT_FOUND", or "PRICE_CHANGED"，則為必要欄位。

包含修正的新 ProposedOrder。如果原始提案訂單中有可復原的錯誤，請傳回這個物件。舉例來說，如果購物車中有一或多個委刊項的價格變更，就會視為可復原的錯誤。具備有效 ProposedOrder 的可復原錯誤會提前進入確認階段，而不會要求使用者查看購物車。
paymentOptions PaymentOptions

如為 foodOrderErrors.error = "UNAVAILABLE_SLOT", "PROMO_EXPIRED", "PROMO_NOT_APPLICABLE", "PROMO_NOT_RECOGNIZED", "PROMO_ORDER_INELIGIBLE", "PROMO_USER_INELIGIBLE", "AVAILABILITY_CHANGED", "INCORRECT_PRICE", "INVALID", "NOT_FOUND", or "PRICE_CHANGED"，則為必要欄位。

為使用者選取的預設付款方式。
additionalPaymentOptions 清單<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 缺點

這是必填欄位。

這項額外資訊的類型。這個欄位一律會設為「type.googleapis.com/google.actions.v2.orders.FoodItemExtension」。

值：type.googleapis.com/google.actions.v2.orders.FoodItemExtension
options 清單<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 時，如果購物車中有多項商品具有相同的優惠 ID，可以使用這個欄位加以區分。

範例：39231093
offerId String

商品的優惠 ID。

範例：912835081
name String

選項名稱。

範例：Honey Mustard
price Money
note String

與選項相關的附註。
quantity Number

如為項目選項，則代表項目數量。

範例：3
subOptions 清單<FoodItemOption>

選項的子選項 (如果有的話)。

範例：[ { "id": "71283712", "offerId": "51209121", "name": "BBQ Sauce", "price": { "currencyCode": "USD", "units": "3", "nanos": 780000000 }, "quantity": 2 }, { "id": "102941024", "offerId": "12084102", "name": "Ketchup", "price": { "currencyCode": "USD", "units": "2", "nanos": 980000000 }, "quantity": 6 } ]

以下範例為 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

如為 error = "AVAILABILITY_CHANGED", "INCORRECT_PRICE", "PRICE_CHANGED", "INVALID", or "NOT_FOUND"，則為必要欄位。

如果是商品層級錯誤，此為必填欄位。這是 Google 為選單項目指派的 LineItem.id，或外掛程式的 FoodItemOption.id。
description String

錯誤的說明。這項說明僅供內部記錄使用，不會向使用者顯示。
updatedPrice Money

如為 error = "PRICE_CHANGED"，則為必要欄位。

造成錯誤的商品新價格。只有發生錯誤為「PRICE_CHANGED」時，才需要使用這個選項。
availableQuantity 整數

如為 error = "INVALID", or "NOT_FOUND"，則為必要欄位。

導致錯誤的商品有新的可用數量。只有「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 缺點

這項額外資訊的類型。這個欄位一律會設為「type.googleapis.com/google.actions.v2.orders.FoodOrderExtension」。

值：type.googleapis.com/google.actions.v2.orders.FoodOrderExtension
availableFulfillmentOptions 清單<FulfillmentOption>

代表訂單可用的出貨選項。
optinForRemarketing 布林

使用者要求加入你的行銷通路。根據預設，您不得未經使用者同意就傳送行銷內容。如果 optinFor 再行銷 為 true，即可訂閱使用者。如果 optForFor 再行銷 為 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 中指定的 LineItem ID 相符。

下表列出 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 像素。為獲得最佳效果，請使用至少 216x216 像素的圖片。圖片必須小於 6 MB 或 6,400 萬像素。

LineItem

定義購物車內容 (Cart.lineItems) 或訂單的額外費用 (ProposedOrder.otherItems)。

下表列出 LineItem 類型的屬性：

屬性 類型 說明
id String

如為 type = "REGULAR"，則為必要欄位。

對於購物車中的委刊項 (ProposedOrder.cart.lineItems[0].id)，這是 Google 在建立訂單時建立的專屬 ID。針對 ProposedOrder (ProposedOrder.otherItems[0].id) 中的 LineItem，用於新增運費和稅金等項目，ID 值會由供應商定義。舉例來說，購物車中有兩項相同的商品，其準備指示不同 (例如兩張有不同配料組合的中型披薩)。本例中這兩個商品都有相同的基本優惠 ID。如果您傳送訂單更新要求，指出某個商品已遭拒，請使用這個 ID 做為消歧器。換句話說，如果其中一間披薩因缺少特定配料而遭到拒絕，這個 ID 可協助 Google 決定您提及的訂單順序。此欄位為必要項目，其他項目除外。
name String

這是必填欄位。

委刊項的名稱。這是使用者可見的字串，而且必須盡可能採用句首字母大寫格式 (例如「運費」、「服務費」、「稅金」)。如果是使用者，這個欄位只會顯示 100 個字元。
type LineItemType

這是必填欄位。
quantity 整數

如為 type = "REGULAR"，則為必要欄位。

包含的項目數量。不適用於 ProposedOrder.otherItems。
description String

商品的說明。
price Price

這是必填欄位。

商品或商品的價格。這個值反映了這個委刊項所有商品或服務的總價 (亦即加上任何附加服務的費用，再乘以數量)。舉例來說，如果 $10 美元的商品數量為 3，則價格就是 $30 美元。如果披薩的基本價格為 $5 美元，加購 $1 美元，價格為 $6 美元。假設兩件披薩 (數量 = 2) 的基本價格為 $5 美元，而每起一項加 $1 美元的加值，則價格為 $12 美元。即使價格為「0」，每個明細項目都必須包含一個價格。當類型為 DISCOUNT，請將這個值指定為負值 (例如「-2」)。
subLines 清單<SublineNote>

選用，且只有在類型為「REGULAR」時才有效。使用者可以在結帳要求和訂單提交要求的這個欄位中，傳送商品專屬附註。確認商家在提供附註時會收到附註。在要求中會以 subLines[0].note 表示，這是這個欄位在要求中出現時的唯一值。

最多 1 個項目。
offerId String

如為 type = "REGULAR"，則為必要欄位。

商品的 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：文法委刊項。通常為使用者所選提示的 SendOrderRequestMessage 保留空間。適用於 ProposedOrder.otherItems。
  • DELIVERY：放送委刊項。適用於 ProposedOrder.otherItems。
  • SUBTOTAL：小計委刊項。適用於 ProposedOrder.otherItems。
  • FEE：其他類型未涵蓋的其他委刊項。適用於 ProposedOrder.otherItems。

位置

指定訂餐地址。Location 類型用於 Cart 中，僅表示外送訂單的目的地。如果使用者下單，TransactionDecisionValue 中也會顯示最終的位置。如果訂單有指定自取，則系統不會列出任何地點 (甚至是空白的訂單)。

下表列出 Location 類型的屬性：

屬性 類型 說明
coordinates Coordinates
formattedAddress String

顯示商家地點的地址。

範例：1350 CHARLESTON ROAD, MOUNTAIN VIEW, CA, United States
postalAddress PostalAddress
zipCode String

範例：90210
city String

城市名稱。

範例：Los Angeles
notes String

地點注意事項，例如登機門代碼。長度不得超過 500 個字元。

範例：Gate code is #111

以下範例為 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 進行比對。

範例：https://www.exampleprovider.com/merchant/id1
name String

這是必填欄位。

此為商家名稱。

範例：Falafel Bite

以下範例為 Merchant 元素：

範例

{
  "id": "https://www.exampleprovider.com/merchant/id1",
  "name": "Falafel Bite"
}

金額

下表列出 Money 類型的屬性：

屬性 類型 說明
currencyCode String

這是必填欄位。

ISO 4217 格式的 3 個英文字母貨幣代碼。

範例：USD
units String

金額的整數單位。舉例來說，如果 currencyCode 為 美元，則「1」單位為一美元。

範例：36
nanos 整數

金額的十億分之一 (10^-9) 單位數量。這個值必須介於 -999,999,999 至 +999,999,999 (含) 之間。請使用以下規則：如果單位為正數，nanos 必須為正值或零。如果單位為零，nanos 可以是正數、零或負數。如果單位為負值，nanos 就必須為負值或零。舉例來說，-1.75 美元的表示方式為 = -1，nanos = -750,000,000。

範例：730000000

以下範例為 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，可用於識別傳送更新的順序。如果 OrderUpdate 針對「CREATED」訂單，請在 OrderUpdate 內提供至少一次 IP.user_visible_order_id，這個 ID 就是您在 Google 訂單資訊卡中輸入的使用者可見 ID。
orderState OrderState

這是必填欄位。

訂單的新狀態。
lineItemUpdates Map<String, LineItemUpdate>
updateTime ISO 時間戳記

這是必填欄位。

訂單更新時間。
orderManagementActions 清單<OrderManagementAction>

下單後執行的動作，例如與支援團隊聯絡，以及查看訂單詳細資料。

不得少於 1 個項目，最多不得超過 6 個項目。

rejectionInfo RejectionInfo

如為 orderState.state = "REJECTED"，則為必要欄位。
cancellationInfo CancellationInfo

如為 orderState.state = "CANCELLED"，則為必要欄位。
inTransitInfo InTransitInfo

這個欄位已淘汰。
fulfillmentInfo FulfillmentInfo

這個欄位已淘汰。
receipt Receipt

如為 orderState.state = "CONFIRMED", "IN_PREPARATION", or "READY_FOR_PICKUP"，則為必要欄位。

在收據中提供使用者可查看的訂單 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)H(n)M(n)M(n)S」)。舉例來說，PT90M 代表時間長度為 90 分鐘。預設值為「PT0M」，代表偏好的取貨時間是盡快。參考資料：https://en.wikipedia.org/wiki/ISO_8601#Merged_date_and_time_representations。在結帳回應中，你可以使用這項資訊更新預估取貨時間。

範例：PT90M

以下範例為 PickupInfo 元素：

範例

{
  "pickupTimeIso8601": "PT90M"
}

PostalAddress

下表列出 PostalAddress 類型的屬性：

屬性 類型 說明
regionCode String

這是必填欄位。

雙字母的國家/地區代碼。

範例：US
postalCode String

郵遞區號。

範例：94043
administrativeArea String

最高行政區，用於國家/地區的郵遞地址。可以是州、省、州/省或縣。

範例：CA
locality String

這個位置的城市或鄉鎮。如為未明確定義縣市或不符合此結構的地區，請不要指定 locality，改用 addressLines 欄位。

範例：Mountain View
addressLines List<String>

您可使用一或多行文字來指定街道地址。這個欄位可能含有縣市不明確，因此請勿修改。

範例：[ "1350 Charleston Road" ]
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 清單<LineItem>

供應商新增的商品，例如運費、其他費用和稅金。其他商品也可能含有使用者新增的優惠和/或折扣。

最多 10 個項目。
image Image

與提議訂單相關聯的圖片。
totalPrice Price

這是必填欄位。

提議訂單的總價。
extension FoodOrderExtension

這是必填欄位。

定義餐點訂單的出貨資訊。
disclaimers 清單<Disclaimer>

對應於下單前，於使用者介面中顯示的免責事項訊息。

以下範例為 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 清單<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 清單<Argument>

這是必填欄位。

包含要結帳或要下的訂單

必須剛好 1 個項目。

引數

包含使用者想結帳的食品詳細資料。如果是結帳，則只能使用延長期限。針對提交訂單，只有 transactionDecisionValue

下表列出 Argument 類型的屬性：

屬性 類型 說明
必須提供確切的下列其中一個屬性群組。
extension 群組 1 Cart

針對使用者想結帳的食物列出詳細資料。
transactionDecisionValue 第 2 組 TransactionDecisionValue

包含要下的訂單和付款詳情。

出貨回應

AppResponse

下表列出 AppResponse 類型的屬性：

屬性 類型 說明
expectUserResponse 缺點

設為 false。

值：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 清單<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 清單<Item>

這是必填欄位。

必須剛好 1 個項目。

StructuredResponse

如果是 CheckoutResponseMessage，則可能是下列其中一項：CheckResponse 表示結帳成功。或 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 個半形字元的句子大小寫，確保正確呈現。

範例：Contact us
openUrlAction OpenUrlAction

這是必填欄位。

以下範例為 Button 元素：

範例

{
  "title": "Send us feedback",
  "openUrlAction": {
    "url": "mailto:person@example.com"
  }
}

CancellationInfo

下表列出 CancellationInfo 類型的屬性：

屬性 類型 說明
reason String

這是必填欄位。

當 OrderState.state 為「CANCELLED」時，顯示的文字原因。

範例：Restaurant closed

以下範例為 CancellationInfo 元素：

範例

{
  "reason": "Insufficient inventory"
}

FoodOrderUpdateExtension

這個類型會提供使用者預估訂單送達或準備取貨的預計時間間隔。當擴充功能在上次傳送後有異動時，會在 OrderUpdate 中傳送此擴充功能。

建議您保守執行要求間隔，讓使用者的期望持續達成。舉例來說，如果訂單預計會在今天 13:00 送達，則您應傳送與因路況變化一致的預估間隔，例如今天的 12:45 到 13:15。

系統會將 ISO 8601 時間長度或時間戳記解讀為從 OrderUpdate 的 updateTime (基本上是「現在」) 到 updateTime 加上 duration 的間隔時間。除非「現在」實際上符合合理預期，否則請勿使用這種格式。

系統會將 ISO 8601 間隔解讀為從開始到間隔結束的間隔。

下表列出 FoodOrderUpdateExtension 類型的屬性：

屬性 類型 說明
@type 缺點

這項額外資訊的類型。這個欄位一律會設為「type.googleapis.com/google.actions.v2.orders.FoodOrderUpdateExtension」。

值：type.googleapis.com/google.actions.v2.orders.FoodOrderUpdateExtension
estimatedFulfillmentTimeIso8601 String

預估訂單商品送達或取貨的預計時間。字串必須採用 ISO 8601 格式，且必須對應時間間隔，而不是單一固定時間。可接受的慣例為：間隔、時間長度，以及日期/時間。當資訊已取得或出現變更 (例如提前或延遲抵達) 時，這個欄位可在 CreateOrderResponseMessage 或 AsyncOrderUpdateRequestMessage 中傳送。

範例：2017-07-17T13:00:00Z/2017-07-17T13:30:00Z
foodOrderErrors 清單<FoodOrderError>

說明訂購後發生的錯誤。建議每個購物車或每項商品執行一次錯誤。請使用 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」。

範例：https://www.google.com

OrderManagementAction

訂單管理機制可讓使用者獲得訂單後的支援服務，建議在提交訂單 AppResponse 中的每個 OrderUpdate 傳送，且特定訂單傳送的所有後續 AsyncOrderUpdateRequestMessage 訂單管理動作可能會因狀態而異。

舉例來說，處於「已建立」狀態時，CUSTOMER_SERVICE 可能會參照您的客戶服務電話。然後，如果為「已確認」狀態，CUSTOMER_SERVICE 可以變更為餐廳的電話號碼，視為客戶最合適的聯絡窗口。同樣地，訂單處於「FULFILLED」狀態後，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

這是必填欄位。

使用者可見的狀態顯示字串。英文標題應採用句首字母大寫格式。

範例：Your order has been received

以下範例為 OrderState 元素：

範例

{
  "state": "CONFIRMED",
  "label": "Provider confirmed"
}

OrderStateEnum

定義與 OrderState 相關的類型。

OrderStateEnum 類型包含下列可能的值：

  • CREATED：整合商建立的訂單，正在等待供應商確認。對應至「已訂購」購買狀態。
  • CONFIRMED：供應商已確認訂單，目前有效。對應至「已接受」購買狀態。
  • REJECTED：整合商或供應商已拒絕訂單。對應於「已遭拒」的購買狀態。
  • 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 元素：

範例

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

這是必填欄位。

收據上顯示的付款方式名稱。

範例：Taco Points Total
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 類型包含下列可能的值：

  • AMEX
  • DISCOVER
  • INTERAC
  • JCB
  • MASTERCARD
  • VISA

BillingAddressParameters

這個物件可讓您為要求的帳單地址設定要傳回的額外欄位。

下表列出 BillingAddressParameters 類型的屬性：

屬性 類型 說明
format String

完成交易所需的帳單地址格式。MIN：姓名、國家/地區代碼和郵遞區號。完整：姓名、街道地址、縣市、區域、國家/地區代碼和郵遞區號。

以下範例為 BillingAddressParameters 元素：

範例 1

{
  "format": "MIN"
}

範例 2

{
  "format": "FULL"
}

CardParameters

使用這個物件即可設定對 Google Pay API 的網站支援。

下表列出 CardParameters 類型的屬性：

屬性 類型 說明
allowedAuthMethods List<Const>

這是必填欄位。

驗證卡片交易時支援的欄位。

不得少於 1 個項目。
allowedCardNetworks 清單<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 編碼字串，用於向參與計畫的 Google Pay 處理方收取使用者費用 (根據先前指定的 GoogleProvidedPaymentOptions)。
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 清單<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 商家 ID。
merchantName String

這是必填欄位。

採用 UTF-8 編碼的商家名稱。商家名稱會顯示在付款畫面中。

OnFulfillmentPaymentData

使用這個物件，傳送 PaymentType 為「ON_FULFILLMENT」的其他資料。

下表列出 OnFulfillmentPaymentData 類型的屬性：

屬性 類型 說明
supportedPaymentOptions 清單<PaymentOptionsEnums>

使用者在訂單履行時可用的付款選項清單。

以下範例為 OnFulfillmentPaymentData 元素：

範例

{
  "supportedPaymentOptions": [
    "Cash",
    "Card"
  ]
}

參數

定義與 TokenizationParameters 相關的類型。

下表列出 Parameters 類型的屬性：

屬性 類型 說明
gateway String

這是必填欄位。

範例：braintree
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 缺點

這是必填欄位。

主要 API 版本。

值：2
apiVersionMinor 缺點

這是必填欄位。

子 API 版本。

值：0
merchantInfo MerchantInfo

這是必填欄位。

(Google Pay 商家 ID) 要求付款資料的商家相關資訊。
allowedPaymentMethods 清單<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 缺點

這是必填欄位。

支援的付款方式簡短 ID。目前僅支援 CARD。

值：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 互斥。使用此 ID 透過 gPay 線上付款。
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 類型包含下列可能的值：

  • Cash
  • Card
  • UPI
  • Paytm

PaymentType

PaymentType 類型包含下列可能的值：

  • PAYMENT_CARD：適用於 GoogleProvidedPaymentOptions。
  • ON_FULFILLMENT：適用於 ActionProvidedPaymentOptions。

SupportedCardNetworks

定義與 GoogleProvidedPaymentOptions 相關的類型。

SupportedCardNetworks 類型包含下列可能的值：

  • UNSPECIFIED_CARD_NETWORK
  • AMEX
  • DISCOVER
  • JCB
  • MASTERCARD
  • VISA

TokenizationParameters

定義與 GoogleProvidedPaymentOptions 相關的類型。

下表列出 TokenizationParameters 類型的屬性：

屬性 類型 說明
tokenizationType Enum [ "UNSPECIFIED_TOKENIZATION_TYPE", "PAYMENT_GATEWAY" ]

這是必填欄位。

請改用 facilitationSpecification。可接受的權杖類型。
parameters Parameters

請改用 facilitationSpecification。

TokenizationSpecification

這個物件可讓您設定要接收可扣款付款資訊的帳戶。

下表列出 TokenizationSpecification 類型的屬性：

屬性 類型 說明
type 缺點

這是必填欄位。
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 缺點

這是必填欄位。

請以「ESTIMATED」做為預設值。總價可能會根據回覆詳情調整，例如根據帳單地址收取的銷售稅。

值：ESTIMATED
totalPrice String

這是必填欄位。

交易總金額，可選用位數至小數點後兩位。這個欄位的值必須與 cart.totalPrice 相同。

以下範例為 TransactionInfo 元素：

範例

{
  "totalPriceStatus": "ESTIMATED",
  "totalPrice": "12.34",
  "currencyCode": "USD"
}