Dopo la chiamata di pagamento, l'utente esamina il carrello aggiornato con tasse, spese di spedizione, sconti e altri addebiti restituiti. L'utente conferma e invia l'ordine e Google invia al tuo endpoint di evasione una richiesta JSON contenente le informazioni relative all'ordine. Il servizio web deve ricevere l'ordine, elaborarlo e rispondere a Google indicando lo stato dell'ordine.
Questa sezione descrive il formato del messaggio di richiesta dell'ordine inviato da Google,
chiamato SubmitOrderRequestMessage, e il formato del messaggio di risposta
che devi fornire, chiamato
SubmitOrderResponseMessage.
Per ulteriori informazioni sul ciclo di vita dell'evasione degli ordini, consulta la Panoramica dell'evasione degli ordini.
Implementazione dell'evasione degli ordini
Il servizio web end-to-end di ordinazione creato per funzionare con l'end-to-end di ordinazione deve includere un endpoint URL per la ricezione dei messaggi degli ordini da Google. Per l'elaborazione degli ordini, il tuo servizio web riceve un codice SubmitOrderRequestMessage in formato JSON come richiesta POST da Google. Questa richiesta contiene l'ordine di un cliente, incluse tasse, commissioni e dati di pagamento. Quando ricevi una richiesta di invio di un ordine, il tuo servizio web deve:
- Controllare l'idoneità delle transazioni, ad esempio la verifica della carta o il rilevamento di attività fraudolente.
- Crea un ordine nel tuo sistema.
- Autorizza il metodo di pagamento e, se applicabile, chiama l'API Charge dell'elaboratore dei pagamenti.
- Rispondi indicando lo stato appropriato dell'ordine:
CREATED,CONFIRMEDoREJECTED.
Dopo l'elaborazione dell'ordine, il codice di evasione deve fornire una risposta
sotto forma di messaggio JSON SubmitOrderResponseMessage a Google.
Per ulteriori informazioni sui requisiti di implementazione del servizio web per l'evasione degli ordini end-to-end, consulta la Panoramica dell'evasione degli ordini.
Messaggio di richiesta dell'ordine
Quando un cliente sceglie di effettuare un ordine durante il flusso end-to-end dell'ordine, Google invia una richiesta al tuo servizio web con un messaggio JSON chiamato SubmitOrderRequestMessage contenente i seguenti dati:
- Intent:il campo
inputs[0].intentdel corpo di ogni richiesta di ordine di invio contiene il valore della stringaactions.intent.TRANSACTION_DECISION. - Ordine: il campo
inputs[0].arguments[0].transactionDecisionValuedi una richiesta di invio dell'ordine contiene un oggettoOrderche rappresenta l'ordine del cliente da effettuare, insieme ai dettagli di pagamento. - Flag sandbox: il campo
isInSandboxdi una richiesta di invio di un ordine indica se la transazione utilizza pagamenti sandbox.
Esempio di richiesta di ordine
Di seguito è riportato un esempio di SubmitOrderRequestMessage:
JSON
{
"user": {},
"conversation": {
"conversationId": "CTKbKfUlHCyDEdcz_5PBJTtf"
},
"inputs": [
{
"intent": "actions.intent.TRANSACTION_DECISION",
"arguments": [
{
"transactionDecisionValue": {
"order": {
"finalOrder": {
"cart": {
"merchant": {
"id": "restaurant/Restaurant/QWERTY",
"name": "Tep Tep Chicken Club"
},
"lineItems": [
{
"name": "Spicy Fried Chicken",
"type": "REGULAR",
"id": "299977679",
"quantity": 2,
"price": {
"type": "ESTIMATE",
"amount": {
"currencyCode": "AUD",
"units": "39",
"nanos": 600000000
}
},
"offerId": "MenuItemOffer/QWERTY/scheduleId/496/itemId/143",
"extension": {
"@type": "type.googleapis.com/google.actions.v2.orders.FoodItemExtension"
}
}
],
"extension": {
"@type": "type.googleapis.com/google.actions.v2.orders.FoodCartExtension",
"fulfillmentPreference": {
"fulfillmentInfo": {
"delivery": {
"deliveryTimeIso8601": "P0M"
}
}
},
"location": {
"coordinates": {
"latitude": -33.8376441,
"longitude": 151.0868736
},
"formattedAddress": "Killoola St, 1, Concord West NSW 2138",
"zipCode": "2138",
"city": "Concord West",
"postalAddress": {
"regionCode": "AU",
"postalCode": "2138",
"administrativeArea": "NSW",
"locality": "Concord West",
"addressLines": [
"Killoola St",
"1"
]
}
},
"contact": {
"displayName": "Hab Sy",
"email": "hab9878.sy@gmail.com",
"phoneNumber": "+61000000000",
"firstName": "Hab",
"lastName": "Sy"
}
}
},
"otherItems": [
{
"name": "Delivery fee",
"type": "DELIVERY",
"price": {
"type": "ESTIMATE",
"amount": {
"currencyCode": "AUD",
"units": "3",
"nanos": 500000000
}
}
},
{
"name": "Subtotal",
"type": "SUBTOTAL",
"price": {
"type": "ESTIMATE",
"amount": {
"currencyCode": "AUD",
"units": "39",
"nanos": 600000000
}
}
}
],
"totalPrice": {
"type": "ESTIMATE",
"amount": {
"currencyCode": "AUD",
"units": "43",
"nanos": 100000000
}
},
"extension": {
"@type": "type.googleapis.com/google.actions.v2.orders.FoodOrderExtension"
}
},
"googleOrderId": "01412971004192156198",
"orderDate": "2020-10-22T09:02:06.173Z",
"paymentInfo": {
"displayName": "Pay when you get your food",
"paymentType": "ON_FULFILLMENT"
}
}
}
}
]
}
],
"directActionOnly": true,
"isInSandbox": true
}
Messaggio di risposta all'ordine
Dopo aver ricevuto una richiesta, il servizio web end-to-end di ordinazione elabora la richiesta e ti invia un SubmitOrderResponseMessage che include i seguenti dati:
OrderUpdate: un oggetto contenente lo stato dell'ordine e le eventuali azioni post-ordine disponibili per l'utente, come contattare l'assistenza e visualizzare i dettagli dell'ordine, che definisci nel campofinalResponse.richResponse.items[0].structuredResponse.orderUpdatedella risposta.
Campo di aggiornamento dell'ordine
Quando il tuo servizio web invia un SubmitOrderResponseMessage, contiene un campo OrderUpdate che include i seguenti campi:
actionOrderId: l'ID univoco dell'ordine, utilizzato per identificare in modo univoco l'ordine nel tuo sistema e farvi riferimento quando invii i successivi aggiornamenti dell'ordine.orderState: un oggettoOrderStateche rappresenta lo stato dell'ordine.orderManagementActions: azioni post-ordine disponibili per l'utente, ad esempio contattare l'assistenza clienti e visualizzare i dettagli dell'ordine.totalPrice: il prezzo totale dell'ordine. Questa opzione è facoltativa. Inviala solo se il prezzo totale dell'ordine è cambiato dopo l'invio.
Un ordine può avere uno dei seguenti stati:
CREATED: l'endpoint di evasione degli ordini ha elaborato l'ordine correttamente, ma il fornitore non ha ancora confermato l'ordine.CONFIRMED: l'endpoint di evasione degli ordini ha elaborato l'ordine e il fornitore lo ha confermato.REJECTED: si è verificato un problema e l'endpoint di evasione degli ordini non ha potuto creare o confermare l'ordine, il che potrebbe includere problemi con il pagamento.
Se imposti lo stato di un ordine su REJECTED, specifica il motivo nel campo rejectionInfo di OrderUpdate. Utilizza i valori FoodOrderUpdateExtension.FoodOrderErrors in combinazione con rejectionInfo di tipo UNKNOWN e fornisci una descrizione.
Esempio di risposta all'ordine
Di seguito è riportato un esempio di SubmitOrderResponseMessage:
JSON
{
"finalResponse": {
"richResponse": {
"items": [
{
"structuredResponse": {
"orderUpdate": {
"actionOrderId": "1603357328160",
"orderState": {
"state": "CONFIRMED",
"label": "Pending"
},
"updateTime": "2020-10-22T02:02:08-07:00",
"orderManagementActions": [
{
"type": "CUSTOMER_SERVICE",
"button": {
"title": "Call customer service",
"openUrlAction": {
"url": "tel:+61234561000"
}
}
},
{
"type": "VIEW_DETAILS",
"button": {
"title": "View order details",
"openUrlAction": {
"url": "https://partner.com/view/orderstatus"
}
}
}
],
"receipt": {
"userVisibleOrderId": "BXZ-1603357328"
}
}
}
}
]
}
}
}
Richiesta non riuscita
Se una richiesta di invio non va a buon fine, SubmitOrderResponseMessage deve impostare OrderState.state su REJECTED. La risposta deve includere anche RejectionInfo, che contiene un oggetto RejectionType per descrivere il tipo di errore.
Esempio di risposta non riuscita
JSON
{
"expectUserResponse": false,
"finalResponse": {
"richResponse": {
"items": [
{
"structuredResponse": {
"orderUpdate": {
"actionOrderId": "sample_action_order_id",
"orderState": {
"state": "REJECTED",
"label": "Order rejected"
},
"updateTime": "2017-05-10T02:30:00.000Z",
"rejectionInfo": {
"type": "PAYMENT_DECLINED",
"reason": "Insufficient funds"
},
"orderManagementActions": [
{
"type": "CUSTOMER_SERVICE",
"button": {
"title": "Contact customer service",
"openUrlAction": {
"url": "mailto:support@example.com"
}
}
},
{
"type": "EMAIL",
"button": {
"title": "Email restaurant",
"openUrlAction": {
"url": "mailto:person@example.com"
}
}
},
{
"type": "CALL",
"button": {
"title": "Call restaurant",
"openUrlAction": {
"url": "tel:+16505554679"
}
}
},
{
"type": "VIEW_DETAILS",
"button": {
"title": "View order",
"openUrlAction": {
"url": "https://orderview.partner.com?orderid=sample_action_order_id"
}
}
}
]
}
}
}
]
}
}
}
Invia implementazione ordine
Quando implementi l'API di invio dell'ordine, devi seguire questi passaggi.
Convalida
- Esegui le convalide del servizio, del carrello e delle promozioni come indicato in Configurare il pagamento.
- Se necessario, restituisci RejectionInfo con uno dei seguenti tipi:
| RejectionInfoType | Caso d'uso |
|---|---|
UNAVAILABLE_SLOT |
L'ora di evasione non è più valida. |
PROMO_USER_INELIGIBLE |
Utilizza l'indirizzo email nell'oggetto Contact della richiesta per convalidare l'idoneità alla promozione per l'utente. Consulta l'esempio per implementare l'invio dell'ordine con le promozioni. |
INELIGIBLE |
|
PAYMENT_DECLINED |
Impossibile elaborare il pagamento. Ad esempio, la causa potrebbe essere un'insufficienza di fondi. |
UNKNOWN |
Per qualsiasi altro errore di convalida. |
Imposta OrderState.state su REJECTED se si verificano errori di convalida. Se vuoi, puoi specificare un motivo di rifiuto specifico
utilizzando FoodOrderUpdateExtension.foodOrderErrors. Vedi gli esempi nella sezione relativa all'invio della convalida dell'ordine.
Elabora il pagamento
- Calcola il valore
totalPriceaggiungendo il prezzo del carrello, le commissioni, lo sconto, le tasse e la mancia.totalPricedeve corrispondere al valoretotalPricerestituito in CheckoutResponseMessage più la modifica dell'importo delle mance se la mancia può essere modificata dall'utente. Per ulteriori dettagli, consulta Variazioni di prezzo durante l'invio dell'ordine. - Elabora l'ordine e il pagamento se restituisci una risposta con stato dell'ordine
CREATEDoCONFIRMED. - Assicurati che venga restituito un formato di risposta valido utilizzando i tipi generati creati dallo schema come descritto nella sezione Generare librerie client.
- Utilizzare lo GoogleProvidedPaymentInstrument.
instrumentTokenper elaborare il pagamento. Restituisci RejectionInfo di tipoPAYMENT_DECLINEDse non è possibile elaborare il pagamento. Per ulteriori informazioni, consulta Elaborare i pagamenti. - Avvisa l'utente immediatamente dopo l'elaborazione dell'ordine via email e/o SMS.
Restituire la risposta
- Imposta OrderState.
statesuCREATEDoCONFIRMEDse non sono presenti errori. - Imposta OrderState.
statesuREJECTEDse si verificano errori e includi l'oggetto RejectionInfo con il corrispondente RejectionInfoType. - Imposta OrderUpdate.
orderManagementActions.