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
,CONFIRMED
ouREJECTED
.
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].intent
de 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].transactionDecisionValue
de uma solicitação de envio de pedido contém um objetoOrder
que representa o pedido do cliente a ser feito, além dos detalhes da forma de pagamento. - Sinalização de sandbox:o campo
isInSandbox
de 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.orderUpdate
da 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 objetoOrderState
que 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. OtotalPrice
precisa ser o mesmo que ototalPrice
retornado 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
CREATED
ouCONFIRMED
. - 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.
instrumentToken
para processar o pagamento. Retorne RejectionInfo com o tipoPAYMENT_DECLINED
se 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.
state
comoCREATED
ouCONFIRMED
, se não houver erros. - Defina OrderState.
state
comoREJECTED
se houver erros e inclua o objeto RejectionInfo com o RejectionInfoType correspondente. - Defina o OrderUpdate.
orderManagementActions
.