Kể từ ngày 7 tháng 8 năm 2019, API Đơn đặt hàng phiên bản 2 đã ngừng hoạt động và được thay thế bằng Đơn đặt hàng phiên bản 3. Nếu bạn đã tạo một Hành động xử lý các giao dịch thực trước ngày này, hãy làm theo hướng dẫn này để cập nhật Hành động của mình để sử dụng Đơn đặt hàng phiên bản 3.
Nội dung thay đổi đối với API
Phiên bản 3 của API Đơn đặt hàng có các thay đổi chính sau từ phiên bản 2:
- Cấu trúc yêu cầu – Cấu trúc đơn đặt hàng phiên bản 3 chứa tất cả thông tin chi tiết về đơn đặt hàng thay vì chỉ chứa nội dung giỏ hàng.
- Cập nhật đơn đặt hàng – API đơn đặt hàng phiên bản 3 xử lý thông tin cập nhật về đơn đặt hàng ngoài việc xử lý vị trí đơn đặt hàng, vì vậy, điểm cuối của bạn không cần sử dụng Actions API để gửi cho người dùng thông tin cập nhật về đơn đặt hàng của họ. Bạn cũng sẽ gửi thông tin cập nhật dưới dạng yêu cầu PATCH tới API đơn đặt hàng để cập nhật đối tượng
orderhiện có, thay vì yêu cầu POST để gửi thông tin cập nhật trạng thái. - Tạo điều kiện thanh toán – Những hành động sử dụng Google Pay với API Đơn đặt hàng phiên bản 3 sẽ lồng thông tin cổng thanh toán theo cấu trúc JSON mới để cho phép mở rộng hơn và tuân thủ luật pháp của Liên minh Châu Âu.
Di chuyển Node.JS sang phiên bản 3
Hãy làm theo các bước sau để di chuyển một Hành động sử dụng thư viện ứng dụng Node.JS.
1. Thêm cờ Đơn đặt hàng phiên bản 3
Hàm thư viện ứng dụng mà bạn đã dùng để xử lý giao dịch sẽ được cập nhật cho Đơn đặt hàng phiên bản 3, bạn chỉ cần thêm một cờ vào mã phương thức thực hiện để cập nhật các hàm để gửi JSON phiên bản 3.
Thêm mã sau vào phương thức thực hiện của bạn:
const {dialogflow} = require('actions-on-google');
const app = dialogflow({ordersv3: true});
2. Cập nhật cụm giỏ hàng của bạn
Loại ProposedOrder đã được thay thế bằng đối tượng Order chi tiết hơn. Tham khảo JSON để chuyển đổi giỏ hàng ProposedOrder của bạn thành giỏ hàng Order.
3. Cập nhật thông số thanh toán
Cấu trúc thông tin thanh toán trong bước đề xuất đặt hàng sẽ khác nhau giữa các phiên bản API.
Trong yêu cầu ý định actions.intent.TRANSACTION_DECISION, hãy thay thế đối tượng paymentOptions cũ bằng đối tượng paymentParameters mới. Hầu hết các trường chứa đều giống nhau, hãy lưu một số thay đổi đối với cấu trúc của đối tượng JSON.
Các đoạn mã sau đây minh hoạ một yêu cầu ý định actions.intent.TRANSACTION_DECISION mẫu đối với Google Pay sử dụng phiên bản 3 và một yêu cầu so sánh phiên bản 2 cũ.
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,
}));
Xin lưu ý rằng JSON của Dialogflow dưới đây mô tả một phản hồi bằng webhook.
{
"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"
}
}
}
}
}
}
}
Xin lưu ý rằng JSON của Dialogflow dưới đây mô tả một phản hồi bằng webhook.
{
"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. Gửi nội dung cập nhật bằng API đơn đặt hàng
Phiên bản 3 của API Đơn đặt hàng xử lý thông tin cập nhật về đơn đặt hàng, vì vậy, bạn không cần gửi yêu cầu POST tới API Actions nữa. Thay vào đó, bạn gửi yêu cầu PATCH tới API đơn đặt hàng để cập nhật nội dung của đối tượng Order.
Truy xuất mã thông báo truy xuất mới cho người dùng
Bạn có thể sử dụng chính khoá tài khoản dịch vụ JSON mà bạn đã dùng để truy xuất mã thông báo truy cập cho Actions API. Bạn cần yêu cầu một mã thông báo truy cập mới cho API Đơn đặt hàng. Trao đổi khoá dịch vụ lấy mã thông báo truy cập bằng cách sử dụng thư viện ứng dụng API của Google và phạm vi "https://www.googleapis.com/auth/actions.order.developer".
Bạn có thể tìm thấy các bước cài đặt và ví dụ trên trang GitHub của thư viện ứng dụng API.
Bạn cũng có thể tham khảo order-update.js đã cập nhật trong mẫu Node.js của chúng tôi để xem ví dụ về việc trao đổi khoá API Đơn đặt hàng.
Gửi thông tin cập nhật
Quá trình gửi cập nhật đơn đặt hàng bằng API đơn đặt hàng cũng tương tự như gửi thông tin cập nhật bằng Actions API, mặc dù bạn gửi yêu cầu PATCH thay vì yêu cầu POST. Yêu cầu PATCH phải có nội dung JSON có định dạng sau:
{ "orderUpdate": OrderUpdate" }
Định dạng OrderUpdate cũng khác trong phiên bản 3. Hãy xem tài liệu tham khảo về yêu cầu PaTCH và cập nhật các trường OrderUpdate của bạn cho phù hợp. Đoạn mã sau đây cho thấy một yêu cầu PATCH mẫu cập nhật trạng thái của đơn đặt hàng thành "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;
}
});
});
Xử lý các trạng thái khác của đơn đặt hàng
Phiên bản 3 của API đơn đặt hàng hỗ trợ các giá trị trạng thái đơn đặt hàng bổ sung không có trong phiên bản 2. Bạn nên gửi thông tin cập nhật về đơn đặt hàng cho mọi trạng thái liên quan đến từng giao dịch.
Các giá trị trạng thái sau đây là giá trị mới đối với phiên bản 3:
IN_PREPARATION– Đơn đặt hàng đang được chuẩn bị để vận chuyển/giao hàng, chẳng hạn như thức ăn đang nấu hoặc một mặt hàng đang đóng gói.READY_FOR_PICKUP- Người nhận có thể đến lấy đơn đặt hàng.DELIVERED- Đơn đặt hàng đã được giao tới người nhậnOUT_OF_STOCK– Một hoặc nhiều mặt hàng trong đơn đặt hàng đã hết hàng.CHANGE_REQUESTED– Người dùng đã yêu cầu thay đổi đơn đặt hàng và thay đổi đó đang được xử lý.
Ngừng sử dụng trạng thái FULFILLED và thay thế bằng DELIVERED.
Di chuyển Java sang phiên bản 3
Hãy làm theo các bước sau để di chuyển một Hành động sử dụng thư viện ứng dụng Java.
1. Cập nhật cụm giỏ hàng của bạn
Loại ProposedOrder đã được thay thế bằng đối tượng Order chi tiết hơn. Tham khảo JSON để chuyển đổi giỏ hàng ProposedOrder của bạn thành giỏ hàng Order.
2. Cập nhật thông số thanh toán
Cấu trúc thông tin thanh toán trong bước đề xuất đặt hàng sẽ khác nhau giữa các phiên bản API.
Trong yêu cầu ý định actions.intent.TRANSACTION_DECISION, hãy thay thế đối tượng paymentOptions cũ bằng đối tượng paymentParameters mới. Hầu hết các trường chứa đều giống nhau, hãy lưu một số thay đổi đối với cấu trúc của đối tượng JSON.
Các đoạn mã sau đây minh hoạ một yêu cầu ý định actions.intent.TRANSACTION_DECISION mẫu đối với Google Pay sử dụng phiên bản 3 và một yêu cầu so sánh phiên bản 2 cũ.
// 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();
Xin lưu ý rằng JSON của Dialogflow dưới đây mô tả một phản hồi bằng webhook.
{
"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"
}
}
}
}
}
}
}
Xin lưu ý rằng JSON của Dialogflow dưới đây mô tả một phản hồi bằng webhook.
{
"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. Gửi nội dung cập nhật bằng API đơn đặt hàng
Phiên bản 3 của API Đơn đặt hàng xử lý thông tin cập nhật về đơn đặt hàng, vì vậy, bạn không cần gửi yêu cầu POST tới API Actions nữa. Thay vào đó, bạn gửi yêu cầu PATCH tới API đơn đặt hàng để cập nhật nội dung của đối tượng Order.
Truy xuất mã thông báo truy xuất mới cho người dùng
Bạn có thể sử dụng chính khoá tài khoản dịch vụ JSON mà bạn đã dùng để truy xuất mã thông báo truy cập cho Actions API. Bạn cần yêu cầu một mã thông báo truy cập mới cho API Đơn đặt hàng. Trao đổi khoá dịch vụ lấy mã thông báo truy cập bằng cách sử dụng thư viện ứng dụng API của Google và phạm vi "https://www.googleapis.com/auth/actions.order.developer".
Bạn có thể tìm thấy các bước cài đặt và ví dụ trên trang GitHub của thư viện ứng dụng API.
Bạn cũng có thể tham khảo order-update.js đã cập nhật trong mẫu Java của chúng tôi để xem ví dụ về việc trao đổi khoá API Đơn đặt hàng.
Gửi thông tin cập nhật
Quá trình gửi cập nhật đơn đặt hàng bằng API đơn đặt hàng cũng tương tự như gửi thông tin cập nhật bằng Actions API, mặc dù bạn gửi yêu cầu PATCH thay vì yêu cầu POST. Yêu cầu PATCH phải có nội dung JSON có định dạng sau:
{ "orderUpdate": OrderUpdate" }
Định dạng OrderUpdate cũng khác trong phiên bản 3. Hãy xem tài liệu tham khảo về yêu cầu PaTCH và cập nhật các trường OrderUpdate của bạn cho phù hợp. Đoạn mã sau đây cho thấy một yêu cầu PATCH mẫu cập nhật trạng thái của đơn đặt hàng thành "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);
Xử lý các trạng thái khác của đơn đặt hàng
Phiên bản 3 của API đơn đặt hàng hỗ trợ các giá trị trạng thái đơn đặt hàng bổ sung không có trong phiên bản 2. Bạn nên gửi thông tin cập nhật về đơn đặt hàng cho mọi trạng thái liên quan đến từng giao dịch.
Các giá trị trạng thái sau đây là giá trị mới đối với phiên bản 3:
IN_PREPARATION– Đơn đặt hàng đang được chuẩn bị để vận chuyển/giao hàng, chẳng hạn như thức ăn đang nấu hoặc một mặt hàng đang đóng gói.READY_FOR_PICKUP- Người nhận có thể đến lấy đơn đặt hàng.DELIVERED- Đơn đặt hàng đã được giao tới người nhậnOUT_OF_STOCK– Một hoặc nhiều mặt hàng trong đơn đặt hàng đã hết hàng.CHANGE_REQUESTED– Người dùng đã yêu cầu thay đổi đơn đặt hàng và thay đổi đó đang được xử lý.
Ngừng sử dụng trạng thái FULFILLED và thay thế bằng DELIVERED.