Após a chamada de finalização de compra, o usuário analisa o carrinho atualizado com tributos, taxas de entrega, descontos e outras cobranças que você devolver. O usuário confirma e envia o pedido, e o Google envia ao endpoint de fulfillment uma solicitação JSON que contém as informações do pedido. Seu serviço da Web precisa receber esse pedido, processá-lo e responder ao Google com o estado dele.
Nesta seção, descrevemos o formato da mensagem de solicitação de pedido enviada pelo Google,
chamado SubmitOrderRequestMessage, e o formato da mensagem de resposta
que você precisa fornecer, denominado
SubmitOrderResponseMessage.
Para mais informações sobre o ciclo de vida do atendimento de pedidos, consulte a
Visão geral do atendimento do pedido.
Implementação do atendimento do pedido
O serviço da Web de ponta a ponta criado para trabalhar com esse tipo de serviço precisa
incluir um endpoint de URL para receber mensagens de pedidos do Google. Para processamento
de pedidos, seu serviço da Web recebe um SubmitOrderRequestMessage no formato JSON
como uma solicitação POST do Google. Essa solicitação contém um pedido do cliente, incluindo tributos, taxas e informações de pagamento. Ao receber uma solicitação de envio de pedido, seu serviço da Web precisa fazer o seguinte:
- Verificar a qualificação da transação, como verificação de cartão ou detecção de fraudes.
- Crie um pedido no seu sistema.
- Autorize a forma de pagamento e chame a API de cobrança do processador de pagamentos quando aplicável.
- Responda com o estado adequado da ordem:
CREATED,CONFIRMEDouREJECTED.
Depois de processar o pedido, seu código de fulfillment precisa fornecer uma resposta
na forma de uma mensagem JSON SubmitOrderResponseMessage para o Google.
Para mais informações sobre os requisitos de implementação do serviço da Web de fulfillment completo de pedidos, consulte Visão geral do atendimento do pedido.
Mensagem de solicitação do pedido
Quando um cliente decide fazer um pedido durante o fluxo de ponta a ponta do pedido,
o Google envia uma solicitação ao seu serviço da Web com uma mensagem JSON chamada
SubmitOrderRequestMessage que contém os seguintes dados:
- Intent:o campo
inputs[0].intentde cada corpo da solicitação de pedido de envio contém o valor de stringactions.intent.TRANSACTION_DECISION. - Pedido: o campo
inputs[0].arguments[0].transactionDecisionValuede uma solicitação de envio de pedido contém um objetoOrderque representa o pedido do cliente a ser feito, além dos detalhes da forma de pagamento. - Sinalização de sandbox:o campo
isInSandboxde uma solicitação de envio de pedido indica se a transação usa pagamentos por sandbox.
Exemplo de solicitação de pedido
Veja abaixo um exemplo de 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
}
Mensagem de resposta do pedido
Depois de receber uma solicitação, o serviço da Web de Pedidos de ponta a ponta processa a
solicitação e envia de volta um SubmitOrderResponseMessage que inclui os
seguintes dados:
OrderUpdate: um objeto que contém o estado do pedido e todas as ações pós-ordem disponíveis para o usuário, como entrar em contato com o suporte e ver detalhes do pedido, que você define no campofinalResponse.richResponse.items[0].structuredResponse.orderUpdateda resposta.
Campo de atualização do pedido
Quando o serviço da Web envia uma SubmitOrderResponseMessage, ele contém um
campo OrderUpdate que inclui os seguintes campos:
actionOrderId: o ID exclusivo do pedido, que é usado para identificar de forma exclusiva o pedido no sistema e se referir a ele ao enviar atualizações de pedidos subsequentes.orderState: um objetoOrderStateque representa o estado do pedido.orderManagementActions: ações pós-pedido disponíveis para o usuário, como entrar em contato com o suporte ao cliente e conferir os detalhes do pedido.totalPrice: o preço total do pedido. Isso é opcional. Envie somente se o preço total do pedido tiver mudado após o envio.
Um pedido pode estar em um dos seguintes estados:
CREATED: o endpoint de fulfillment processou o pedido, mas o fornecedor ainda não confirmou o pedido.CONFIRMED: o endpoint de fulfillment processou o pedido, e o fornecedor confirmou o pedido.REJECTED: ocorreu um problema e o endpoint de fulfillment não conseguiu criar ou confirmar o pedido, o que pode incluir problemas com o pagamento.
Se você definir um pedido para um estado REJECTED, especifique o motivo no campo rejectionInfo de OrderUpdate. Use
valores de FoodOrderUpdateExtension.FoodOrderErrors com
rejectionInfo do tipo UNKNOWN e forneça uma descrição.
Exemplo de resposta do pedido
Veja abaixo um exemplo de 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"
}
}
}
}
]
}
}
}
Falha na solicitação
Se uma solicitação de envio não for bem-sucedida, SubmitOrderResponseMessage precisará definir
o OrderState.state como REJECTED. A resposta também precisa
incluir RejectionInfo, que contém um objeto RejectionType
para descrever o tipo de erro.
Exemplo de resposta malsucedida
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"
}
}
}
]
}
}
}
]
}
}
}
Enviar implementação do pedido
Siga estas etapas ao implementar a API de pedido de envio.
Validação
- Realize as validações de serviço, carrinho e promoção conforme feito em Configurar Finalização de compra.
- Retorne RejectionInfo com um dos seguintes tipos, se necessário:
| RejectionInfoType | Caso de uso |
|---|---|
UNAVAILABLE_SLOT |
O tempo de fulfillment não é mais válido. |
PROMO_USER_INELIGIBLE |
Use o e-mail no objeto Contato na solicitação para validar a qualificação da promoção para o usuário. Confira o exemplo em implementar pedido de envio com promoções. |
INELIGIBLE |
|
PAYMENT_DECLINED |
Não foi possível processar o pagamento. Por exemplo, isso pode ser devido a fundos insuficientes. |
UNKNOWN |
Para qualquer outro erro de validação. |
Defina OrderState.state como REJECTED se houver erros de validação encontrados. Opcionalmente, informe um motivo específico de rejeição
usando a FoodOrderUpdateExtension.foodOrderErrors. Veja exemplos em
Validação de envio do pedido.
Processar o pagamento
- Para calcular o
totalPrice, adicione o preço, as taxas, o desconto, os tributos e a gorjeta do carrinho. OtotalPriceprecisa ser o mesmo que ototalPriceretornado na CheckoutResponseMessage mais a mudança no valor, se ele puder ser modificado pelo usuário. Consulte Mudanças no preço durante o envio do pedido para mais detalhes. - Processe o pedido e o pagamento se você retornar uma resposta com um estado de pedido
CREATEDouCONFIRMED. - Verifique se um formato de resposta válido é retornado usando tipos gerados criados a partir do esquema, conforme descrito em Gerar bibliotecas de cliente.
- Use o
GoogleProvidedPaymentInstrument.
instrumentTokenpara processar o pagamento. Retorne RejectionInfo com o tipoPAYMENT_DECLINEDse o pagamento não puder ser processado. Consulte Processar pagamentos para mais detalhes. - Notifique o usuário imediatamente após o processamento do pedido por e-mail ou SMS.
Retornar a resposta
- Defina OrderState.
statecomoCREATEDouCONFIRMED, se não houver erros. - Defina OrderState.
statecomoREJECTEDse houver erros e inclua o objeto RejectionInfo com o RejectionInfoType correspondente. - Defina o OrderUpdate.
orderManagementActions.