הזמנות סינכרוניות הן הזמנות שאושרו או נדחו בזמן אמת.
הזמנות אסינכרוניות מוגדרות כהזמנות שהמוכר מאשר או דוחה במועד מאוחר יותר.
הזמנה מוגדרת כסינכרונית או כאסינכרונית ברמת הזמינות. המשמעות היא גם שלמוכר ושירות מסוימים ייתכן שיהיו משבצות זמינות סינכרוניות ואסינכרוניות.
כדי לקבוע איך לבצע את ההטמעה המתאימה, קודם צריך לזהות את הקטגוריה של המלאי שלך:
- הפעלת הזמנות סינכרוניות בלבד: כל המוכרים והשירותים מקבלים אישור באופן מיידי.
- הפעלת הזמנות אסינכרוניות: חלק מהמוכרים והשירותים מחייבים אישור ידני של המוכר.
קריטריונים אסינכרוניים להזמנה
- לא ניתן לשנות הזמנה אסינכרונית במרכז הפעולות.
- למוכרים צריכה להיות אפשרות לאשר או לדחות את ההזמנה דרך המערכת אונליין של השותף (למשל, חלונית המארח של המסעדה). אסור להתקשר למוכר בשם המשתמש כדי לברר אם המוכר מאשר או דוחה הזמנה.
- ההצעה של המוכר לקביעת מועד חדש להזמנה לא נתמכת. צריך לאשר או לדחות את ההזמנה במצב המקורי.
הפעלת הזמנות סינכרוניות בלבד
כברירת מחדל, בהטמעה הרגילה מוגדרת השיטה 'הזמנות סינכרוניות'. במסמכי התיעוד בנושא שילוב מקצה לקצה של פגישות תוכלו למצוא מידע נוסף.
הפעלת הזמנה אסינכרונית
אם חלק מהמוכרים או כולם משתמשים בתהליך הזמנות אסינכרוני, יש לבצע את השינויים הבאים:
-
מצב אישור: כל הייצוגים של משבצות זמינות מכילים עכשיו את השדה
confirmation_mode
, שבו מוסבר איך מתבצע האישור של ההזמנות במשבצת הזמינות הזו. צריך לציין אתconfirmation_mode
של כל משבצת זמינות עבור הפריטים הבאים:- בפיד הזמינות,
confirmation_mode
צוין ברמת הזמינות - ב-methods של Booking Server API,
confirmation_mode
מצוין ברמת יחידת הקיבולת (Slot) - ב-methods של Real-Time Updates API,
confirmation_mode
מצוין ברמת הזמינות
- בפיד הזמינות,
- סטטוס ההזמנה: כל הייצוגים של ההזמנות מכילים
את השדה
status
שמייצג את מצב ההזמנה. הוספנו שלושה ערכי סטטוס אסינכרוניים חדשים:PENDING_CONFIRMATION
,DECLINED_BY_MERCHANT
ו-FAILED
. כדאי להשתמש בערכי הסטטוס החדשים האלה במהלך עיבוד יצירות, דחיות וכישלונות של הזמנות אסינכרוניות. - עדכונים לגבי הזמנות: צריך לדווח על כל העדכונים האסינכרוניים בסטטוס של ההזמנות דרך המתודה bookings.patch של ההזמנות.
בתרשים הבא אפשר לראות איך משתמשים במצב אישור ובסטטוס ההזמנה באינטראקציה אסינכרונית אופיינית של הזמנות.
- הפידים של הזמינות עודכנו כך שצוין מצב האישור של כל משבצת זמינות. חשוב לכלול את המידע הזה בפיד כדי שנוכל להסביר למשתמש את האופי האסינכרוני של ההזמנה בשלב מוקדם בתהליך.
- כשאנחנו מתקשרים אל
BatchAvailabilityLookup
או אתCheckAvailability
אנחנו מעבירים את מצב האישור, ועדיף שיהיה זהה למצב האישור. כך ניתן להבטיח שהמשתמש יראה את המסר המתאים. - כשאנחנו מפעילים את
CreateBooking
, אנחנו מעבירים את מצב האישור כדי לציין את מצב האישור הצפוי. כשנשלחת הבקשה להזמנה אסינכרונית, ההזמנה מוחזרת בסטטוסPENDING_MERCHANT_CONFIRMATION
. - כשהמוכר מאשר או דוחה בקשה להזמנה, סטטוס ההזמנה מתעדכן באמצעות המתודה bookings.patch של העדכון בזמן אמת של Booking Notification API. אם ברצונך לדחות אוטומטית הזמנות שלא נענו בפרק זמן סביר, צריך לעשות זאת באותה שיטת עדכון בזמן אמת.
פידים של זמינות
בפיד הזמינות, צריך לציין אם כל יחידת קיבולת (Slot) היא סינכרונית או
אסינכרונית. כדי לעשות זאת, צריך להגדיר את השדה החדש
confirmation_mode
.
// Mode by which bookings for an availability slot are confirmed. // enum ConfirmationMode { // The confirmation mode was not specified. // Synchronous confirmation will be assumed. CONFIRMATION_MODE_UNSPECIFIED = 0; // Bookings for this availability will be confirmed synchronously. CONFIRMATION_MODE_SYNCHRONOUS = 1; // Bookings for this availability will be confirmed asynchronously. CONFIRMATION_MODE_ASYNCHRONOUS = 2; }
למרות שמצב האישור הוא סינכרוני אם לא צוין מצב, מומלץ מאוד לציין באופן מפורש את המצב, מפני שמסיר כל בלבול בנוגע להשמטות מקריות.
אסינכרוני
{ "availability": [ { "merchant_id": "10001", "service_id": "1000", "spots_open": 3, "spots_total": 3, "duration_sec": 3600, "start_sec": 1535806800, "resources": { "party_size": 4 }, "confirmation_mode": "CONFIRMATION_MODE_ASYNCHRONOUS" } ] }
סנכרון
{ "availability": [ { "merchant_id": "10001", "service_id": "1000", "spots_open": 3, "spots_total": 3, "duration_sec": 3600, "start_sec": 1535806800, "resources": { "party_size": 4 }, "confirmation_mode": "CONFIRMATION_MODE_SYNCHRONOUS" } ] }
אסינכרוני וסנכרון
{ "availability": [ { "merchant_id": "10001", "service_id": "1000", "spots_open": 3, "spots_total": 3, "duration_sec": 3600, "start_sec": 1535806800, "resources": { "party_size": 4 }, "confirmation_mode": "CONFIRMATION_MODE_SYNCHRONOUS" }, { "merchant_id": "10002", "service_id": "1000", "spots_open": 4, "spots_total": 4, "duration_sec": 3600, "start_sec": 1535806800, "resources": { "party_size": 2 }, "confirmation_mode": "CONFIRMATION_MODE_ASYNCHRONOUS" } ] }
שרת הזמנות
BatchAvailabilityLookup או CheckAvailability
ב-BatchAvailabilityLookupResponse
(BAL)
או ב-CheckAvailabilityResponse
(CA), מחזירים את אותו confirmation_mode
כפי שצוין
בפיד הזמינות ומועבר באמצעות
BatchAvailabilityLookupRequest
או
CheckAvailabilityRequest
.
אסינכרוני BAL
{ "slot_time_availability": [ { "slot_time": { "duration_sec": "3600", "resource_ids": { "party_size": 3 }, "service_id": "1000", "start_sec": "1546458300", "confirmation_mode": "CONFIRMATION_MODE_ASYNCHRONOUS" }, "available": true } ] }
סנכרון BAL
{ "slot_time_availability": [ { "slot_time": { "duration_sec": "3600", "resource_ids": { "party_size": 3 }, "service_id": "1000", "start_sec": "1546458300", "confirmation_mode": "CONFIRMATION_MODE_SYNCHRONOUS" }, "available": true } ] }
CA-Async
{ "slot": { "duration_sec": "3600", "merchant_id": "317652", "resources": { "party_size": 3 }, "service_id": "1000", "start_sec": "1546458300", "confirmation_mode": "CONFIRMATION_MODE_ASYNCHRONOUS" }, "count_available": 1, "duration_requirement": "DO_NOT_SHOW_DURATION" }
סנכרון CA
{ "slot": { "duration_sec": "3600", "merchant_id": "317652", "resources": { "party_size": 3 }, "service_id": "1000", "start_sec": "1546458300", "confirmation_mode": "CONFIRMATION_MODE_SYNCHRONOUS" }, "count_available": 1, "duration_requirement": "DO_NOT_SHOW_DURATION" }
CreateBooking
חשוב להחזיר את הסטטוס הנכון של ההזמנה באמצעות האפשרויות הזמינות הבאות:
// Status of a booking. // // Updating booking status does not change the status of the associated payment. // Prepayment status updates should be done using the PrepaymentStatus enum. enum BookingStatus { // Not specified. BOOKING_STATUS_UNSPECIFIED = 0; // Booking has been confirmed CONFIRMED = 1; // Booking is awaiting confirmation by the merchant before it can transition // into CONFIRMED status. Only applicable to non-payments Dining or // Beauty verticals. PENDING_MERCHANT_CONFIRMATION = 2; // Booking has been canceled on behalf of the user. // The merchant can still trigger a manual refund. CANCELED = 3; // User did not show for the appointment NO_SHOW = 4; // User did not show for the appointment in violation of the cancellation // policy. NO_SHOW_PENALIZED = 5; // Booking could not be completed by the async backend due to a failure. FAILED = 6; // Booking was asynchronously declined by the merchant. Only applicable to // non-payments Dining or Beauty verticals. DECLINED_BY_MERCHANT = 7; }
בשדה CreateBookingResponse
,
מחזירים את ה-confirmation_mode
הנוכחי עבור המשבצת המצטברת של ההזמנה שצוינה
ב-CreateBookingRequest. בנוסף, כשההזמנה אסינכרונית,
צריך להגדיר את status
לערך PENDING_MERCHANT_CONFIRMATION
. יש לוודא
שהconfirmation_mode
הוא השם של המשתמש, וכן מה ש-'Google הזמנת מקומות' מצפה לו כדי למנוע בלבול.
אסינכרוני
{ "booking": { "slot": { "duration_sec": "3600", "merchant_id": "100001", "resources": { "party_size": 2 }, "service_id": "1000", "start_sec": "1546647234", "confirmation_mode": "CONFIRMATION_MODE_ASYNCHRONOUS" }, "user_information": { "email": "johnsmith@gmail.com", "family_name": "John", "given_name": "Smith", "telephone": "+1 800-123-4567", "user_id": "2017492857928759285" }, "payment_information": { "prepayment_status": "PREPAYMENT_NOT_PROVIDED" }, "status": "PENDING_MERCHANT_CONFIRMATION" } }
סנכרון
{ "booking": { "slot": { "duration_sec": "3600", "merchant_id": "100001", "resources": { "party_size": 2 }, "service_id": "1000", "start_sec": "1546647234", "confirmation_mode": "CONFIRMATION_MODE_SYNCHRONOUS" }, "user_information": { "email": "johnsmith@gmail.com", "family_name": "John", "given_name": "Smith", "telephone": "+1 800-123-4567", "user_id": "2017492857928759285" }, "payment_information": { "prepayment_status": "PREPAYMENT_NOT_PROVIDED" }, "status": "CONFIRMED" } }
UpdateBooking
בגרסה הראשונית של האסינכרוני, אין תמיכה בשינויים שבוצעו על ידי משתמשים בהזמנה קיימת. במקום זאת, המשתמש צריך לבטל את ההזמנה וליצור הזמנה חדשה.
עדכונים בזמן אמת
כדי לקבל עדכונים בזמן אמת לגבי זמינות, צריך לציין את confirmation_mode
. הכלל הזה חל על השיטות הבאות:
RTU של מלאי (ReplaceServiceAvailability או BatchReplaceServiceAvailability)
באמצעות
השיטה availability.replace
(באצווה)
או
בשיטה services.availability.replace
,
מגדירים את confirmation_mode
כ-CONFIRMATION_MODE_ASYNCHRONOUS
בAvailability
אסינכרוני
{ "extendedServiceAvailability": [ { "merchantId": "1001", "serviceId": "12310", "startTimeRestrict": "2014-10-02T15:01:23.045123456Z", "endTimeRestrict": "2014-10-02T19:01:23.045123456Z", "availability": [ { "startTime": "2014-10-02T15:30:00.00Z", "duration": "3600s", "spotsOpen": "0", "spotsTotal": "2", "availabilityTag": "1000001", "confirmation_mode": "CONFIRMATION_MODE_ASYNCHRONOUS" } ] } ] }
סנכרון
{ "extendedServiceAvailability": [ { "merchantId": "1001", "serviceId": "12310", "startTimeRestrict": "2014-10-02T15:01:23.045123456Z", "endTimeRestrict": "2014-10-02T19:01:23.045123456Z", "availability": [ { "startTime": "2014-10-02T15:30:00.00Z", "duration": "3600s", "spotsOpen": "0", "spotsTotal": "2", "availabilityTag": "1000001", "confirmation_mode": "CONFIRMATION_MODE_SYNCHRONOUS" } ] } ] }
אסינכרוני וסנכרון
{ "extendedServiceAvailability": [ { "merchantId": "1001", "serviceId": "12310", "startTimeRestrict": "2014-10-02T15:01:23.045123456Z", "endTimeRestrict": "2014-10-02T19:01:23.045123456Z", "availability": [ { "startTime": "2014-10-02T15:30:00.00Z", "duration": "3600s", "spotsOpen": "0", "spotsTotal": "2", "availabilityTag": "1000001", "confirmation_mode": "CONFIRMATION_MODE_ASYNCHRONOUS" }, { "startTime": "2014-10-03T11:00:00.00Z", "duration": "5400s", "spotsOpen": "1", "spotsTotal": "1", "availabilityTag": "1000002", "confirmation_mode": "CONFIRMATION_MODE_SYNCHRONOUS" } ] } ] }
ממשק API להתראות על הזמנות
כדי לבצע עדכונים אסינכרוניים בסטטוס ההזמנה, צריך להשתמש בשיטה bookings.patch של Booking Notification API.
כשמעדכנים את הסטטוס, חשוב לכלול את שם השדה status
ב-updateMask
.
סטטוס | התיאור |
---|---|
אושר | המוכר אישר את ההזמנה |
נכשלה | השותף לא הצליח לאשר או לדחות את ההזמנה מהמוכר |
DECLINED_BY_MERCHANT | המוכר דחה את ההזמנה |
Request: PATCH https://mapsbooking.googleapis.com/v1alpha/notification/partners/<PARTNER_ID>/bookings/<BOOKING_ID>?updateMask=status Body: {"name":"partners/<PARTNER_ID>/bookings/<BOOKING_ID>", "status":"DECLINED_BY_MERCHANT"}
במקרה של כשל בהזמנה, צריך להגדיר את סטטוס ההזמנה כ-FAILED
ולציין את הפרמטר order_failure. אם הסטטוס מוגדר לערך אחר, המערכת תתעלם
מהסטטוס booking_failure
.
Request: PATCH https://mapsbooking.googleapis.com/v1alpha/notification/partners/<PARTNER_ID>/bookings/<BOOKING_ID>?updateMask=status&booking_failure.cause="SLOT_UNAVAILABLE" Body: {"name":"partners/<PARTNER_ID>/bookings/<BOOKING_ID>", "status":"FAILED"}
התראות באימייל
במקרה של הזמנות אסינכרוניות, המערכת שולחת למשתמשים חמש אימיילים פוטנציאליים שקשורים לסטטוס של ההזמנה.
PENDING_MERCHANT_CONFIRMATION
CONFIRMED
DECLINED_BY_MERCHANT
FAILED
CANCELED