Questa pagina è stata tradotta dall'API Cloud Translation.

Configurare Invia ordine

Dopo la chiamata di pagamento, l'utente esamina il carrello aggiornato con tasse, spese di consegna, sconti e altri addebiti che restituisci. L'utente conferma e invia l'ordine e Google invia al tuo endpoint di evasione degli ordini una richiesta JSON contenente le informazioni relative all'ordine. Il tuo servizio web deve ricevere questo ordine, elaborarlo e rispondere a Google con lo stato dell'ordine.

Questa sezione descrive il formato del messaggio di richiesta di 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 sezione Panoramica dell'evasione.

Implementazione dell'evasione degli ordini

Il servizio web Ordine end-to-end che crei per lavorare con Ordine end-to-end deve includere un endpoint URL per ricevere i messaggi di ordine da Google. Per l'elaborazione degli ordini, il tuo servizio web riceve un SubmitOrderRequestMessage in formato JSON come richiesta POST da Google. Questa richiesta contiene un ordine del cliente, incluse tasse, commissioni e dati di pagamento. Al ricevimento di una richiesta di invio dell'ordine, il tuo servizio web deve:

Verificare l'idoneità delle transazioni, ad esempio la verifica della carta o il rilevamento delle attività fraudolente.
Crea un ordine nel tuo sistema.
Autorizza il metodo di pagamento e chiama l'API di addebito del tuo elaboratore dei pagamenti, se applicabile.
Rispondi con lo stato appropriato dell'ordine: CREATED, CONFIRMED o REJECTED.

Dopo l'elaborazione dell'ordine, il codice di evasione deve fornire una risposta a Google sotto forma di messaggio JSON SubmitOrderResponseMessage.

Per ulteriori informazioni sui requisiti di implementazione del servizio web di evasione degli ordini end-to-end, consulta la Panoramica dell'evasione degli ordini.

Messaggio di richiesta ordine

Quando un cliente sceglie di effettuare un ordine durante il flusso end-to-end di acquisto, Google invia una richiesta al tuo servizio web con un messaggio JSON chiamato SubmitOrderRequestMessage che contiene i seguenti dati:

Intent: il campo inputs[0].intent di ogni corpo della richiesta di invio dell'ordine contiene il valore della stringa actions.intent.TRANSACTION_DECISION.
Ordine: il campo inputs[0].arguments[0].transactionDecisionValue di una richiesta di invio dell'ordine contiene un oggetto Order che rappresenta l'ordine del cliente da effettuare, insieme ai dettagli di pagamento.
Flag sandbox: il campo isInSandbox di una richiesta di invio dell'ordine indica se la transazione utilizza i 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 Ordering la elabora e restituisce 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, ad esempio contattare l'assistenza e visualizzare i dettagli dell'ordine, che definisci nel campo finalResponse.richResponse.items[0].structuredResponse.orderUpdate della risposta.

Aggiornamento ordine

Quando il servizio web invia un SubmitOrderResponseMessage, contiene un OrderUpdate che include i seguenti campi:

actionOrderId: l'ID univoco dell'ordine, utilizzato per identificarlo in modo univoco nel tuo sistema e farvi riferimento quando invii aggiornamenti dell'ordine successivi.
orderState: un oggetto OrderState che rappresenta lo stato dell'ordine.
orderManagementActions: azioni post-ordine disponibili per l'utente, come contattare l'assistenza clienti e visualizzare i dettagli dell'ordine.
totalPrice: il prezzo totale dell'ordine. Questa opzione è facoltativa. Invia solo se il prezzo totale dell'ordine è cambiato dopo l'invio dell'ordine.

Un ordine può trovarsi in uno dei seguenti stati:

CREATED: l'endpoint di evasione ha elaborato l'ordine correttamente, ma il fornitore non lo ha ancora confermato.
CONFIRMED: l'endpoint di evasione degli ordini ha elaborato l'ordine correttamente e il fornitore lo ha confermato.
REJECTED: si è verificato un problema e l'endpoint di evasione degli ordini non è stato in grado di creare o confermare l'ordine, il che può includere problemi di pagamento.

Se imposti un ordine in uno stato REJECTED, specifica il motivo nel rejectionInfo campo 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"
                    }
                  }
                }
              ]
            }
          }
        }
      ]
    }
  }
}

Implementazione dell'invio dell'ordine

Quando implementi l'API SubmitOrder, devi seguire i passaggi che seguono.

Convalida

Esegui le verifiche 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 dell'ordine non è più valida.
`PROMO_USER_INELIGIBLE`	Utilizza l'email nell'oggetto Contatto della richiesta per convalidare l'idoneità dell'utente alla promozione. Consulta l'esempio in Implementare l'invio dell'ordine con le promozioni.
`INELIGIBLE`	Le informazioni dell'utente, come il numero di telefono o l'email, non sono valide. Il tuo motore del rischio rileva attività fraudolente.
`PAYMENT_DECLINED`	Impossibile elaborare il pagamento. Ad esempio, potrebbe essere dovuto a fondi insufficienti.
`UNKNOWN`	Per qualsiasi altro errore di convalida.

Imposta OrderState.state su REJECTED se si verificano errori di convalida. Se vuoi, puoi fornire un motivo di rifiuto specifico utilizzando FoodOrderUpdateExtension.foodOrderErrors Consulta gli esempi in Convalida dell'invio dell'ordine.

Elaborare il pagamento

Calcola totalPrice aggiungendo il prezzo del carrello, le commissioni, lo sconto, le imposte e la mancia. totalPrice deve essere uguale a totalPrice restituito in CheckoutResponseMessage più la variazione dell'importo della mancia se la mancia può essere modificata dall'utente. Per ulteriori dettagli, consulta la sezione Modifiche ai prezzi durante l'invio dell'ordine.
Elabora l'ordine e il pagamento se restituisci una risposta con uno stato dell'ordine CREATED o CONFIRMED.
Assicurati che venga restituito un formato di risposta valido utilizzando i tipi generati creati dallo schema come descritto in Genera librerie client.
Utilizza GoogleProvidedPaymentInstrument.instrumentToken per elaborare il pagamento. Restituire RejectionInfo con il tipo PAYMENT_DECLINED se non è possibile elaborare il pagamento. Per ulteriori dettagli, consulta la sezione Elaborare i pagamenti.
Avvisa l'utente immediatamente dopo l'elaborazione dell'ordine via email e/o SMS.

Restituire la risposta

Imposta OrderState.state su CREATED o CONFIRMED se non ci sono errori.
Imposta OrderState.state su REJECTED se si verificano errori e includi l'oggetto RejectionInfo con il RejectionInfoType corrispondente.
Imposta OrderUpdate.orderManagementActions.

Indietro

Configurare il pagamento

Avanti

Testa l'API Fulfillment