Kể từ ngày 7 tháng 8 năm 2019, Orders v2 API không còn được dùng nữa và được thay thế bằng Orders phiên bản 3. Nếu bạn đã tạo một Hành động xử lý giao dịch thực trước khi vào ngày này, hãy làm theo hướng dẫn này để cập nhật Hành động để 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 Orders API có các thay đổi quan trọng sau đây so với 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ả chi tiết đơn đặt hàng thay vì chỉ chứa nội dung giỏ hàng.
- Thông tin cập nhật về đơn đặt hàng – Orders API phiên bản 3 xử lý thông tin cập nhật về đơn đặt hàng trong
ngoài việc xử lý vị trí đặt hàng, vì vậy điểm cuối của bạn không cần
sử dụng API Hành động để 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 gửi
cập nhật khi PATCH yêu cầu đối với Orders API cập nhật
order, thay vì các yêu cầu POST để gửi thông tin cập nhật trạng thái. - Hỗ trợ thanh toán – Những hành động sử dụng Google Pay phiên bản 3 Orders API lồng thông tin về cổng thanh toán vào một cấu trúc JSON mới cho phép mở rộng 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ờ Orders v3
Các hàm thư viện ứng dụng mà bạn dùng để xử lý giao dịch sẽ được cập nhật đối với Đơn đặt hàng phiên bản 3, bạn chỉ cần thêm cờ vào mã thực hiện đơn hàng 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ách lắp ráp giỏ hàng
ProposedOrder
loại đã được thay thế bằng Order chi tiết hơn
. Tham khảo tệp JSON để chuyển đổi giỏ hàng ProposedOrder của bạn thành
một giỏ hàng Order.
3. Cập nhật thông số thanh toán
Cấu trúc của thông tin thanh toán trong bước đề xuất đơn đặt hàng là khác nhau giữa các phiên bản API.
Trong yêu cầu ý định actions.intent.TRANSACTION_DECISION của bạn, hãy thay thế nội dung cũ
paymentOptions với đối tượng paymentParameters mới. Hầu hết
các trường được chứa là giống nhau, lưu lại một số thay đổi đối với đối tượng JSON
cấu trúc.
Các đoạn mã sau đây cho thấy một ví dụ về actions.intent.TRANSACTION_DECISION
ý định gửi cho Google Pay bằng phiên bản 3 và yêu cầu phiên bản 2 cũ cho
so sánh.
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 Dialogflow bên dưới mô tả phản hồi 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 Dialogflow bên dưới mô tả phản hồi 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 Orders API
Phiên bản 3 của Orders API xử lý việc cập nhật đơn đặt hàng, vì vậy, bạn không cần
gửi yêu cầu POST đến API Actions. Thay vào đó, bạn sẽ gửi yêu cầu PATCH
đối với Orders API cập nhật nội dung của đối tượng Order.
Truy xuất mã thông báo truyền tải mới
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 mang cho API Actions, bạn cần yêu cầu một mã thông báo mang mới cho Orders API. 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à "https://www.googleapis.com/auth/actions.order.developer" phạm vi.
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ề trao đổi khoá API Orders.
Gửi nội dung cập nhật
Quy trình gửi thông tin cập nhật đơn đặt hàng bằng Orders API tương tự như gửi các bản cập nhật bằng Actions API, cho dù bạn gửi yêu cầu PATCH thay vì yêu cầu POST. Yêu cầu PATCH phải lấy phần nội dung JSON của định dạng sau:
{ "orderUpdate": OrderUpdate" }
Định dạng OrderUpdate cũng khác trong phiên bản 3. Tham khảo tài liệu tham khảo về yêu cầu PaTCH
và cập nhật các trường OrderUpdate cho phù hợp. Đoạn mã sau đây
hiển thị một yêu cầu PATCH mẫu cập nhật trạng thái của một đơ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 bổ sung của đơn đặt hàng
Phiên bản 3 của Orders API hỗ trợ thêm các giá trị trạng thái đơn đặt hàng mà 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 có 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 phẩm đang được nấu chín hoặc một mặt hàng được đó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 cho 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 đối với đơn đặt hàng và thay đổi đó đang được xử lý.
Trạng thái FULFILLED không được dùng nữa và được 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ách lắp ráp giỏ hàng
ProposedOrder
loại đã được thay thế bằng Order chi tiết hơn
. Tham khảo tệp JSON để chuyển đổi giỏ hàng ProposedOrder của bạn thành
một giỏ hàng Order.
2. Cập nhật thông số thanh toán
Cấu trúc của thông tin thanh toán trong bước đề xuất đơn đặt hàng là khác nhau giữa các phiên bản API.
Trong yêu cầu ý định actions.intent.TRANSACTION_DECISION của bạn, hãy thay thế nội dung cũ
paymentOptions với đối tượng paymentParameters mới. Hầu hết
các trường được chứa là giống nhau, lưu lại một số thay đổi đối với đối tượng JSON
cấu trúc.
Các đoạn mã sau đây cho thấy một ví dụ về actions.intent.TRANSACTION_DECISION
ý định gửi cho Google Pay bằng phiên bản 3 và yêu cầu phiên bản 2 cũ cho
so sánh.
// 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 Dialogflow bên dưới mô tả phản hồi 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 Dialogflow bên dưới mô tả phản hồi 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 Orders API
Phiên bản 3 của Orders API xử lý việc cập nhật đơn đặt hàng, vì vậy, bạn không cần
gửi yêu cầu POST đến API Actions. Thay vào đó, bạn sẽ gửi yêu cầu PATCH
đối với Orders API cập nhật nội dung của đối tượng Order.
Truy xuất mã thông báo truyền tải mới
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 mang cho API Actions, bạn cần yêu cầu một mã thông báo mang mới cho Orders API. 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à "https://www.googleapis.com/auth/actions.order.developer" phạm vi.
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ề trao đổi khoá API Orders.
Gửi nội dung cập nhật
Quy trình gửi thông tin cập nhật đơn đặt hàng bằng Orders API tương tự như gửi các bản cập nhật bằng Actions API, cho dù bạn gửi yêu cầu PATCH thay vì yêu cầu POST. Yêu cầu PATCH phải lấy phần nội dung JSON của định dạng sau:
{ "orderUpdate": OrderUpdate" }
Định dạng OrderUpdate cũng khác trong phiên bản 3. Tham khảo tài liệu tham khảo về yêu cầu PaTCH
và cập nhật các trường OrderUpdate cho phù hợp. Đoạn mã sau đây
hiển thị một yêu cầu PATCH mẫu cập nhật trạng thái của một đơ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 bổ sung của đơn đặt hàng
Phiên bản 3 của Orders API hỗ trợ thêm các giá trị trạng thái đơn đặt hàng mà 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 có 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 phẩm đang được nấu chín hoặc một mặt hàng được đó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 cho 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 đối với đơn đặt hàng và thay đổi đó đang được xử lý.
Trạng thái FULFILLED không được dùng nữa và được thay thế bằng DELIVERED.