As promoções fornecem uma maneira para você e o Google incentivarem os clientes a experimentar seu serviço de pedidos de comida com descontos. O Google oferece suporte à integração das ações completas dos pedidos com o sistema de gerenciamento de promoções.
Os seguintes tipos de desconto são compatíveis:
- Códigos promocionais patrocinados pelo Google:são códigos promocionais preenchidos automaticamente pelo Google ou inseridos pelos usuários.
- Códigos promocionais patrocinados por terceiros:são códigos promocionais para os usuários inserirem fornecidos pelo seu serviço de pedidos de comida.
- Descontos automáticos patrocinados por terceiros:descontos que seu serviço de pedidos de comida aplica automaticamente sem um código promocional.
Independentemente do tipo de desconto, o Google faz uma chamada de pagamento para o atendimento do pedido de comida para verificar e aplicar o desconto.
Como desenvolvedor de um serviço de pedidos de comida, você precisa fazer algumas mudanças na sua implementação para calcular descontos para códigos promocionais válidos ou enviar erros para códigos promocionais inválidos, gerenciar limitações de resgate de códigos promocionais e rastrear dados contábeis para reembolso.
Como processar promoções
Para implementar um fulfillment compatível com promoções, faça o seguinte:
- Configurar a integração de promoções. Pule esta etapa se você não estiver usando os códigos promocionais patrocinados pelo Google.
- Implementar a finalização da compra com promoções.
- Implementar o envio de pedido com promoções.
Configurar a integração de promoções
Nesta seção, descrevemos como configurar a integração de promoções se você pretende usar códigos promocionais patrocinados pelo Google. Se você quiser oferecer compatibilidade apenas com códigos promocionais ou descontos que um terceiro patrocina, será possível especificar sua própria configuração e pular esta seção.
O Google especifica o tipo de promoção a ser patrocinada e entra em contato com você para configurar a integração. Fornecemos os seguintes detalhes:
- O valor do desconto.
- O valor mínimo do carrinho.
- São as datas de início e de término para usar os códigos promocionais.
- O valor máximo em dólares orçado para a campanha de promoção.
- Número de vezes que os códigos promocionais podem ser usados.
Exemplos de códigos promocionais:
FopaNewUser: 10% (porcentagem fixa) com desconto máximo de R $50.FopaMoreThan50: R$ 10 (valor fixo de desconto).
Se o Google decidir interromper a aplicação do código, você será contatado.
Configurar pagamentos
Entre em contato com seu consultor do Google EAP para configurar o processo de reembolso. O Google só reembolsa transações envolvendo códigos promocionais patrocinados se o status do pedido final for um dos seguintes:
CONFIRMEDIN_TRANSITREADY_FOR_PICKUPIN_PREPARATIONFULFILLED
Implementar a finalização da compra com promoções
Esta seção descreve a implementação do processamento de finalização de compra quando você aceita códigos promocionais (patrocinados pelo Google ou por terceiros). Para descontos automáticos patrocinados por terceiros, você só precisa retornar o item de linha de desconto no CheckoutResponseMessage. Não é necessário verificar o código promocional.
Durante o atendimento de pedidos de comida, o Google envia um único código promocional no
CheckoutRequestMessage para o atendimento do pedido. Os usuários podem alterar o carrinho ou
o código promocional em solicitações repetidas de finalização da compra.
Para verificar se essa é a primeira vez que o usuário aplicou um código promocional, faça o seguinte:
- Códigos promocionais patrocinados pelo Google: o Google verifica se um usuário recorrente está tentando usar o mesmo código promocional novamente. Você não precisa fazer nada.
- Códigos promocionais ou descontos automáticos patrocinados de terceiros: se você
não tiver implementado a vinculação de contas e a ativação do usuário, não será possível verificar
os detalhes do usuário durante o processamento da solicitação de finalização da compra. Em vez disso, verifique isso
durante o processamento de
SubmitOrderRequestMessageusando os detalhes deContact(como o endereço de e-mail do usuário) do objetoFoodCartExtension.
Identifique erros ou calcule descontos com seu fulfillment com base na solicitação de finalização de compra mais recente. Ao fazer isso, verifique se o sistema não mantém informações de estado desatualizadas.
Verificar a validade do código promocional
O fulfillment deve verificar a validade ou a qualificação de um determinado código promocional
em relação aos termos estipulados, como data de validade, uso máximo e
desconto máximo. Em seguida, responda corretamente no CheckoutResponseMessage
com o desconto calculado ou com foodOrderErrors se o código promocional
não puder ser aplicado. Se você detectar erros no código promocional, siga o processo descrito em Processar erros com promoções.
O snippet a seguir mostra um exemplo de foodOrderErrors para um código promocional.
Verifique se o correctedProposedOrder não inclui o nó de
promoções.
"foodOrderErrors": [
{
"error": "PROMO_NOT_APPLICABLE",
// Copy promotions.coupon string from CheckoutRequest as the ID
"id": "GoogleNewUser",
"description": "Promotion could not be applied"
}
],
"correctedProposedOrder": {// required ...},
"paymentOptions": {// required ...}
Descontos em computação
Se o código promocional for válido, o fulfillment deverá calcular o valor em dólar do desconto e enviar de volta um CheckoutResponseMessage com o valor de desconto calculado na matriz otherItems. O preço total do pedido não pode ser
negativo. Se o valor do desconto exceder o valor do carrinho, retorne o valor máximo em dólares para renderizar o preço total do pedido como US $0.
O snippet a seguir mostra um exemplo de seção CheckoutResponseMessage para o desconto promocional:
"proposedOrder": {
"otherItems": [
. . .
{
"name": "Discount",
// copy promotions.coupon field from CheckoutRequest as the id
"id": "GoogleNewUser",
"price": {
"type": "ESTIMATE",
"amount": {
"currencyCode": "USD",
"units": "-3",
"nanos": -500000000
}
},
"type": "DISCOUNT",
}
]
}
Liberar promoções não utilizadas
Nem todo pedido de finalização da compra leva a um pedido de envio de pedido. Se o fulfillment suspender uma promoção no momento da chamada de finalização da compra, use um mecanismo para liberar a retenção caso ela não seja reivindicada por meio de um pedido enviado após um determinado período. Isso garante que seu serviço de pedido de comida mantenha a cota correta da campanha.
Solucionar erros com promoções
Se o fulfillment determinar que o código promocional de um
CheckoutRequestMessage não é válido (por exemplo, está expirado, inválido
ou não reconhecido), envie um CheckoutResponseMessage com uma foodOrderError
que contenha o código de erro aplicável e o texto do motivo, junto com
objetos correctedProposedOrder e paymentOptions.
Se o fulfillment encontrar vários erros de código promocional da mesma solicitação, envie os erros irrecuperáveis antes de enviar os erros recuperáveis. Priorize suas verificações da seguinte maneira (da prioridade mais alta para a mais baixa):
PROMO_NOT_RECOGNIZEDPROMO_EXPIREDPROMO_USER_INELIGIBLEPROMO_ORDER_INELIGIBLEPROMO_NOT_APPLICABLE
Exemplos
Veja um exemplo de uma solicitação de finalização de compra com um código promocional:
{
"accessToken": "test_access_token",
"lastSeen": "2018-06-22T19:25:39Z"
},
"conversation": {
"conversationId": "XYZ"
},
"inputs": [
{
"intent": "actions.foodordering.intent.CHECKOUT",
"arguments": [
{
"extension": {
"@type": "type.googleapis.com/google.actions.v2.orders.Cart",
"merchant": {
"id": "https://www.exampleprovider.com/merchant/id1",
"name": "Falafel Bite"
},
"lineItems": [
{
"name": "Falafel Tray",
"type": "REGULAR",
"id": "sample_item_offer_id_1",
"quantity": 1,
"price": {
"type": "ESTIMATE",
"amount": {
"currencyCode": "USD",
"units": "9",
"nanos": 950000000
}
},
"offerId": "https://www.exampleprovider.com/menu/item/offer/id1",
"extension": {
"@type": "type.googleapis.com/google.actions.v2.orders.FoodItemExtension"
}
}
],
"promotions": [
{
"coupon": "FOPAACTIVECODE"
}
],
"extension": {
"@type": "type.googleapis.com/google.actions.v2.orders.FoodCartExtension",
"fulfillmentPreference": {
"fulfillmentInfo": {
"pickup": {
"pickupTimeIso8601": "P0M"
}
}
}
}
}
}
]
}
],
"directActionOnly": true,
"isInSandbox": true
}
Esta é a resposta de finalização de compra correspondente do fulfillment se o código promocional for válido:
{
"expectUserResponse": false,
"finalResponse": {
"richResponse": {
"items": [
{
"structuredResponse": {
"checkoutResponse": {
"proposedOrder": {
"otherItems": [
{
"name": "Delivery Fees",
"price": {
"type": "ESTIMATE",
"amount": {
"currencyCode": "USD",
"units": "3",
"nanos": 500000000
}
},
"type": "DELIVERY"
},
{
"name": "Tax",
"price": {
"type": "ESTIMATE",
"amount": {
"currencyCode": "USD",
"units": "1",
"nanos": 370000000
}
},
"type": "TAX"
},
{
"name": "Promotion",
"price": {
"type": "ESTIMATE",
"amount": {
"currencyCode": "USD",
"units": "-5",
"nanos": 0
}
},
"id": "FOPAACTIVECODE",
"type": "DISCOUNT"
}
],
"cart": {
"merchant": {
"id": "https://www.exampleprovider.com/merchant/id1",
"name": "Falafel Bite"
},
"lineItems": [
{
"name": "Falafel Tray",
"type": "REGULAR",
"id": "2529103",
"quantity": 1,
"price": {
"type": "ESTIMATE",
"amount": {
"currencyCode": "USD",
"units": "9",
"nanos": 950000000
}
},
"offerId": "https://www.exampleprovider.com/menu/item/offer/id1",
"extension": {
"@type": "type.googleapis.com/google.actions.v2.orders.FoodItemExtension"
}
}
],
"promotions": [
{
"coupon": "FOPAACTIVECODE"
}
],
"extension": {
"@type": "type.googleapis.com/google.actions.v2.orders.FoodCartExtension",
"fulfillmentPreference": {
"fulfillmentInfo": {
"pickup": {
"pickupTimeIso8601": "P0M"
}
}
}
}
},
"totalPrice": {
"type": "ESTIMATE",
"amount": {
"currencyCode": "USD",
"units": "9",
"nanos": 820000000
}
},
"extension": {
"@type": "type.googleapis.com/google.actions.v2.orders.FoodOrderExtension",
"availableFulfillmentOptions": [
{
"fulfillmentInfo": {
"pickup": {
"pickupTimeIso8601": "P0M"
}
},
"expiresAt": "2018-06-22T19:30:52.596Z"
}
]
}
},
"orderOptions": {},
"paymentOptions": {
"googleProvidedOptions": {
"tokenizationParameters": {
"tokenizationType": "PAYMENT_GATEWAY",
"parameters": {
"gateway": "stripe",
"stripe:publishableKey": "example_stripe_client_key",
"stripe:version": "2017-04-06"
}
},
"supportedCardNetworks": [
"AMEX",
"DISCOVER",
"MASTERCARD",
"VISA",
"JCB"
],
"prepaidCardDisallowed": true
}
}
}
}
}
],
"suggestions": []
}
}
}
Confira um exemplo de resposta de finalização de compra se o código promocional for inválido:
{
"expectUserResponse": false,
"finalResponse": {
"richResponse": {
"items": [
{
"structuredResponse": {
"error": {
"foodOrderErrors": [
{
"error": "PROMO_NOT_RECOGNIZED",
"id": "SOMEPROMO",
"description": "Coupon not found"
}
],
"correctedProposedOrder": {
"cart": {
"merchant": {
"id": "https://www.exampleprovider.com/merchant/id1",
"name": "Falafel Bite"
},
"lineItems": [
{
"id": "sample_item_offer_id_4",
"name": "Prawns Biryani",
"type": "REGULAR",
"quantity": 1,
"price": {
"type": "ESTIMATE",
"amount": {
"currencyCode": "USD",
"units": "18",
"nanos": 750000000
}
},
"offerId": "https://www.exampleprovider.com/menu/item/offer/id4",
"extension": {
"@type": "type.googleapis.com/google.actions.v2.orders.FoodItemExtension"
}
}
],
"extension": {
"fulfillmentPreference": {
"fulfillmentInfo": {
"pickup": {
"pickupTimeIso8601": "P0M"
}
}
},
"@type": "type.googleapis.com/google.actions.v2.orders.FoodCartExtension"
},
"promotions": []
},
"otherItems": [
{
"name": "Tax",
"type": "TAX",
"price": {
"type": "ESTIMATE",
"amount": {
"currencyCode": "USD",
"units": "1",
"nanos": 650000000
}
}
}
],
"termsOfServiceUrl": "https://exampleprovider.com/terms",
"totalPrice": {
"type": "ESTIMATE",
"amount": {
"currencyCode": "USD",
"units": "20",
"nanos": 400000000
}
},
"extension": {
"availableFulfillmentOptions": [
{
"fulfillmentInfo": {
"pickup": {
"pickupTimeIso8601": "PT0M"
}
}
}
],
"@type": "type.googleapis.com/google.actions.v2.orders.FoodOrderExtension"
}
},
"paymentOptions": {
"googleProvidedOptions": {
"prepaidCardDisallowed": false,
"billingAddressRequired": true,
"tokenizationParameters": {
"tokenizationType": "PAYMENT_GATEWAY",
"parameters": {
"gateway": "braintree",
"braintree:apiVersion": "v1",
"braintree:sdkVersion": "1.4.0",
"braintree:merchantId": "example_braintree_merchant_ID",
"braintree:clientKey": "example_braintree_client_key",
"braintree:authorizationFingerprint": "example_braintree_fingerprint"
}
}
}
},
"@type": "type.googleapis.com/google.actions.v2.orders.FoodErrorExtension"
}
}
}
]
}
}
}
Implementar o envio de pedido com promoções
No atendimento do pedido de envio, verifique se esta é a primeira vez que o
usuário está aplicando um código promocional. Durante o processamento de SubmitOrderRequestMessage, é possível verificar isso usando os detalhes de Contact (como o
endereço de e-mail do usuário) do objeto FoodCartExtension.
Verifique novamente a aplicabilidade do código promocional:
- Se o código for aplicável:confirme o pedido e marque o cupom resgatado.
- Se o código não for mais aplicável:rejeite o pedido com o erro
PROMO_NOT_APPLICABLE. Você pode fornecer um motivo de rejeição específico usando o mesmo mecanismo usado paraFoodOrderUpdateExtension.
Exemplos
Veja um exemplo de solicitação de envio de pedido com promoções:
{
"conversation": {
"conversationId": "example_conversation_ID"
},
"inputs": [
{
"intent": "actions.intent.TRANSACTION_DECISION",
"arguments": [
{
"transactionDecisionValue": {
"order": {
"finalOrder": {
"cart": {
"merchant": {
"id": "https://www.exampleprovider.com/merchant/id1",
"name": "Falafel Bite"
},
"lineItems": [
{
"name": "Falafel Tray",
"type": "REGULAR",
"id": "sample_item_offer_id_1",
"quantity": 1,
"price": {
"type": "ESTIMATE",
"amount": {
"currencyCode": "USD",
"units": "9",
"nanos": 950000000
}
},
"offerId": "https://www.exampleprovider.com/menu/item/addon/offer/id1",
"extension": {
"@type": "type.googleapis.com/google.actions.v2.orders.FoodItemExtension"
}
}
],
"promotions": [
{
"coupon": "FOPAACTIVECODE"
}
],
"extension": {
"@type": "type.googleapis.com/google.actions.v2.orders.FoodCartExtension",
"fulfillmentPreference": {
"fulfillmentInfo": {
"pickup": {
"pickupTimeIso8601": "P0M"
}
}
},
"contact": {
"displayName": "Food Ordering",
"email": "example.provider@gmail.com",
"phoneNumber": "+19993334444",
"firstName": "Food",
"lastName": "Ordering"
}
}
},
"otherItems": [
{
"name": "Delivery Fees",
"type": "DELIVERY",
"price": {
"type": "ESTIMATE",
"amount": {
"currencyCode": "USD",
"units": "3",
"nanos": 500000000
}
}
},
{
"name": "Tax",
"type": "TAX",
"price": {
"type": "ESTIMATE",
"amount": {
"currencyCode": "USD",
"units": "1",
"nanos": 370000000
}
}
},
{
"name": "Promotion",
"type": "DISCOUNT",
"price": {
"type": "ESTIMATE",
"amount": {
"currencyCode": "USD",
"units": "-5"
}
},
"id": "FOPAACTIVECODE"
},
{
"name": "Subtotal",
"type": "SUBTOTAL",
"price": {
"type": "ESTIMATE",
"amount": {
"currencyCode": "USD",
"units": "9",
"nanos": 950000000
}
}
},
{
"name": "Tip",
"type": "GRATUITY",
"price": {
"type": "ESTIMATE",
"amount": {
"currencyCode": "USD"
}
}
}
],
"totalPrice": {
"type": "ESTIMATE",
"amount": {
"currencyCode": "USD",
"units": "9",
"nanos": 820000000
}
},
"extension": {
"@type": "type.googleapis.com/google.actions.v2.orders.FoodOrderExtension"
}
},
"googleOrderId": "example_google_order_ID",
"orderDate": "2018-06-22T19:30:59.502Z",
"paymentInfo": {
"displayName": "example_display_name",
"googleProvidedPaymentInstrument": {
"instrumentToken": "example_instrument_token"
},
"paymentType": "PAYMENT_CARD"
},
"locale": "en"
}
}
}
]
}
],
"directActionOnly": true,
"isInSandbox": true
}
Confira um exemplo da resposta de pedido de envio correspondente de um fulfillment se o código promocional for válido:
{
"expectUserResponse": false,
"finalResponse": {
"richResponse": {
"items": [
{
"structuredResponse": {
"orderUpdate": {
"actionOrderId": "example_action_order_ID",
"orderState": {
"state": "CREATED",
"label": "Order is created with partner."
},
"updateTime": "2018-06-22T19:31:01.556Z",
"orderManagementActions": [
{
"type": "CALL_RESTAURANT",
"button": {
"title": "Call Us",
"openUrlAction": {
"url": "tel:+1-111-111-1111"
}
}
},
{
"type": "EMAIL",
"button": {
"title": "Email Us",
"openUrlAction": {
"url": "mailto:example.provider@gmail.com"
}
}
},
{
"type": "CUSTOMER_SERVICE",
"button": {
"title": "Customer Service",
"openUrlAction": {
"url": "http://www.google.com"
}
}
}
]
}
}
}
],
"suggestions": []
}
}
}
Veja um exemplo de resposta do pedido de envio se o código promocional for inválido:
"orderUpdate": {
"actionOrderId": "sample_action_order_id",
"orderState": {
"state": "REJECTED",
"label": "Order rejected."
},
"updateTime": "2017-05-10T02:30:00.000Z",
"rejectionInfo": {
"type": "PROMO_NOT_APPLICABLE",
"reason": "Sorry, there's something wrong. Try another code?"
},
"orderManagementActions": [
{
"type": "CUSTOMER_SERVICE",
"button": {
"title": "Contact customer service",
"openUrlAction": {
"url": "mailto:support@example.com"
}
}
},
{
"type": "EMAIL",
"button": {
"title": "Email restaurant",
"openUrlAction": {
"url": "mailto:example.provider@example.com"
}
}
},
{
"type": "CALL_RESTAURANT",
"button": {
"title": "Call restaurant",
"openUrlAction": {
"url": "tel:+19993334444"
}
}
}
],
"infoExtension": {
"@type": "type.googleapis.com/google.actions.v2.orders.FoodOrderUpdateExtension",
"foodOrderErrors": [
{
"error": "PROMO_USER_INELIGIBLE",
"description": "Sorry, you can only use this promotion once."
}
]
}
}