Las promociones son una forma para que tú y Google incentiven a los clientes a probar tu servicio de pedidos de comida con precios con descuento. Google admite la integración de tus Acciones de extremo a extremo de pedidos con tu sistema de administración de promociones.
Se admiten los siguientes tipos de descuentos:
- Códigos promocionales patrocinados por Google: Son códigos promocionales que Google completa automáticamente o que ingresan los usuarios.
- Códigos de promoción patrocinados por terceros: Son códigos de promoción que los usuarios deben ingresar y que proporciona tu servicio de pedidos de comida.
- Descuentos automáticos patrocinados por terceros: Son descuentos que tu servicio de pedidos de comida aplica automáticamente sin un código de promoción.
Independientemente del tipo de descuento, Google realiza una llamada de confirmación de la compra a la entrega de pedidos de comida para verificar y aplicar el descuento.
Como desarrollador de un servicio de pedidos de comida, debes realizar algunos cambios en tu implementación para calcular los descuentos de los códigos de promoción válidos o enviar errores para los códigos de promoción no válidos, administrar las limitaciones de canje de códigos de promoción y hacer un seguimiento de los datos de contabilidad para el reembolso.
Cómo procesar promociones
Para implementar una entrega que admita promociones, haz lo siguiente:
- Configura la integración de promociones. (omite este paso si no usas códigos de promoción patrocinados por Google).
- Implementa la confirmación de la compra con promociones.
- Implementa la función para enviar pedidos con promociones.
Configura la integración de promociones
En esta sección, se describe cómo configurar la integración de promociones si planeas usar códigos de promoción patrocinados por Google. Si solo deseas admitir códigos de promoción o descuentos que patrocina un tercero, puedes especificar tu propia configuración y omitir esta sección.
Google especifica el tipo de promoción que patrocinará y se comunicará contigo para configurar la integración. Proporcionamos los siguientes detalles:
- Es el importe del descuento.
- Es el valor mínimo del carrito.
- Las fechas de inicio y finalización para usar los códigos promocionales
- Es el importe máximo en dólares presupuestado para la campaña de promoción.
- Indica la cantidad de veces que se pueden usar los códigos promocionales.
Ejemplos de códigos promocionales:
FopaNewUser: 10% (porcentaje fijo) con un máximo de USD 50 de descuento.FopaMoreThan50: USD 10 (descuento de importe fijo).
Si Google decide detener la aplicación del código, nos comunicaremos contigo.
Configura los pagos
Comunícate con tu consultor de EAP de Google para configurar el proceso de desembolso. Google solo reembolsa las transacciones que involucran códigos promocionales patrocinados por Google si el estado final del pedido es uno de los siguientes:
CONFIRMEDIN_TRANSITREADY_FOR_PICKUPIN_PREPARATIONFULFILLED
Implementa la confirmación de la compra con promociones
En esta sección, se describe cómo implementar el procesamiento de confirmación de la compra cuando admites códigos promocionales (patrocinados por Google o por terceros). En el caso de los descuentos automáticos patrocinados por terceros, solo debes mostrar la línea de descuento en CheckoutResponseMessage (no es necesario verificar el código de promoción).
Durante la entrega de pedidos de comida, Google envía un solo código de promoción en el elemento CheckoutRequestMessage a tu entrega. Los usuarios pueden cambiar su carrito o código promocional en solicitudes de confirmación de la compra repetidas.
Para verificar si es la primera vez que el usuario aplica un código promocional, haz lo siguiente:
- Códigos promocionales patrocinados por Google: Google verifica si un usuario recurrente intenta usar el mismo código promocional nuevamente. No necesitas hacer nada.
- Códigos de promoción patrocinados por terceros o descuentos automáticos: Si no implementaste la vinculación de cuentas ni la habilitación del usuario, no podrás verificar los detalles del usuario durante el procesamiento de la solicitud de confirmación de la compra. En su lugar, verifica esto durante el procesamiento de
SubmitOrderRequestMessagecon los detalles deContact(como la dirección de correo electrónico del usuario) del objetoFoodCartExtension.
Identifica errores o calcula descuentos con tu entrega según la solicitud de confirmación de la compra más reciente. Cuando lo hagas, asegúrate de que el sistema no mantenga información de estado inactiva.
Cómo verificar la validez del código promocional
La entrega debe verificar la validez o elegibilidad de un código de promoción determinado en función de las condiciones estipuladas, como la fecha de vencimiento, el uso máximo y el descuento máximo. Luego, responde de manera adecuada en CheckoutResponseMessage con el descuento calculado o con foodOrderErrors si no se puede aplicar el código de promoción. Si detectas errores con el código de promoción, sigue el proceso que se describe en Cómo controlar los errores con las promociones.
En el siguiente fragmento, se muestra un ejemplo de foodOrderErrors para un código de promoción.
Asegúrate de que correctedProposedOrder no incluya el nodo de promociones.
"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 ...}
Descuentos por procesamiento
Si el código de promoción es válido, la entrega debe calcular el valor en dólares del descuento y enviar de vuelta un CheckoutResponseMessage con el valor del descuento calculado en el array otherItems. El precio total del pedido no debe ser negativo. Si el importe del descuento supera el importe del carrito, envía el importe máximo en dólares para que el precio total del pedido sea de USD 0.
En el siguiente fragmento, se muestra un ejemplo de la sección CheckoutResponseMessage para el descuento 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",
}
]
}
Libera promociones sin usar
No todas las solicitudes de confirmación de la compra generan una solicitud de envío del pedido. Si tu equipo de entrega retiene una promoción durante la llamada de confirmación de la compra, asegúrate de tener un mecanismo para liberarla si la promoción no se reclama mediante el envío del pedido después de un período determinado. Esto garantiza que tu servicio de pedidos de comida mantenga la cuota de campaña correcta.
Cómo controlar errores con promociones
Si la entrega determina que el código de promoción de un CheckoutRequestMessage no es válido (por ejemplo, está vencido, no es válido o no se reconoce), envía un CheckoutResponseMessage con un foodOrderError que contenga el código de error y el texto del motivo correspondientes, junto con los objetos correctedProposedOrder y paymentOptions.
Si la entrega encuentra varios errores de códigos de promoción de la misma solicitud, envía los errores irrecuperables antes de enviar los recuperables. Prioriza tus verificaciones de la siguiente manera (de prioridad alta a baja):
PROMO_NOT_RECOGNIZEDPROMO_EXPIREDPROMO_USER_INELIGIBLEPROMO_ORDER_INELIGIBLEPROMO_NOT_APPLICABLE
Ejemplos
Este es un ejemplo de una solicitud de confirmación de la compra con un código de promoción:
{ "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 es la respuesta de confirmación de la compra correspondiente de la entrega si el código de promoción es 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": [] } } }
Este es un ejemplo de una respuesta de confirmación de la compra si el código de promoción no es vá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" } } } ] } } }
Implementa el envío de pedidos con promociones
En la entrega del pedido que enviaste, verifica si es la primera vez que el usuario aplica un código promocional. Durante el procesamiento de SubmitOrderRequestMessage, puedes verificar esto con los detalles de Contact (como la dirección de correo electrónico del usuario) del objeto FoodCartExtension.
También debes volver a verificar la aplicabilidad del código promocional:
- Si el código es aplicable: Confirma el pedido y marca el cupón como canjeado.
- Si el código ya no es aplicable: Rechaza el pedido con el error
PROMO_NOT_APPLICABLE. Puedes proporcionar un motivo de rechazo específico con el mismo mecanismo que paraFoodOrderUpdateExtension.
Ejemplos
Este es un ejemplo de una solicitud de envío de pedido con promociones:
{ "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 }
Este es un ejemplo de la respuesta correspondiente para enviar un pedido de una entrega si el código de promoción es 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": [] } } }
Este es un ejemplo de la respuesta de envío del pedido si el código de promoción no es vá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." } ] } }