2019년 8월 7일부로 Orders v2 API가 지원 중단되고 Orders 버전 3으로 대체되었습니다. 이 날짜 이전에 실물 거래를 처리하는 작업을 빌드한 경우 이 가이드에 따라 주문 v3를 사용하도록 작업을 업데이트하세요.
API 변경사항
Orders API 버전 3에는 버전 2에서 다음과 같은 주요 변경사항이 있습니다.
- 요청 구조 - 버전 3 주문 구조에는 장바구니 콘텐츠만 포함하는 것이 아니라 모든 주문 세부정보가 포함됩니다.
- 주문 업데이트 - 버전 3의 Orders API는 주문 배치를 처리하는 것 외에도 주문 업데이트를 처리하므로, 엔드포인트에서 Actions API를 사용하여 사용자에게 주문에 대한 업데이트를 전송할 필요가 없습니다. 또한 상태 업데이트를 전송하는 POST 요청이 아닌 기존
order객체를 업데이트하는 PATCH 요청으로 업데이트를 Orders API에 전송합니다. - 결제 촉진 - 버전 3 Orders API로 Google Pay를 사용하는 작업은 결제 게이트웨이 세부정보를 새로운 JSON 구조로 중첩하여 EU 법률을 더 확장하고 준수할 수 있습니다.
Node.JS를 v3로 이전
Node.JS 클라이언트 라이브러리를 사용하는 작업을 이전하려면 다음 단계를 따르세요.
1. 주문 v3 플래그 추가
트랜잭션을 처리하는 데 사용한 클라이언트 라이브러리 함수가 Orders 버전 3에 맞게 업데이트됩니다. 버전 3 JSON을 전송하도록 함수를 업데이트하는 처리 코드에 플래그를 추가하기만 하면 됩니다.
처리에 다음 코드를 추가합니다.
const {dialogflow} = require('actions-on-google');
const app = dialogflow({ordersv3: true});
2. 장바구니 조합 업데이트
ProposedOrder 유형이 더 자세한 Order 객체로 대체되었습니다. JSON 참조를 참고하여 ProposedOrder 장바구니를 Order 장바구니로 변환합니다.
3. 결제 매개변수 업데이트
주문 제안 단계의 결제 정보 구조는 API 버전마다 다릅니다.
actions.intent.TRANSACTION_DECISION 인텐트 요청에서 이전 paymentOptions 객체를 새 paymentParameters 객체로 바꿉니다. 포함된 필드는 대부분 동일합니다. JSON 객체 구조에서 일부 변경사항을 제외하세요.
다음 코드 스니펫은 버전 3을 사용하는 Google Pay의 actions.intent.TRANSACTION_DECISION 인텐트 요청과 비교를 위한 이전 버전 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은 주문 업데이트를 처리하므로 더 이상 Actions API에 POST 요청을 전송할 필요가 없습니다. 대신 Order 객체의 콘텐츠를 업데이트하는 PATCH 요청을 Orders API에 전송합니다.
새 Bearer 토큰 검색
Actions API의 Bearer 토큰을 검색하는 데 사용한 것과 동일한 JSON 서비스 계정 키를 사용할 수 있으므로 Orders API의 새 Bearer 토큰을 요청해야 합니다. Google API 클라이언트 라이브러리와 "https://www.googleapis.com/auth/actions.order.developer" 범위를 사용하여 서비스 키를 Bearer 토큰으로 교환합니다.
API 클라이언트 라이브러리 GitHub 페이지에서 설치 단계 및 예시를 확인할 수 있습니다.
Order API 키 교환 예시를 위해 Node.js 샘플에서 업데이트된 order-update.js를 참조할 수도 있습니다.
업데이트 보내기
Orders API를 사용하여 주문 업데이트를 전송하는 프로세스는 Actions API를 사용하여 업데이트를 전송하는 과정과 비슷하지만 POST 요청 대신 PATCH 요청을 전송합니다. PATCH 요청은 다음 형식의 JSON 본문을 사용해야 합니다.
{ "orderUpdate": OrderUpdate" }
OrderUpdate 형식도 버전 3에서 다릅니다. PATCH 요청 참조를 확인하고 그에 따라 OrderUpdate 필드를 업데이트하세요. 다음 코드 스니펫은 주문 상태를 'DELIVERED'로 업데이트하는 PATCH 요청의 예를 보여줍니다.
// 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- 주문한 하나 이상의 상품이 재고가 없습니다.CHANGE_REQUESTED: 사용자가 주문 변경을 요청했으며 변경사항을 처리하는 중입니다.
FULFILLED 상태가 지원 중단되고 DELIVERED로 대체되었습니다.
Java를 v3로 이전
자바 클라이언트 라이브러리를 사용하는 작업을 이전하려면 다음 단계를 따르세요.
1. 장바구니 조합 업데이트
ProposedOrder 유형이 더 자세한 Order 객체로 대체되었습니다. JSON 참조를 참고하여 ProposedOrder 장바구니를 Order 장바구니로 변환합니다.
2. 결제 매개변수 업데이트
주문 제안 단계의 결제 정보 구조는 API 버전마다 다릅니다.
actions.intent.TRANSACTION_DECISION 인텐트 요청에서 이전 paymentOptions 객체를 새 paymentParameters 객체로 바꿉니다. 포함된 필드는 대부분 동일합니다. JSON 객체 구조에서 일부 변경사항을 제외하세요.
다음 코드 스니펫은 버전 3을 사용하는 Google Pay의 actions.intent.TRANSACTION_DECISION 인텐트 요청과 비교를 위한 이전 버전 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은 주문 업데이트를 처리하므로 더 이상 Actions API에 POST 요청을 전송할 필요가 없습니다. 대신 Order 객체의 콘텐츠를 업데이트하는 PATCH 요청을 Orders API에 전송합니다.
새 Bearer 토큰 검색
Actions API의 Bearer 토큰을 검색하는 데 사용한 것과 동일한 JSON 서비스 계정 키를 사용할 수 있으므로 Orders API의 새 Bearer 토큰을 요청해야 합니다. Google API 클라이언트 라이브러리와 "https://www.googleapis.com/auth/actions.order.developer" 범위를 사용하여 서비스 키를 Bearer 토큰으로 교환합니다.
API 클라이언트 라이브러리 GitHub 페이지에서 설치 단계 및 예시를 확인할 수 있습니다.
Order API 키 교환 예시로 자바 샘플에서 업데이트된 order-update.js를 참조할 수도 있습니다.
업데이트 보내기
Orders API를 사용하여 주문 업데이트를 전송하는 프로세스는 Actions API를 사용하여 업데이트를 전송하는 과정과 비슷하지만 POST 요청 대신 PATCH 요청을 전송합니다. PATCH 요청은 다음 형식의 JSON 본문을 사용해야 합니다.
{ "orderUpdate": OrderUpdate" }
OrderUpdate 형식도 버전 3에서 다릅니다. PATCH 요청 참조를 확인하고 그에 따라 OrderUpdate 필드를 업데이트하세요. 다음 코드 스니펫은 주문 상태를 'DELIVERED'로 업데이트하는 PATCH 요청의 예를 보여줍니다.
// 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- 주문한 하나 이상의 상품이 재고가 없습니다.CHANGE_REQUESTED: 사용자가 주문 변경을 요청했으며 변경사항을 처리하는 중입니다.
FULFILLED 상태가 지원 중단되고 DELIVERED로 대체되었습니다.