ตั้งแต่วันที่ 7 สิงหาคม 2019 เราได้เลิกใช้งาน API ของคำสั่งซื้อเวอร์ชัน 2 และใช้คำสั่งซื้อเวอร์ชัน 3 แทน หากคุณได้สร้างการดำเนินการที่จัดการธุรกรรมทางกายภาพก่อนวันที่ดังกล่าว ให้ทำตามคู่มือนี้เพื่ออัปเดตการดำเนินการของคุณให้ใช้คำสั่งซื้อ v3
การเปลี่ยนแปลง API
Orders API เวอร์ชัน 3 จะมีการเปลี่ยนแปลงที่สำคัญดังต่อไปนี้จากเวอร์ชัน 2
- โครงสร้างคำขอ - โครงสร้างคำสั่งซื้อเวอร์ชัน 3 มีรายละเอียดคำสั่งซื้อทั้งหมด แทนที่จะมีเฉพาะเนื้อหาในรถเข็น
- การอัปเดตคำสั่งซื้อ - Orders API เวอร์ชัน 3 จะจัดการการอัปเดตคำสั่งซื้อเพิ่มเติมจากการจัดการกับตำแหน่งการสั่งซื้อ ดังนั้นปลายทางของคุณจึงไม่จำเป็นต้องใช้ Actions API เพื่อส่งข้อมูลอัปเดตเกี่ยวกับคำสั่งซื้อให้แก่ผู้ใช้ นอกจากนี้ คุณยังส่งข้อมูลอัปเดตเป็นคำขอ Patch ไปยัง Orders API ที่อัปเดตออบเจ็กต์
orderที่มีอยู่ แทนคำขอ POST เพื่อส่งการอัปเดตสถานะ - การอำนวยความสะดวกในการชำระเงิน - การดำเนินการที่ใช้ Google Pay กับเวอร์ชัน 3 Orders API จะฝังรายละเอียดเกตเวย์การชำระเงินไว้ในโครงสร้าง JSON แบบใหม่ซึ่งช่วยให้ขยายการใช้งานได้มากขึ้นและเป็นไปตามกฎหมายของสหภาพยุโรป
ย้ายข้อมูล Node.JS ไปยัง v3
ทำตามขั้นตอนต่อไปนี้เพื่อย้ายข้อมูลการดำเนินการที่ใช้ไลบรารีของไคลเอ็นต์ Node.JS
1. เพิ่มแฟล็ก "คำสั่งซื้อ v3"
ฟังก์ชันไลบรารีของไคลเอ็นต์ที่คุณใช้จัดการธุรกรรมจะได้รับการอัปเดตสำหรับคำสั่งซื้อเวอร์ชัน 3 คุณเพียงต้องเพิ่มแฟล็กลงในโค้ด Fulfillment ที่อัปเดตฟังก์ชันเพื่อส่ง JSON เวอร์ชัน 3
เพิ่มโค้ดต่อไปนี้ลงใน Fulfillment
const {dialogflow} = require('actions-on-google');
const app = dialogflow({ordersv3: true});
2. อัปเดตการประกอบรถเข็น
ระบบได้แทนที่ประเภท ProposedOrder ด้วยออบเจ็กต์ Order ที่ละเอียดมากขึ้น โปรดดูข้อมูลอ้างอิง JSON เพื่อแปลงรถเข็น ProposedOrder เป็นรถเข็น Order
3. อัปเดตพารามิเตอร์การชำระเงิน
โครงสร้างข้อมูลการชำระเงินในขั้นตอนข้อเสนอการสั่งซื้อใน API เวอร์ชันต่างๆ จะมีความแตกต่างกัน
ในคำขอ Intent actions.intent.TRANSACTION_DECISION ให้แทนที่ออบเจ็กต์ paymentOptions เก่าด้วยออบเจ็กต์ paymentParameters ใหม่ ช่องส่วนใหญ่ที่มีอยู่เหมือนกัน บันทึกไว้สำหรับการเปลี่ยนแปลงโครงสร้างของออบเจ็กต์ JSON
ข้อมูลโค้ดต่อไปนี้แสดงตัวอย่าง actions.intent.TRANSACTION_DECISION คำขอ Intent สำหรับ Google Pay ที่ใช้เวอร์ชัน 3 และคำขอเปรียบเทียบเวอร์ชันเก่า 2
conv.ask(new TransactionDecision({
orderOptions: {
requestDeliveryAddress: false,
userInfoOptions: {
userInfoProperties: [
'EMAIL',
],
},
},
paymentParameters: {
googlePaymentOption: {
// facilitationSpec is expected to be a serialized JSON string
facilitationSpec: JSON.stringify({
apiVersion: 2,
apiVersionMinor: 0,
merchantInfo: {
merchantName: 'Example Merchant',
},
allowedPaymentMethods: [
{
type: 'CARD',
parameters: {
allowedAuthMethods: ['PAN_ONLY', 'CRYPTOGRAM_3DS'],
allowedCardNetworks: [
'AMEX', 'DISCOVER', 'JCB', 'MASTERCARD', 'VISA'],
},
tokenizationSpecification: {
type: 'PAYMENT_GATEWAY',
parameters: {
gateway: 'example',
gatewayMerchantId: 'exampleGatewayMerchantId',
},
},
},
],
transactionInfo: {
totalPriceStatus: 'FINAL',
totalPrice: '10.00',
currencyCode: 'USD',
},
}),
},
},
presentationOptions: {
actionDisplayName: 'PLACE_ORDER',
},
order: order,
}));
conv.ask(new TransactionDecision({
orderOptions: {
requestDeliveryAddress: false,
},
paymentOptions: {
googleProvidedOptions: {
prepaidCardDisallowed: false,
supportedCardNetworks: ['VISA', 'AMEX', 'DISCOVER', 'MASTERCARD'],
tokenizationParameters: {
tokenizationType: 'PAYMENT_GATEWAY',
// These will be provided by payment processor,
// like Stripe, Braintree, Vantiv, Ayden, etc.
parameters: {
'gateway': 'stripe',
'stripe:publishableKey': (conv.sandbox ? 'pk_test_key' : 'pk_live_key'),
'stripe:version': '2018-11-08'
},
},
},
},
proposedOrder: order,
}));
โปรดทราบว่า Dialogflow JSON ด้านล่างอธิบายการตอบสนองของเว็บฮุค
{
"payload": {
"google": {
"expectUserResponse": true,
"systemIntent": {
"intent": "actions.intent.TRANSACTION_DECISION",
"data": {
"@type": "type.googleapis.com/google.actions.transactions.v3.TransactionDecisionValueSpec",
"orderOptions": {
"requestDeliveryAddress": "false"
},
"paymentParameters": {
"googlePaymentOption": {
"facilitationSpec": "{\"apiVersion\":2,\"apiVersionMinor\":0,\"merchantInfo\":{\"merchantName\":\"Example Merchant\"},\"allowedPaymentMethods\":[{\"type\":\"CARD\",\"parameters\":{\"allowedAuthMethods\":[\"PAN_ONLY\",\"CRYPTOGRAM_3DS\"],\"allowedCardNetworks\":[\"AMEX\",\"DISCOVER\",\"JCB\",\"MASTERCARD\",\"VISA\"]},\"tokenizationSpecification\":{\"type\":\"PAYMENT_GATEWAY\",\"parameters\":{\"gateway\":\"example\",\"gatewayMerchantId\":\"exampleGatewayMerchantId\"}}}],\"transactionInfo\":{\"totalPriceStatus\":\"FINAL\",\"totalPrice\":\"10.00\",\"currencyCode\":\"USD\"}}"
}
},
"presentationOptions": {
"actionDisplayName": "PLACE_ORDER"
},
"order": {
"createTime": "2019-08-01T17:12:13.765Z",
"lastUpdateTime": "2019-08-01T17:12:13.765Z",
"merchantOrderId": "UNIQUE_ORDER_ID",
"userVisibleOrderId": "USER_VISIBLE_ORDER_ID",
"transactionMerchant": {
"id": "http://www.example.com",
"name": "Example Merchant"
},
"contents": {
"lineItems": [
{
"id": "LINE_ITEM_ID",
"name": "Pizza",
"description": "A four cheese pizza.",
"priceAttributes": [
{
"type": "REGULAR",
"name": "Line Item Price",
"state": "ACTUAL",
"amount": {
"currencyCode": "USD",
"amountInMicros": 8990000
},
"taxIncluded": true
}
],
"notes": [
"Extra cheese."
],
"purchase": {
"quantity": 1,
"unitMeasure": {
"measure": 1,
"unit": "POUND"
},
"itemOptions": [
{
"id": "ITEM_OPTION_ID",
"name": "Pepperoni",
"prices": [
{
"type": "REGULAR",
"state": "ACTUAL",
"name": "Item Price",
"amount": {
"currencyCode": "USD",
"amountInMicros": 1000000
},
"taxIncluded": true
}
],
"note": "Extra pepperoni",
"quantity": 1,
"subOptions": []
}
]
}
}
]
},
"buyerInfo": {
"email": "janedoe@gmail.com",
"firstName": "Jane",
"lastName": "Doe",
"displayName": "Jane Doe"
},
"priceAttributes": [
{
"type": "TOTAL",
"name": "Total Price",
"state": "ESTIMATE",
"amount": {
"currencyCode": "USD",
"amountInMicros": 15770000
},
"taxIncluded": true
},
{
"type": "TAX",
"name": "Tax",
"state": "ESTIMATE",
"amount": {
"currencyCode": "USD",
"amountInMicros": 3780000
},
"taxIncluded": true
},
{
"type": "SUBTOTAL",
"name": "Subtotal",
"state": "ESTIMATE",
"amount": {
"currencyCode": "USD",
"amountInMicros": 9990000
},
"taxIncluded": true
},
{
"type": "DELIVERY",
"name": "Delivery",
"state": "ACTUAL",
"amount": {
"currencyCode": "USD",
"amountInMicros": 2000000
},
"taxIncluded": true
}
],
"followUpActions": [
{
"type": "VIEW_DETAILS",
"title": "View details",
"openUrlAction": {
"url": "http://example.com"
}
},
{
"type": "CALL",
"title": "Call us",
"openUrlAction": {
"url": "tel:+16501112222"
}
},
{
"type": "EMAIL",
"title": "Email us",
"openUrlAction": {
"url": "mailto:person@example.com"
}
}
],
"termsOfServiceUrl": "www.example.com",
"note": "Sale event",
"promotions": [
{
"coupon": "COUPON_CODE"
}
],
"purchase": {
"status": "CREATED",
"userVisibleStatusLabel": "CREATED",
"type": "FOOD",
"returnsInfo": {
"isReturnable": false,
"daysToReturn": 1,
"policyUrl": "http://www.example.com"
},
"fulfillmentInfo": {
"id": "FULFILLMENT_SERVICE_ID",
"fulfillmentType": "DELIVERY",
"expectedFulfillmentTime": {
"timeIso8601": "2017-01-16T01:30:15.01Z"
},
"location": {
"zipCode": "94086",
"city": "Sunnyvale",
"postalAddress": {
"regionCode": "US",
"postalCode": "94086",
"administrativeArea": "CA",
"locality": "Sunnyvale",
"addressLines": [
"222, Some other Street"
]
}
},
"price": {
"type": "REGULAR",
"name": "Delivery Price",
"state": "ACTUAL",
"amount": {
"currencyCode": "USD",
"amountInMicros": 2000000
},
"taxIncluded": true
},
"fulfillmentContact": {
"email": "johnjohnson@gmail.com",
"firstName": "John",
"lastName": "Johnson",
"displayName": "John Johnson"
}
},
"purchaseLocationType": "ONLINE_PURCHASE"
}
}
}
}
}
}
}
โปรดทราบว่า Dialogflow JSON ด้านล่างอธิบายการตอบสนองของเว็บฮุค
{
"payload": {
"google": {
"expectUserResponse": true,
"systemIntent": {
"intent": "actions.intent.TRANSACTION_DECISION",
"data": {
"@type": "type.googleapis.com/google.actions.v2.TransactionDecisionValueSpec",
"orderOptions": {
"requestDeliveryAddress": false
},
"paymentOptions": {
"googleProvidedOptions": {
"prepaidCardDisallowed": false,
"supportedCardNetworks": [
"VISA",
"AMEX",
"DISCOVER",
"MASTERCARD"
],
"tokenizationParameters": {
"tokenizationType": "PAYMENT_GATEWAY",
"parameters": {
"gateway": "stripe",
"stripe:publishableKey": "pk_test_key",
"stripe:version": "2018-11-08"
}
}
}
},
"proposedOrder": {
"id": "UNIQUE_ORDER_ID222",
"cart": {
"merchant": {
"id": "book_store_id",
"name": "A Book Store"
},
"lineItems": [
{
"name": "My Memoirs",
"id": "mymemoirs_id",
"price": {
"amount": {
"currencyCode": "USD",
"nanos": 990000000,
"units": 8
},
"type": "ACTUAL"
},
"quantity": 1,
"subLines": [
{
"note": "By Bestselling Novelist"
}
],
"type": "REGULAR"
},
{
"name": "Biography",
"id": "biography_id",
"price": {
"amount": {
"currencyCode": "USD",
"nanos": 990000000,
"units": 10
},
"type": "ACTUAL"
},
"quantity": 1,
"subLines": [
{
"note": "Signed copy"
}
],
"type": "REGULAR"
}
],
"notes": "Sale event",
"otherItems": []
},
"otherItems": [
{
"name": "Subtotal",
"id": "subtotal",
"price": {
"amount": {
"currencyCode": "USD",
"nanos": 980000000,
"units": 19
},
"type": "ESTIMATE"
},
"type": "SUBTOTAL"
},
{
"name": "Tax",
"id": "tax",
"price": {
"amount": {
"currencyCode": "USD",
"nanos": 780000000,
"units": 2
},
"type": "ESTIMATE"
},
"type": "TAX"
}
],
"totalPrice": {
"amount": {
"currencyCode": "USD",
"nanos": 760000000,
"units": 22
},
"type": "ESTIMATE"
}
}
}
}
}
}
}
4. ส่งการอัปเดตด้วย Orders API
Orders API เวอร์ชัน 3 จะจัดการการอัปเดตคำสั่งซื้อ คุณจึงไม่ต้องส่งคำขอ POST ไปยัง Actions API อีกต่อไป แต่คุณจะส่งคำขอ Patch ไปยัง Orders API ที่อัปเดตเนื้อหาของออบเจ็กต์ Order แทน
เรียกโทเค็นสำหรับผู้ถือใหม่
คุณใช้คีย์บัญชีบริการ JSON เดียวกันกับที่เรียกข้อมูลโทเค็นสำหรับผู้ถือสำหรับ Actions API ได้ โดยต้องขอโทเค็นสำหรับผู้ถือใหม่สำหรับ Orders API แลกเปลี่ยนคีย์บริการเป็นโทเค็นสำหรับผู้ถือ โดยใช้ไลบรารีของไคลเอ็นต์ Google APIs และขอบเขต "https://www.googleapis.com/auth/actions.order.developer"
คุณดูขั้นตอนการติดตั้งและตัวอย่างได้ที่หน้า GitHub ของไคลเอ็นต์ API
นอกจากนี้ คุณยังสามารถอ้างอิง order-update.js ที่อัปเดตในตัวอย่าง Node.js ของเราสำหรับตัวอย่างการแลกเปลี่ยนคีย์ Orders API ด้วย
ส่งการอัปเดต
กระบวนการส่งการอัปเดตคำสั่งซื้อด้วย Orders API จะคล้ายกับการส่งอัปเดตด้วย Actions API แต่คุณจะส่งคำขอ Patch แทนคำขอ POST คำขอ Patch ควรมีเนื้อหา JSON ในรูปแบบต่อไปนี้
{ "orderUpdate": OrderUpdate" }
รูปแบบ OrderUpdate จะแตกต่างกันในเวอร์ชัน 3 เช่นกัน โปรดดูข้อมูลอ้างอิงคำขอแพตช์ แล้วอัปเดตช่อง OrderUpdate ให้สอดคล้องกัน ข้อมูลโค้ดต่อไปนี้แสดงตัวอย่างคำขอ Patch ที่อัปเดตสถานะของคำสั่งซื้อเป็น "DELIVERED"
// Import the 'googleapis' module for authorizing the request.
const {google} = require('googleapis');
// Import the 'request' module for sending an HTTP POST request.
const request = require('request');
// Import the OrderUpdate class from the Actions on Google client library.
const {OrderUpdate} = require('actions-on-google');
// Import the service account key used to authorize the request. Replace the string path with a path to your service account key.
const key = require('./service-account.json');
// Create a new JWT client for the Actions API using credentials from the service account key.
let jwtClient = new google.auth.JWT(
key.client_email,
null,
key.private_key,
['https://www.googleapis.com/auth/actions.order.developer'],
null
);
// Authorize the client asynchronously, passing in a callback to run upon authorization.
jwtClient.authorize((err, tokens) => {
if (err) {
console.log(err);
return;
}
// Declare the ID of the order to update.
const orderId = '<UNIQUE_MERCHANT_ORDER_ID>';
const orderUpdate = new OrderUpdate({
updateMask: [
'lastUpdateTime',
'purchase.status',
'purchase.userVisibleStatusLabel',
].join(','),
order: {
merchantOrderId: orderId,
lastUpdateTime: new Date().toISOString(),
purchase: {
status: 'DELIVERED',
userVisibleStatusLabel: 'Order delivered',
},
},
reason: 'Order status updated to delivered.',
});
// Set up the PATCH request header and body, including the authorized token
// and order update.
const bearer = 'Bearer ' + tokens.access_token;
const options = {
method: 'PATCH',
url: `https://actions.googleapis.com/v3/orders/${orderId}`,
headers: {
'Authorization': bearer,
},
body: {
header: {
'isInSandbox': true,
},
orderUpdate,
},
json: true,
};
// Send the PATCH request to the Orders API.
request.patch(options, (err, httpResponse, body) => {
if (err) {
console.log('There was an error...');
console.log(err);
return;
}
});
});
จัดการสถานะการสั่งซื้อเพิ่มเติม
Orders API เวอร์ชัน 3 รองรับค่าสถานะคำสั่งซื้อเพิ่มเติมที่ไม่มีในเวอร์ชัน 2 คุณควรส่งการอัปเดตคำสั่งซื้อสำหรับทุกสถานะที่เกี่ยวข้องกับธุรกรรมแต่ละรายการ
ค่าสถานะต่อไปนี้เป็นใหม่ของเวอร์ชัน 3
IN_PREPARATION- อยู่ระหว่างการเตรียมสินค้าเพื่อจัดส่ง/จัดส่ง เช่น อาหารกำลังปรุงสุกหรือสิ่งของที่บรรจุหีบห่อREADY_FOR_PICKUP- ผู้รับสามารถมารับสินค้าได้DELIVERED- คำสั่งซื้อส่งถึงผู้รับแล้วOUT_OF_STOCK- สินค้าอย่างน้อย 1 รายการในคำสั่งซื้อนี้หมดสต็อกCHANGE_REQUESTED- ผู้ใช้ขอเปลี่ยนแปลงคำสั่งซื้อ ระบบกำลังประมวลผลการเปลี่ยนแปลง
เราเลิกใช้งานสถานะ FULFILLED แล้ว และแทนที่ด้วย DELIVERED
ย้ายข้อมูล Java ไปยัง v3
ทำตามขั้นตอนเหล่านี้เพื่อย้ายข้อมูลการดำเนินการที่ใช้ไลบรารีของไคลเอ็นต์ Java
1. อัปเดตการประกอบรถเข็น
ระบบได้แทนที่ประเภท ProposedOrder ด้วยออบเจ็กต์ Order ที่ละเอียดมากขึ้น โปรดดูข้อมูลอ้างอิง JSON เพื่อแปลงรถเข็น ProposedOrder เป็นรถเข็น Order
2. อัปเดตพารามิเตอร์การชำระเงิน
โครงสร้างข้อมูลการชำระเงินในขั้นตอนข้อเสนอการสั่งซื้อใน API เวอร์ชันต่างๆ จะมีความแตกต่างกัน
ในคำขอ Intent actions.intent.TRANSACTION_DECISION ให้แทนที่ออบเจ็กต์ paymentOptions เก่าด้วยออบเจ็กต์ paymentParameters ใหม่ ช่องส่วนใหญ่ที่มีอยู่เหมือนกัน บันทึกไว้สำหรับการเปลี่ยนแปลงโครงสร้างของออบเจ็กต์ JSON
ข้อมูลโค้ดต่อไปนี้แสดงตัวอย่าง actions.intent.TRANSACTION_DECISION คำขอ Intent สำหรับ Google Pay ที่ใช้เวอร์ชัน 3 และคำขอเปรียบเทียบเวอร์ชันเก่า 2
// Create order options
OrderOptionsV3 orderOptions = new OrderOptionsV3()
.setRequestDeliveryAddress(false)
.setUserInfoOptions(new UserInfoOptions()
.setUserInfoProperties(Collections.singletonList("EMAIL")));
// Create presentation options
PresentationOptionsV3 presentationOptions = new PresentationOptionsV3()
.setActionDisplayName("PLACE_ORDER");
// Create payment parameters
JSONObject merchantInfo = new JSONObject();
merchantInfo.put("merchantName", "Example Merchant");
JSONObject facilitationSpec = new JSONObject();
facilitationSpec.put("apiVersion", 2);
facilitationSpec.put("apiVersionMinor", 0);
facilitationSpec.put("merchantInfo", merchantInfo);
JSONObject allowedPaymentMethod = new JSONObject();
allowedPaymentMethod.put("type", "CARD");
JSONArray allowedAuthMethods = new JSONArray();
allowedAuthMethods.addAll(Arrays.asList("PAN_ONLY", "CRYPTOGRAM_3DS"));
JSONArray allowedCardNetworks = new JSONArray();
allowedCardNetworks.addAll(Arrays.asList("AMEX", "DISCOVER", "JCB", "MASTERCARD", "VISA"));
JSONObject allowedPaymentMethodParameters = new JSONObject();
allowedPaymentMethodParameters.put("allowedAuthMethods", allowedAuthMethods);
allowedPaymentMethodParameters.put("allowedCardNetworks", allowedCardNetworks);
allowedPaymentMethod.put("parameters", allowedPaymentMethodParameters);
JSONObject tokenizationSpecificationParameters = new JSONObject();
tokenizationSpecificationParameters.put("gateway", "example");
tokenizationSpecificationParameters.put("gatewayMerchantId", "exampleGatewayMerchantId");
JSONObject tokenizationSpecification = new JSONObject();
tokenizationSpecification.put("type", "PAYMENT_GATEWAY");
tokenizationSpecification.put("parameters", tokenizationSpecificationParameters);
allowedPaymentMethod.put("tokenizationSpecification", tokenizationSpecification);
JSONArray allowedPaymentMethods = new JSONArray();
allowedPaymentMethods.add(allowedPaymentMethod);
facilitationSpec.put("allowedPaymentMethods", allowedPaymentMethods);
JSONObject transactionInfo = new JSONObject();
transactionInfo.put("totalPriceStatus", "FINAL");
transactionInfo.put("totalPrice", "10.00");
transactionInfo.put("currencyCode", "USD");
facilitationSpec.put("transactionInfo", transactionInfo);
GooglePaymentOption googlePaymentOption = new GooglePaymentOption()
.setFacilitationSpec(facilitationSpec.toJSONString());
PaymentParameters paymentParameters = new PaymentParameters()
.setGooglePaymentOption(googlePaymentOption);
// Ask for transaction decision
return getResponseBuilder(request)
.add("Placeholder for transaction decision text")
.add(new TransactionDecision()
.setOrder(order)
.setOrderOptions(orderOptions)
.setPresentationOptions(presentationOptions)
.setPaymentParameters(paymentParameters)
)
.build();
OrderOptions orderOptions;
PaymentOptions paymentOptions;
// Setup Google provided payment options
Map<String, String> parameters = new HashMap<>();
parameters.put("gateway", "stripe");
parameters.put("stripe:publishableKey", request.isInSandbox() ? "pk_test_key" : "pk_live_key");
parameters.put("stripe:version", "2017-04-06");
PaymentMethodTokenizationParameters tokenizationParameters =
new PaymentMethodTokenizationParameters()
.setTokenizationType("PAYMENT_GATEWAY")
.setParameters(parameters);
orderOptions = new OrderOptions().setRequestDeliveryAddress(false);
GoogleProvidedPaymentOptions googleProvidedPaymentOptions =
new GoogleProvidedPaymentOptions()
.setPrepaidCardDisallowed(false)
.setSupportedCardNetworks(Arrays.asList("VISA", "AMEX"))
.setTokenizationParameters(tokenizationParameters);
paymentOptions = new PaymentOptions().setGoogleProvidedOptions(googleProvidedPaymentOptions);
return getResponseBuilder(request)
.add("Placeholder for transaction decision text")
.add(
new TransactionDecision()
.setOrderOptions(orderOptions)
.setPaymentOptions(paymentOptions)
.setProposedOrder(proposedOrder))
.build();
โปรดทราบว่า Dialogflow JSON ด้านล่างอธิบายการตอบสนองของเว็บฮุค
{
"payload": {
"google": {
"expectUserResponse": true,
"systemIntent": {
"intent": "actions.intent.TRANSACTION_DECISION",
"data": {
"@type": "type.googleapis.com/google.actions.transactions.v3.TransactionDecisionValueSpec",
"orderOptions": {
"requestDeliveryAddress": "false"
},
"paymentParameters": {
"googlePaymentOption": {
"facilitationSpec": "{\"apiVersion\":2,\"apiVersionMinor\":0,\"merchantInfo\":{\"merchantName\":\"Example Merchant\"},\"allowedPaymentMethods\":[{\"type\":\"CARD\",\"parameters\":{\"allowedAuthMethods\":[\"PAN_ONLY\",\"CRYPTOGRAM_3DS\"],\"allowedCardNetworks\":[\"AMEX\",\"DISCOVER\",\"JCB\",\"MASTERCARD\",\"VISA\"]},\"tokenizationSpecification\":{\"type\":\"PAYMENT_GATEWAY\",\"parameters\":{\"gateway\":\"example\",\"gatewayMerchantId\":\"exampleGatewayMerchantId\"}}}],\"transactionInfo\":{\"totalPriceStatus\":\"FINAL\",\"totalPrice\":\"10.00\",\"currencyCode\":\"USD\"}}"
}
},
"presentationOptions": {
"actionDisplayName": "PLACE_ORDER"
},
"order": {
"createTime": "2019-08-01T17:12:13.765Z",
"lastUpdateTime": "2019-08-01T17:12:13.765Z",
"merchantOrderId": "UNIQUE_ORDER_ID",
"userVisibleOrderId": "USER_VISIBLE_ORDER_ID",
"transactionMerchant": {
"id": "http://www.example.com",
"name": "Example Merchant"
},
"contents": {
"lineItems": [
{
"id": "LINE_ITEM_ID",
"name": "Pizza",
"description": "A four cheese pizza.",
"priceAttributes": [
{
"type": "REGULAR",
"name": "Line Item Price",
"state": "ACTUAL",
"amount": {
"currencyCode": "USD",
"amountInMicros": 8990000
},
"taxIncluded": true
}
],
"notes": [
"Extra cheese."
],
"purchase": {
"quantity": 1,
"unitMeasure": {
"measure": 1,
"unit": "POUND"
},
"itemOptions": [
{
"id": "ITEM_OPTION_ID",
"name": "Pepperoni",
"prices": [
{
"type": "REGULAR",
"state": "ACTUAL",
"name": "Item Price",
"amount": {
"currencyCode": "USD",
"amountInMicros": 1000000
},
"taxIncluded": true
}
],
"note": "Extra pepperoni",
"quantity": 1,
"subOptions": []
}
]
}
}
]
},
"buyerInfo": {
"email": "janedoe@gmail.com",
"firstName": "Jane",
"lastName": "Doe",
"displayName": "Jane Doe"
},
"priceAttributes": [
{
"type": "TOTAL",
"name": "Total Price",
"state": "ESTIMATE",
"amount": {
"currencyCode": "USD",
"amountInMicros": 15770000
},
"taxIncluded": true
},
{
"type": "TAX",
"name": "Tax",
"state": "ESTIMATE",
"amount": {
"currencyCode": "USD",
"amountInMicros": 3780000
},
"taxIncluded": true
},
{
"type": "SUBTOTAL",
"name": "Subtotal",
"state": "ESTIMATE",
"amount": {
"currencyCode": "USD",
"amountInMicros": 9990000
},
"taxIncluded": true
},
{
"type": "DELIVERY",
"name": "Delivery",
"state": "ACTUAL",
"amount": {
"currencyCode": "USD",
"amountInMicros": 2000000
},
"taxIncluded": true
}
],
"followUpActions": [
{
"type": "VIEW_DETAILS",
"title": "View details",
"openUrlAction": {
"url": "http://example.com"
}
},
{
"type": "CALL",
"title": "Call us",
"openUrlAction": {
"url": "tel:+16501112222"
}
},
{
"type": "EMAIL",
"title": "Email us",
"openUrlAction": {
"url": "mailto:person@example.com"
}
}
],
"termsOfServiceUrl": "www.example.com",
"note": "Sale event",
"promotions": [
{
"coupon": "COUPON_CODE"
}
],
"purchase": {
"status": "CREATED",
"userVisibleStatusLabel": "CREATED",
"type": "FOOD",
"returnsInfo": {
"isReturnable": false,
"daysToReturn": 1,
"policyUrl": "http://www.example.com"
},
"fulfillmentInfo": {
"id": "FULFILLMENT_SERVICE_ID",
"fulfillmentType": "DELIVERY",
"expectedFulfillmentTime": {
"timeIso8601": "2017-01-16T01:30:15.01Z"
},
"location": {
"zipCode": "94086",
"city": "Sunnyvale",
"postalAddress": {
"regionCode": "US",
"postalCode": "94086",
"administrativeArea": "CA",
"locality": "Sunnyvale",
"addressLines": [
"222, Some other Street"
]
}
},
"price": {
"type": "REGULAR",
"name": "Delivery Price",
"state": "ACTUAL",
"amount": {
"currencyCode": "USD",
"amountInMicros": 2000000
},
"taxIncluded": true
},
"fulfillmentContact": {
"email": "johnjohnson@gmail.com",
"firstName": "John",
"lastName": "Johnson",
"displayName": "John Johnson"
}
},
"purchaseLocationType": "ONLINE_PURCHASE"
}
}
}
}
}
}
}
โปรดทราบว่า Dialogflow JSON ด้านล่างอธิบายการตอบสนองของเว็บฮุค
{
"payload": {
"google": {
"expectUserResponse": true,
"systemIntent": {
"intent": "actions.intent.TRANSACTION_DECISION",
"data": {
"@type": "type.googleapis.com/google.actions.v2.TransactionDecisionValueSpec",
"orderOptions": {
"requestDeliveryAddress": false
},
"paymentOptions": {
"googleProvidedOptions": {
"prepaidCardDisallowed": false,
"supportedCardNetworks": [
"VISA",
"AMEX",
"DISCOVER",
"MASTERCARD"
],
"tokenizationParameters": {
"tokenizationType": "PAYMENT_GATEWAY",
"parameters": {
"gateway": "stripe",
"stripe:publishableKey": "pk_test_key",
"stripe:version": "2018-11-08"
}
}
}
},
"proposedOrder": {
"id": "UNIQUE_ORDER_ID222",
"cart": {
"merchant": {
"id": "book_store_id",
"name": "A Book Store"
},
"lineItems": [
{
"name": "My Memoirs",
"id": "mymemoirs_id",
"price": {
"amount": {
"currencyCode": "USD",
"nanos": 990000000,
"units": 8
},
"type": "ACTUAL"
},
"quantity": 1,
"subLines": [
{
"note": "By Bestselling Novelist"
}
],
"type": "REGULAR"
},
{
"name": "Biography",
"id": "biography_id",
"price": {
"amount": {
"currencyCode": "USD",
"nanos": 990000000,
"units": 10
},
"type": "ACTUAL"
},
"quantity": 1,
"subLines": [
{
"note": "Signed copy"
}
],
"type": "REGULAR"
}
],
"notes": "Sale event",
"otherItems": []
},
"otherItems": [
{
"name": "Subtotal",
"id": "subtotal",
"price": {
"amount": {
"currencyCode": "USD",
"nanos": 980000000,
"units": 19
},
"type": "ESTIMATE"
},
"type": "SUBTOTAL"
},
{
"name": "Tax",
"id": "tax",
"price": {
"amount": {
"currencyCode": "USD",
"nanos": 780000000,
"units": 2
},
"type": "ESTIMATE"
},
"type": "TAX"
}
],
"totalPrice": {
"amount": {
"currencyCode": "USD",
"nanos": 760000000,
"units": 22
},
"type": "ESTIMATE"
}
}
}
}
}
}
}
3. ส่งการอัปเดตด้วย Orders API
Orders API เวอร์ชัน 3 จะจัดการการอัปเดตคำสั่งซื้อ คุณจึงไม่ต้องส่งคำขอ POST ไปยัง Actions API อีกต่อไป แต่คุณจะส่งคำขอ Patch ไปยัง Orders API ที่อัปเดตเนื้อหาของออบเจ็กต์ Order แทน
เรียกโทเค็นสำหรับผู้ถือใหม่
คุณใช้คีย์บัญชีบริการ JSON เดียวกันกับที่เรียกข้อมูลโทเค็นสำหรับผู้ถือสำหรับ Actions API ได้ โดยต้องขอโทเค็นสำหรับผู้ถือใหม่สำหรับ Orders API แลกเปลี่ยนคีย์บริการเป็นโทเค็นสำหรับผู้ถือ โดยใช้ไลบรารีของไคลเอ็นต์ Google APIs และขอบเขต "https://www.googleapis.com/auth/actions.order.developer"
คุณดูขั้นตอนการติดตั้งและตัวอย่างได้ที่หน้า GitHub ของไคลเอ็นต์ API
นอกจากนี้ คุณสามารถอ้างอิง order-update.js ที่อัปเดตในตัวอย่าง Java สำหรับตัวอย่างการแลกเปลี่ยนคีย์ Orders API ได้ด้วย
ส่งการอัปเดต
กระบวนการส่งการอัปเดตคำสั่งซื้อด้วย Orders API จะคล้ายกับการส่งอัปเดตด้วย Actions API แต่คุณจะส่งคำขอ Patch แทนคำขอ POST คำขอ Patch ควรมีเนื้อหา JSON ในรูปแบบต่อไปนี้
{ "orderUpdate": OrderUpdate" }
รูปแบบ OrderUpdate จะแตกต่างกันในเวอร์ชัน 3 เช่นกัน โปรดดูข้อมูลอ้างอิงคำขอแพตช์ แล้วอัปเดตช่อง OrderUpdate ให้สอดคล้องกัน ข้อมูลโค้ดต่อไปนี้แสดงตัวอย่างคำขอ Patch ที่อัปเดตสถานะของคำสั่งซื้อเป็น "DELIVERED"
// Create order update
FieldMask fieldMask = FieldMask.newBuilder().addAllPaths(Arrays.asList(
"last_update_time",
"purchase.status",
"purchase.userVisibleStatusLabel"))
.build();
OrderUpdateV3 orderUpdate = new OrderUpdateV3()
.setOrder(new OrderV3()
.setMerchantOrderId(orderId)
.setLastUpdateTime(Instant.now().toString())
.setPurchase(new PurchaseOrderExtension()
.setStatus("DELIVERED")
.setUserVisibleStatusLabel("Order delivered.")))
.setUpdateMask(FieldMaskUtil.toString(fieldMask))
.setReason("Order status was updated to delivered.");
// Setup JSON body containing order update
JsonParser parser = new JsonParser();
JsonObject orderUpdateJson =
parser.parse(new Gson().toJson(orderUpdate)).getAsJsonObject();
JsonObject body = new JsonObject();
body.add("orderUpdate", orderUpdateJson);
JsonObject header = new JsonObject();
header.addProperty("isInSandbox", true);
body.add("header", header);
StringEntity entity = new StringEntity(body.toString());
entity.setContentType(ContentType.APPLICATION_JSON.getMimeType());
request.setEntity(entity);
// Make request
HttpClient httpClient = HttpClientBuilder.create().build();
HttpResponse response = httpClient.execute(request);
จัดการสถานะการสั่งซื้อเพิ่มเติม
Orders API เวอร์ชัน 3 รองรับค่าสถานะคำสั่งซื้อเพิ่มเติมที่ไม่มีในเวอร์ชัน 2 คุณควรส่งการอัปเดตคำสั่งซื้อสำหรับทุกสถานะที่เกี่ยวข้องกับธุรกรรมแต่ละรายการ
ค่าสถานะต่อไปนี้เป็นใหม่ของเวอร์ชัน 3
IN_PREPARATION- อยู่ระหว่างการเตรียมสินค้าเพื่อจัดส่ง/จัดส่ง เช่น อาหารกำลังปรุงสุกหรือสิ่งของที่บรรจุหีบห่อREADY_FOR_PICKUP- ผู้รับสามารถมารับสินค้าได้DELIVERED- คำสั่งซื้อส่งถึงผู้รับแล้วOUT_OF_STOCK- สินค้าอย่างน้อย 1 รายการในคำสั่งซื้อนี้หมดสต็อกCHANGE_REQUESTED- ผู้ใช้ขอเปลี่ยนแปลงคำสั่งซื้อ ระบบกำลังประมวลผลการเปลี่ยนแปลง
เราเลิกใช้งานสถานะ FULFILLED แล้ว และแทนที่ด้วย DELIVERED