7 sierpnia 2019 roku interfejs API Orders w wersji 2 został wycofany i zastąpiony przez Orders w wersji 3. Jeśli masz akcję, która obsługuje transakcje fizyczne przed tą datą, zaktualizuj ją zgodnie z tym przewodnikiem, aby używać Zamówienia w wersji 3.
Zmiany w interfejsie API
W porównaniu z wersją 3 interfejsu Orders API w porównaniu z wersją 2 wprowadziliśmy te najważniejsze zmiany:
- Struktura żądania – struktura zamówienia w wersji 3 zawiera wszystkie szczegóły zamówienia, a nie tylko zawartość koszyka.
- Aktualizacje zamówień – interfejs Orders API w wersji 3 oprócz obsługi składania zamówień obsługuje aktualizacje zamówień. Dzięki temu Twój punkt końcowy nie musi używać interfejsu Actions API do wysyłania użytkownikom aktualnych informacji o zamówieniach. Aktualizacje wysyłasz też do interfejsu Orders API jako żądania PATCH, które aktualizują istniejący obiekt
order, a nie jako żądania POST w celu wysyłania aktualizacji stanu. - Ułatwianie płatności – działania korzystające z Google Pay w wersji 3 interfejsu Orders API umieszczają szczegóły bramy płatności w nowej strukturze JSON, co zapewnia większą elastyczność i zgodność z przepisami Unii Europejskiej.
Migracja Node.JS do wersji 3
Wykonaj te czynności, aby przenieść akcję, która korzysta z biblioteki klienta Node.JS.
1. Dodaj flagę zamówień (wersja 3)
Funkcje biblioteki klienta, z których korzystasz do obsługi transakcji, zostały zaktualizowane w przypadku zamówień w wersji 3. Wystarczy, że do kodu realizacji zamówienia dodasz flagę, która zaktualizuje funkcje wysyłania kodu JSON w wersji 3.
Dodaj do realizacji ten kod:
const {dialogflow} = require('actions-on-google');
const app = dialogflow({ordersv3: true});
2. Aktualizowanie zestawu koszyka
Typ ProposedOrder został zastąpiony bardziej szczegółowym obiektem Order. Zapoznaj się z informacjami o formacie JSON, aby przekonwertować koszyk w usłudze ProposedOrder na koszyk Order.
3. Zaktualizuj parametry płatności
Struktura informacji o płatności na kroku dotyczącym oferty pakietowej różni się w zależności od wersji interfejsu API.
W żądaniu intencji actions.intent.TRANSACTION_DECISION zastąp stary obiekt paymentOptions nowym obiektem paymentParameters. Większość zawartych pól jest taka sama. Zapisz zmiany w strukturze obiektu JSON.
Poniższe fragmenty kodu pokazują przykład żądania actions.intent.TRANSACTION_DECISION dotyczącego zamiaru przesłania go do Google Pay w wersji 3 oraz starszej wersji 2 żądania na potrzeby porównania.
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,
}));
Pamiętaj, że poniższy plik JSON Dialogflow opisuje odpowiedź webhooka.
{
"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"
}
}
}
}
}
}
}
Pamiętaj, że poniższy plik JSON Dialogflow opisuje odpowiedź webhooka.
{
"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. Wysyłaj aktualizacje za pomocą interfejsu Orders API
Wersja 3 interfejsu Orders API obsługuje aktualizacje zamówień, więc nie musisz już wysyłać żądań POST do Actions API. Zamiast tego wysyłasz do interfejsu Orders API żądanie PATCH, które aktualizuje zawartość obiektu Order.
Pobierz nowy token okaziciela
Możesz użyć tego samego klucza konta usługi JSON co do pobierania tokena okaziciela dla Actions API. Musisz poprosić o nowy token okaziciela dla interfejsu Orders API. Wymień klucz usługi na token okaziciela, korzystając z biblioteki klienta interfejsów API Google i zakresu "https://www.googleapis.com/auth/actions.order.developer".
Instrukcje instalacji i przykłady znajdziesz na stronie w GitHubie w bibliotece klienta interfejsu API.
Możesz też zapoznać się ze zaktualizowanym order-update.js w naszym przykładzie Node.js, aby zobaczyć przykładową wymianę kluczy interfejsu Orders API.
Wysyłaj aktualności
Proces wysyłania aktualizacji zamówienia za pomocą interfejsu Orders API jest podobny do wysyłania aktualizacji za pomocą interfejsu Actions API, jednak zamiast żądania POST wysyłasz żądanie PATCH. Żądanie PATCH powinno mieć treść JSON w tym formacie:
{ "orderUpdate": OrderUpdate" }
Format OrderUpdate również różni się w wersji 3. Zapoznaj się z dokumentacją żądania PATCH i odpowiednio zaktualizuj pola OrderUpdate. Ten fragment kodu pokazuje przykładowe żądanie PATCH, które aktualizuje stan zamówienia na „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;
}
});
});
Obsługa dodatkowych stanów zamówień
Wersja 3 interfejsu Orders API obsługuje dodatkowe wartości stanu zamówienia, które były niedostępne w wersji 2. Aktualizacje zamówień należy wysyłać w przypadku każdego stanu odpowiadającego danej transakcji.
W wersji 3 wprowadzono te wartości stanu:
IN_PREPARATION– zamówienie jest przygotowywane do wysyłki/dostawy, np. gotowanie lub pakowanie przedmiotu.READY_FOR_PICKUP– zamówienie może zostać odebrane przez odbiorcę.DELIVERED– zamówienie zostało dostarczone do odbiorcyOUT_OF_STOCK– co najmniej jeden produkt w zamówieniu jest niedostępny.CHANGE_REQUESTED– użytkownik poprosił o zmianę zamówienia, która jest przetwarzana.
Stan FULFILLED został wycofany i zastąpiony przez DELIVERED.
Migracja z Javy do wersji 3
Wykonaj te czynności, aby przenieść akcję, która korzysta z biblioteki klienta w Javie.
1. Aktualizowanie zestawu koszyka
Typ ProposedOrder został zastąpiony bardziej szczegółowym obiektem Order. Zapoznaj się z informacjami o formacie JSON, aby przekonwertować koszyk w usłudze ProposedOrder na koszyk Order.
2. Zaktualizuj parametry płatności
Struktura informacji o płatności na kroku dotyczącym oferty pakietowej różni się w zależności od wersji interfejsu API.
W żądaniu intencji actions.intent.TRANSACTION_DECISION zastąp stary obiekt paymentOptions nowym obiektem paymentParameters. Większość zawartych pól jest taka sama. Zapisz zmiany w strukturze obiektu JSON.
Poniższe fragmenty kodu pokazują przykład żądania actions.intent.TRANSACTION_DECISION dotyczącego zamiaru przesłania go do Google Pay w wersji 3 oraz starszej wersji 2 żądania na potrzeby porównania.
// 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();
Pamiętaj, że poniższy plik JSON Dialogflow opisuje odpowiedź webhooka.
{
"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"
}
}
}
}
}
}
}
Pamiętaj, że poniższy plik JSON Dialogflow opisuje odpowiedź webhooka.
{
"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. Wysyłaj aktualizacje za pomocą interfejsu Orders API
Wersja 3 interfejsu Orders API obsługuje aktualizacje zamówień, więc nie musisz już wysyłać żądań POST do Actions API. Zamiast tego wysyłasz do interfejsu Orders API żądanie PATCH, które aktualizuje zawartość obiektu Order.
Pobierz nowy token okaziciela
Możesz użyć tego samego klucza konta usługi JSON co do pobierania tokena okaziciela dla Actions API. Musisz poprosić o nowy token okaziciela dla interfejsu Orders API. Wymień klucz usługi na token okaziciela, korzystając z biblioteki klienta interfejsów API Google i zakresu "https://www.googleapis.com/auth/actions.order.developer".
Instrukcje instalacji i przykłady znajdziesz na stronie w GitHubie w bibliotece klienta interfejsu API.
Możesz też zapoznać się ze zaktualizowanym order-update.js w naszym przykładzie w języku Java, aby zobaczyć przykładową wymianę kluczy interfejsu Orders API.
Wysyłaj aktualności
Proces wysyłania aktualizacji zamówienia za pomocą interfejsu Orders API jest podobny do wysyłania aktualizacji za pomocą interfejsu Actions API, jednak zamiast żądania POST wysyłasz żądanie PATCH. Żądanie PATCH powinno mieć treść JSON w tym formacie:
{ "orderUpdate": OrderUpdate" }
Format OrderUpdate również różni się w wersji 3. Zapoznaj się z dokumentacją żądania PATCH i odpowiednio zaktualizuj pola OrderUpdate. Ten fragment kodu pokazuje przykładowe żądanie PATCH, które aktualizuje stan zamówienia na „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);
Obsługa dodatkowych stanów zamówień
Wersja 3 interfejsu Orders API obsługuje dodatkowe wartości stanu zamówienia, które były niedostępne w wersji 2. Aktualizacje zamówień należy wysyłać w przypadku każdego stanu odpowiadającego danej transakcji.
W wersji 3 wprowadzono te wartości stanu:
IN_PREPARATION– zamówienie jest przygotowywane do wysyłki/dostawy, np. gotowanie lub pakowanie przedmiotu.READY_FOR_PICKUP– zamówienie może zostać odebrane przez odbiorcę.DELIVERED– zamówienie zostało dostarczone do odbiorcyOUT_OF_STOCK– co najmniej jeden produkt w zamówieniu jest niedostępny.CHANGE_REQUESTED– użytkownik poprosił o zmianę zamówienia, która jest przetwarzana.
Stan FULFILLED został wycofany i zastąpiony przez DELIVERED.