執行動作結構定義

本頁面說明使用 Ordering End-to-End-in 內建動作 API 時，執行要求網路服務 (Ordering End-to-End API) 的酬載。 如需機器可讀取的資訊版本，請下載 JSON 結構定義。

基礎類型

購物車

包含訂單的詳細資料，以及這項要求是否供自取 或放送項目購物車也包含貨品交付詳情、小費和貨品交付資訊 讓我們看看 DNS 解析 進一步探索內部和外部位址 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)M(n)DT(n)M(n)S」。舉例來說，PT90M 表示時間長度為 90 分鐘。預設值「PT0M」表示偏好的運送時間越快越好。參考資料：https://en.wikipedia.org/wiki/ISO_8601#Combined_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 或促銷活動包含無效資料。
  • NOT_FOUND：找不到 LineItem、FulfillmentOption 或促銷活動。
  • 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 時，請使用這個欄位來區分購物車中包含多個商品的相同 OfferId 時。

範例：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，您可以訂閱使用者。如果 optinFor remarketing 為 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： 定義一或多個放送選項 (目前只有一個選項是 支援)。您會在以下項目中將預設選項指定為 LineItem ProposedOrder.otherItems。offerId FulfillmentOption 必須與 ProposedOrder.otherItems已指定 LineItem。

下表列出 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

必填。

圖片的網址。圖片至少應為 72 x 72 像素。為獲得最佳效果，請使用 216x216 像素以上的圖片。圖片必須小於 6 MB 或 6,400 萬像素。

LineItem

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

下表列出 LineItem 類型的屬性：

屬性 類型 說明
id String

必要時機 type = "REGULAR"。

購物車中的 LineItem (ProposedOrder.cart.lineItems[0].id) 是 Google 在建立訂單時建立的專屬 ID。對於 ProposedOrder (ProposedOrder.otherItems[0].id) 中的明細項目，可用來新增運費和稅金等項目，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：分數委刊項。通常只會做為針對使用者所選提示保留的 SubmitOrderRequestMessage。適用於 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

必填。

由 3 個英文字母組成的貨幣代碼，採用 ISO 4217 格式。

範例：USD
units String

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

範例：36
nanos 整數

金額的十億分之一 (10^-9) 單位數量。這個值必須介於 -999,999,999 和 +999,999,999 (含) 之間。請使用以下規則：如果單位為正數，nano 必須為正值或零，如果 unit 為零，則 nano 可為正值、零或負數。如果 units 為負值，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

下表說明 OrderUpdate 類型的欄位 包含在 AppResponse 中。

下表列出 OrderUpdate 類型的屬性：

屬性 類型 說明
actionOrderId String

必填。

整合商系統中的訂單專屬 ID，用於識別更新傳送順序。如未在 OrderUpdate 中提供「CREATED」的收據.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)DT(n)M(n)S」。舉例來說，PT90M 表示時間長度為 90 分鐘。預設值 "PT0M" 表示最快首選上車時間。參考資料：https://en.wikipedia.org/wiki/ISO_8601#Combined_date_and_time_representations。請依此更新結帳流程回覆中的預計取貨時間。

範例：PT90M

以下是 PickupInfo 元素的範例：

範例

{
  "pickupTimeIso8601": "PT90M"
}

PostalAddress

下表列出 PostalAddress 類型的屬性：

屬性 類型 說明
regionCode String

必填。

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

範例：US
postalCode String

郵遞區號。

範例：94043
administrativeArea String

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

範例：CA
locality String

這個營業地點的城市或鄉鎮。如為未明確定義縣市或不適用於此結構的地區，請勿指定縣市並使用 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>

供應商新增的商品，例如運費、其他費用和稅金。other 項目也可能包含使用者新增的贈禮和/或折扣。

最多只能包含 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 是一種 AppRequest 使用 actions.foodordering.intent.CHECKOUT 意圖

SubmitOrderRequestMessage

SubmitOrderRequestMessage 是一種 AppRequest 使用 actions.foodordering.intent.TRANSACTION_DECISION 意圖

對話

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 的 中的 checkoutResponse 或 error StructuredResponse。

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 格式，而且必須對應間隔，而非單一固定時間。可接受的慣例如下：間隔、時間長度和日期/時間。當資訊可用或出現異動 (例如提前或延遲送達) 時，可以透過 SubmitOrderResponseMessage 或 AsyncOrderUpdateRequestMessage 傳送此欄位。

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

說明訂單後發生的錯誤。建議為每個購物車或每個商品提供一項錯誤。針對 AcceptionInfo 未涵蓋的任何錯誤，使用 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 訊息中使用預估 FulfillmentTimeIso8601
pickupTime 第 2 組 ISO 時間戳記

在 FoodOrderingUpdateExtension 訊息中使用預估 FulfillmentTimeIso8601

以下是 FulfillmentInfo 元素的範例：

範例 1

{
  "deliveryTime": "2017-05-10T02:36:38.803Z"
}

範例 2

{
  "pickupTime": "2019-12-26T07:24:27.803Z"
}

InTransitInfo

下表列出 InTransitInfo 類型的屬性：

屬性 類型 說明
updatedTime ISO 時間戳記

在 FoodOrderingUpdateExtension 訊息中使用預估 FulfillmentTimeIso8601

以下是 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

訂單管理能讓使用者取得訂單後支援服務，應將這類支援傳送至 提交訂單中的每個 OrderUpdate AppResponse 之後每次 AsyncOrderUpdateRequestMessage 為特定訂單傳送的訂單管理動作可能因 時間。

例如，在「CREATED」狀態，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

訂單目前的狀態。每個 state 值也是 OrderState 對應的購買狀態 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：姓名、國家/地區代碼與郵遞區號。FULL：姓名、街道地址、縣市、地區、國家/地區代碼與郵遞區號。

以下是 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>

請改用 falitationSpecification。服務專員支援的發卡機構類型。

這個欄位已淘汰。
prepaidCardDisallowed 布林值

請改用 falitationSpecification。是否可使用預付卡做為付款方式。

這個欄位已淘汰。
billingAddressRequired 布林值

請改用 falitationSpecification。無論是否提供帳單地址。

這個欄位已淘汰。
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 互斥。這可用來透過 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" ]

必填。

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

請改用 falitationSpecification。

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