אתם יכולים להוסיף תמיכה בתהליך מילוי ההזמנה, כדי לאפשר למשתמשים לתזמן מראש הזמנות אוכל לאיסוף עצמי ולמשלוחים. לפני שמטמיעים את התמיכה הזו במילוי הבקשה, כדאי ליצור פיד מלאי שירות שבו מציינים את השעות שבהן המשתמשים יכולים לבצע הזמנות מראש, כפי שמתואר בסכימה של פיד המלאי (AdvanceServiceDeliveryHoursSpecification).
משבצות להזמנה מראש
Google מציעה משבצות להזמנה מראש במרווחים של 15 דקות, עד 7 ימים מראש, בהתאם לזמני האספקה של מסעדה או שירות (כפי שמוגדר ב-AdvanceServiceDeliveryHoursSpecification).
כדי לאחזר מראש את ההזמנה המוצעת, צריך להשתמש בערכים הבאים מהשדה fulfillmentPreference באובייקט FoodCartExtension בקופה:
PickupInfo.pickupTimeIso8601DeliveryInfo.deliveryTimeIso8601
הטמעת הזמנות מראש בקופה
בטבלה הבאה מפורטות הדרכים האפשריות להטמעת התגובה של מילוי ההזמנה בזמן התשלום בקופה, כשמשתמשים מנסים לבצע הזמנות.
| תרחיש | התנהגות האספקה |
|---|---|
| אפשר למלא הזמנה מראש במשבצת הזו. | צריך לאשר את עגלת הקניות P0M ('בהקדם האפשרי') או
FUTURE_SLOT על ידי יצירת ProposedOrder עם
אותו משבצת. בקטע הקוד הזה תוכלו לראות דוגמה לתגובה של תשלום בקופה שמקבלת משבצת זמן. |
| אי אפשר למלא הזמנה מראש במיקום המבוקש. | מילוי הבקשה צריך:
קטע הקוד הזה מציג דוגמה לתגובה של דף תשלום עם משבצות חלופיות. |
משבצות חלופיות למילוי הזמנות
בשלב התשלום, אם ההזמנה מראש ש-Google מציעה לא מתאימה, יכול להיות שתקבלו הצעה לחלופות באמצעות האובייקט CheckoutResponseMessage.
כדי לציין משבצות חלופיות להזמנה מראש, משיבים לבקשה לתשלום באמצעות FoodErrorExtension ומגדירים את הערכים הבאים:
- בפרמטר
foodOrderErrors, מציינים את סוג השגיאה (כמוUNAVAILABLE_SLOT,NO_CAPACITYאוCLOSED). - בפרמטר
correctedProposedOrder, צריך לספק ערכים חלופיים שלP0MאוFUTURE_SLOTדרךavailableFulfillmentOptions.
יחידות הקיבולת החלופיות צריכות להיות למשך 7 הימים הבאים מרגע מיקום ההזמנה, ולכלול את כל יחידות הקיבולת (Slot) שבהן אפשר למלא את העגלה שהמשתמש ביקש.
לדוגמה, נניח שמנות מיוחדות לארוחת צהריים זמינות רק בימים שני עד שישי, בין 11:00 ל-13:00. המשתמש מנסה להוסיף מבצעים לארוחת צהריים לעגלת הקניות, אבל משבצת הזמן שנבחרה לא זמינה. במקרה כזה, מילוי ההזמנה אמור להשאיר את המבצעים המיוחדים בעגלת הקניות, ולהחזיר רק את המשבצות בשעות 11:00 עד 13:00 ב-7 הימים הבאים
עליך להשמיט את האובייקט correctedProposedOrder.Cart.fulfillmentPreference בתשובה שלך.
אם אין מקומות פנויים או אם המסעדה או השירות לא תומכים בהזמנות מראש, אין צורך לספק correctedProposedOrder.
ריכזנו כאן דוגמאות להודעות JSON שמופיעות בין תהליך התשלום להזמנה לבין Google בתהליך התשלום ובתהליך התגובה להזמנה מראש, כשהמסעדה או השירות זמינים לביצוע הזמנות מראש.
דוגמה: CheckoutRequest עם משבצת משלוח
בקטע הקוד הבא מוצגת דוגמה לבקשת תשלום עם משבצת משלוח בהזמנה מראש.
{
"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": "Cucina Venti"
},
"lineItems": [
{
"name": "Sizzling Prawns Dinner",
"type": "REGULAR",
"id": "sample_item_offer_id_1",
"offerId": "https://www.exampleprovider.com/menu/item/offer/id1",
"quantity": 1,
"price": {
"type": "ESTIMATE",
"amount": {
"currencyCode": "USD",
"units": "16",
"nanos": 750000000
}
},
}
],
"extension": {
"@type": "type.googleapis.com/google.actions.v2.orders.FoodCartExtension",
"fulfillmentPreference": {
"fulfillmentInfo": {
"delivery": {
// Deliver at 6:30PM.
"deliveryTimeIso8601": "2017-12-14T18:30:00-07:00"
}
}
},
"location": {
...
}
}
}
}
]
}
]
}
דוגמה: תגובה לקופה מקבלת את המיקום
בקטע הקוד הבא מוצגת דוגמה לתשובה לגבי תשלום בקופה, שבה מילוי ההזמנה מאשר את המועדים להזמנה מראש.
{
"expectUserResponse": false,
"finalResponse": {
"richResponse": {
"items": [
{
"structuredResponse": {
"checkoutResponse": {
"proposedOrder": {
"id": "sample_proposed_order_id_1",
"cart": {
"merchant": {
"id": "https://www.exampleprovider.com/merchant/id1",
"name": "Falafel Bite"
},
"lineItems": [
{
"name": "Sizzling Prawns Dinner",
"type": "REGULAR",
"id": "sample_item_offer_id_1",
"offerId": "https://www.exampleprovider.com/menu/item/offer/id1",
"quantity": 1,
"price": {
"type": "ESTIMATE",
"amount": {
"currencyCode": "USD",
"units": "16",
"nanos": 750000000
}
},
}
],
"extension": {
"@type": "type.googleapis.com/google.actions.v2.orders.FoodCartExtension",
"fulfillmentPreference": {
"fulfillmentInfo": {
"delivery": {
// Same as the time in the request.
"deliveryTimeIso8601": "2017-12-14T18:30:00-07:00"
}
}
},
"location": {
...
}
}
},
"totalPrice": {
"type": "ESTIMATE",
"amount": {
// Represents $16.75
"currencyCode": "USD",
"units": "16",
"nanos": 750000000
}
},
"extension": {
"@type": "type.googleapis.com/google.actions.v2.orders.FoodOrderExtension",
// Send whole proposed order back.
"availableFulfillmentOptions": [
"fulfillmentInfo": {
"delivery": {
// Same as the time in the request.
"deliveryTimeIso8601": "2017-12-14T18:30:00-07:00"
}
}
]
}
},
"paymentOptions": {
...
}
}
}
}
]
}
}
}
דוגמה: תגובה ב-Checkout עם משבצות חלופיות
בקטע הקוד הבא מוצגת דוגמה לתגובה בקופה, שבה במילוי ההזמנה מוצעים משבצות חלופיות להזמנה מראש. שימו לב: צריך להשמיט את האובייקט correctedProposedOrder.Cart.fulfillmentPreference בתשובה.
{
"expectUserResponse": false,
"finalResponse": {
"richResponse": {
"items": [
{
"structuredResponse": {
"error": {
"@type": "type.googleapis.com/google.actions.v2.orders.FoodErrorExtension",
"foodOrderErrors": [
{
"error": "UNAVAILABLE_SLOT", // Cart level error
"description": "The restaurant is closed."
}
],
"correctedProposedOrder": {
// Send whole original cart back,
// without the fulfillmentPreference.
"cart": {
...
},
"otherItems": {
...
},
"totalPrice": {
...
},
"extension": {
"@type": "type.googleapis.com/google.actions.v2.orders.FoodOrderExtension",
"availableFulfillmentOptions": [
"fulfillmentInfo": {
"delivery": {
"deliveryTimeIso8601": "2017-12-14T19:00:00-07:00"
}
},
"fulfillmentInfo": {
"delivery": {
"deliveryTimeIso8601": "2017-12-14T19:30:00-07:00"
}
},
"fulfillmentInfo": {
"delivery": {
"deliveryTimeIso8601": "2017-12-14T20:00:00-07:00"
}
}
]
}
},
"paymentOptions": {
...
}
}
}
}
]
}
}
}
יישום הזמנות מראש בעת שליחת ההזמנה
בזמן שליחת ההזמנה, אם יש בעיה עם משבצות הזמן להזמנה מראש, צריך לכלול ב-SubmitOrderResponseMessage את הסיבה (למשל, UNAVAILABLE_SLOT או UNKNOWN) באובייקט RejectionInfo.
לאחר שהספק מאשר את ההזמנה, מעדכנים את מצב ההזמנה מ-CREATED ל-CONFIRMED באובייקט OrderState. צריך לכלול את משבצת הזמן שנבחרה בהודעת האישור באימייל שנשלח למשתמש.
אם לאחר מילוי ההזמנה אתם שולחים את ההזמנה למסעדה מאוחר יותר, שלחו ל-Google עדכון באמצעות Asynchronous Order Update Action.
באובייקט OrderUpdate בתגובת ההזמנה או בעדכוני ההזמנות האסינכרוניים הבאים, צריך לכלול estimatedFulfillmentTimeIso8601 עם הערך הבא:
- כשסטטוס ההזמנה הוא
CREATEDאוCONFIRMED, צריך להגדיר את הערך של זמן המשלוח או האיסוף לפי מועד ההזמנה מראש של המשתמש. - כשיש זמן אספקה משוער מדויק יותר מהמסעדה או מהשירות, אפשר להגדיר את הערך כזמן האספקה המשוער של המשלוח או האיסוף.
דוגמה: SubmitOrderRequest עם משבצת משלוח
קטע הקוד הבא מציג דוגמה לבקשה לשליחת הזמנה שמציינת את משבצת ההזמנה המתקדמת שהמשתמש בחר.
{
"inputs": [
{
"intent": "actions.intent.TRANSACTION_DECISION",
"arguments": [
{
"transactionDecisionValue": {
"order": {
"finalOrder": {
"cart": {
"notes": "Guest prefers their food to be hot when it is delivered.",
"merchant": {
"id": "https://www.exampleprovider.com/merchant/id1",
"name": "Cucina Venti"
},
"lineItems": [
{
"name": "Sizzling Prawns Dinner",
"type": "REGULAR",
"id": "sample_item_offer_id_1",
"offerId": "https://www.exampleprovider.com/menu/item/offer/id1",
"quantity": 1,
"price": {
"type": "ESTIMATE",
"amount": {
"currencyCode": "USD",
"units": "16",
"nanos": 750000000
}
}
}
],
"extension": {
"@type": "type.googleapis.com/google.actions.v2.orders.FoodCartExtension",
"fulfillmentPreference": {
"fulfillmentInfo": {
"delivery": {
"deliveryTimeIso8601": "2017-12-14T18:30:00-07:00"
}
}
}
"contact": {
...
}
}
},
"totalPrice": {
"type": "ESTIMATE",
"amount": {
"currencyCode": "USD",
"units": "16",
"nanos": 750000000
}
},
"id": "sample_final_order_id",
"extension": {
// Send whole proposed order back.
"availableFulfillmentOptions": [
"fulfillmentInfo": {
"delivery": {
"deliveryTimeIso8601": "2017-12-14T18:30:00-07:00"
}
]
}
},
"googleOrderId": "sample_google_order_id",
"orderDate": "2017-07-17T12:00:00Z",
"paymentInfo": {
...
}
}
}
}
]
}
]
}
דוגמה: SubmitOrderResponse מקבל את ההזמנה
בקטע הקוד הבא מוצגת דוגמה לשליחת הזמנה בתגובה לשליחת אישור על כך שהמשתמש אישר את ההזמנה מראש.
{
"expectUserResponse": false,
"finalResponse": {
"richResponse": {
"items": [
{
"structuredResponse": {
"orderUpdate": {
"actionOrderId": "sample_action_order_id",
"orderState": {
"state": "CREATED",
"label": "Order placed"
},
"receipt": {
"userVisibleOrderId": "userVisibleId1234"
},
"updateTime": "2017-07-17T12:00:00Z",
"orderManagementActions": [
...
],
"infoExtension": {
"@type": "type.googleapis.com/google.actions.v2.orders.FoodOrderUpdateExtension",
// Same as the user selected time.
"estimatedFulfillmentTimeIso8601": "2017-12-14T18:30:00-07:00"
}
}
}
}
]
}
}
}
דוגמה: SubmitOrderResponse דוחה את ההזמנה עקב אי זמינות של מיקום
בקטע הבא מוצגת דוגמה לשליחת תשובה להזמנה שבה ההזמנה נדחית על ידי מילוי הבקשה של משתמש בגלל מיקום פנוי.
{
"expectUserResponse": false,
"finalResponse": {
"richResponse": {
"items": [
{
"structuredResponse": {
"orderUpdate": {
"actionOrderId": "sample_action_order_id",
"orderState": {
"state": "REJECTED",
"label": "Unavailable slot"
},
"rejectionInfo": {
// Note that this UNAVAILABLE_SLOT is different from the enum
// with the same name proposed for FoodOrderError.
"state": "UNAVAILABLE_SLOT",
"label": "Unavailable slot"
},
"updateTime": "2017-07-17T12:00:00Z",
"orderManagementActions": [
...
]
}
}
}
]
}
}
}
דוגמאות להזמנות מראש
אפשר להשתמש בסוג AdvanceServiceDeliveryHoursSpecification כדי לציין את שעות המשלוח או האיסוף שבהן המשתמשים יתזמנו את ההזמנה שלהם מראש.
הערה: יש שני חלונות זמן נפרדים שצריך לציין למילוי הזמנות: חלון ההזמנות שבו המשתמשים יכולים לבצע הזמנה וחלון הזמן למילוי הזמנות שבו מצוין מתי ההזמנה מתבצעת. האובייקט OpeningHoursSpecificationServiceDeliveryHoursSpecificationAdvanceServiceDeliveryHoursSpecification
בדוגמה הבאה מגדירים את שעות השירות של קבלת הזמנות מראש, במרווחי זמן של 15 דקות.
{
"hoursAvailable": [
{
"@type": "OpeningHoursSpecification",
"opens": "T00:00:00", // Ordering available 24 hours
"closes": "T23:59:59",
"deliveryHours": [
{
"@type": "ServiceDeliveryHoursSpecification",
"opens": "T09:00:00", // ASAP orders b/w 9am and 8:59:59pm
"closes": "T21:00:00",
"deliveryLeadTime": {
"value": "60",
"unitCode": "MIN"
}
},
{
"@type": "AdvanceServiceDeliveryHoursSpecification",
"opens": "T10:00:00", // Delivery between 10AM and 7:59:59PM
"closes": "T20:00:00",
"serviceTimeInterval": "PT15M", // in slots spaced 15 minutes apart (ISO8601)
"advanceBookingRequirement": {
"minValue": 60, // The slot should be at least 60 mins away
"maxValue": 8640, // but not more than 6 days away
"unitCode": "MIN"
}
}
]
}
]
}
בדוגמה הבאה אפשר לראות איך מגדירים שהשירות פתוח להזמנות באותו יום בחג המולד, ולהזמנות מתקדמות שנקבעו לאותו יום. הדוגמה הזו תומכת בתרחישים הבאים:
- המשתמשים יכולים לבצע הזמנה ב-25 בדצמבר למסירה ביום הקנייה.
- המשתמשים יכולים לבצע הזמנה מראש ב-25 בדצמבר, למשלוח המתוכנן ל-27 בדצמבר.
- המשתמשים לא יכולים לבצע הזמנה מראש ב-22 בדצמבר, שנועדה למשלוח ב-25 בדצמבר.
{
"specialOpeningHoursSpecification": {
"@type": "AdvanceServiceDeliveryHoursSpecification",
"validFrom": "2018-12-25T00:00:00-07:00",
"validThrough": "2018-12-26T00:00:00-07:00",
"opens": "T00:00:00", // No advance ordering
"closes": "T00:00:00"
}
}
בדוגמה הבאה אפשר לראות איך מגדירים שהשירות סגור להזמנות באותו יום או להזמנות מראש שתוזמנו לחג המולד, אבל פתוח להזמנות מתקדמות שמתוזמנות למועד מאוחר יותר. הדוגמה הזו תומכת בתרחישים הבאים:
- המשתמשים לא יכולים לבצע הזמנה ב-25 בדצמבר למסירה ביום הקנייה.
- המשתמשים יכולים לבצע הזמנה מראש ב-25 בדצמבר, למשלוח המתוכנן ל-27 בדצמבר.
- המשתמשים לא יכולים לבצע הזמנה מראש ב-22 בדצמבר, שנועדה למשלוח ב-25 בדצמבר.
{
"specialOpeningHoursSpecification": [
{
"@type": "ServiceDeliveryHoursSpecification",
"validFrom": "2018-12-25T00:00:00-07:00",
"validThrough": "2018-12-26T00:00:00-07:00",
"opens": "T00:00:00", // No ASAP ordering on Christmas
"closes": "T00:00:00"
},
{
"@type": "AdvanceServiceDeliveryHoursSpecification",
"validFrom": "2018-12-25T00:00:00-07:00",
"validThrough": "2018-12-26T00:00:00-07:00",
"opens": "T00:00:00", // Orders cannot be scheduled for Christmas
"closes": "T00:00:00"
}
]
}
אפשר להזמין שירות מסביב לשעון, בין השעות 10:00-14:59:59 בימי חול:
...
{
"@type": "OpeningHoursSpecification",
"opens": "T00:00:00",
"closes": "T23:59:59",
"deliveryHours": {
"@type": "AdvanceServiceDeliveryHoursSpecification",
"opens": "T10:00:00", // Delivery starts at 10:00AM
"closes": "T15:00:00", // Delivery ends at 3:00PM. Delivery from 10AM-2:59:59PM.
"dayOfWeek": [
"Monday",
"Tuesday",
"Wednesday",
"Thursday",
"Friday"
],
"serviceTimeInterval": "PT15M", // in slots spaced 15 minutes apart
"advanceBookingRequirement": {
"minValue": 60, // The slot should be at least 60 mins away
"maxValue": 8640, // but not more than 6 days away
"unitCode": "MIN"
}
}
}
...
בשירות הזה לדוגמה אפשר לבצע הזמנות בכל יום בין 8:00 ל-16:59:59, והלקוחות יכולים לבחור משלוח תוך שעה או לבחור באחת מהאפשרויות הבאות:
...
{
"@type": "OpeningHoursSpecification",
"opens": "T08:00:00", // Ordering opens at 8:00AM
"closes": "T17:00:00", // Ordering closes at 5:00PM, last order at 4:59:59PM
"deliveryHours": [
{
"@type": "ServiceDeliveryHoursSpecification",
"opens": "T08:00:00",
"closes": "T17:00:00",
"deliveryLeadTime": {
"@type": "QuantitativeValue",
"value": "60", // If no exact deliveryLeadTime, put a maximum time
"unitCode": "MIN"
}
},
{
"@type": "AdvanceServiceDeliveryHoursSpecification",
"opens": "T08:00:00",
"closes": "T17:00:00",
"serviceTimeInterval": "PT15M", // in slots spaced 15 minutes apart
"advanceBookingRequirement": {
"minValue": 90, // The slot should be at least 90 mins away
"maxValue": 8640, // but not more than 6 days away
"unitCode": "MIN"
}
}
]
}
...
הדוגמה הבאה מציגה מקרה שבו החנות נפתחת בין 8:00 ל-16:59:59 בימי חול, אבל בסופי שבוע בשעות 8:00 עד 18:59. לא ניתן לקבל הזמנות 24 שעות ביממה, 7 ימים בשבוע.
...
{
// On weekdays, ordering open from 8AM-4:59:59PM.
"@type": "OpeningHoursSpecification",
"opens": "T08:00:00",
"closes": "T17:00:00",
"dayOfWeek": [
"Monday",
"Tuesday",
"Wednesday",
"Thursday",
"Friday"
],
"deliveryHours": [
{
// Fulfillment between 8AM-4:59:59PM on weekdays.
"@type": "AdvanceServiceDeliveryHoursSpecification",
"opens": "T08:00:00",
"closes": "T17:00:00",
"dayOfWeek": [
"Monday",
"Tuesday",
"Wednesday",
"Thursday",
"Friday"
],
"serviceTimeInterval": "PT15M",
"advanceBookingRequirement": {
"minValue": 60,
"maxValue": 8640,
"unitCode": "MIN"
}
},
{
// Fulfillment between 8AM-6:59:59PM on weekends (even for orders placed on a
// weekday).
"@type": "AdvanceServiceDeliveryHoursSpecification",
"opens": "T08:00:00",
"closes": "T19:00:00",
"dayOfWeek": [
"Saturday",
"Sunday"
],
"serviceTimeInterval": "PT15M",
"advanceBookingRequirement": {
"minValue": 60,
"maxValue": 8640,
"unitCode": "MIN"
}
}
]
},
{
// On weekends, one can place orders upto 6:59:59PM.
"@type": "OpeningHoursSpecification",
"opens": "T08:00:00",
"closes": "T19:00:00",
"dayOfWeek": [
"Saturday",
"Sunday"
],
"deliveryHours": [
{
// But fulfillment on weekdays is only till 4:59:59PM.
"@type": "AdvanceServiceDeliveryHoursSpecification",
"opens": "T08:00:00",
"closes": "T17:00:00",
"dayOfWeek": [
"Monday",
"Tuesday",
"Wednesday",
"Thursday",
"Friday"
],
"serviceTimeInterval": "PT15M",
"advanceBookingRequirement": {
"minValue": 60,
"maxValue": 8640,
"unitCode": "MIN"
}
},
{
// Fulfillment on weekends is till 6:59:59PM.
"@type": "AdvanceServiceDeliveryHoursSpecification",
"opens": "T08:00:00",
"closes": "T19:00:00",
"dayOfWeek": [
"Saturday",
"Sunday"
],
"serviceTimeInterval": "PT15M",
"advanceBookingRequirement": {
"minValue": 60,
"maxValue": 8640,
"unitCode": "MIN"
}
}
]
}
...