הפעלה של הזמנות אסינכרוניות

הזמנות סינכרוניות מוגדרות כהזמנות שאושרו או נדחו בזמן אמת.

הזמנות סינכרוניות מוגדרות כהזמנות שהמוכר מאשר או דוחה במועד מאוחר יותר.

הזמנה מוגדרת כסינכרונית או אסינכרונית ברמת הזמינות. פירוש הדבר הוא שלמוכר ולשירות נתון יכולים להיות משבצות זמינות סינכרוניות ואסינכרוניות.

כדי לקבוע את ההטמעה המתאימה, תחילה יש לזהות לאיזו קטגוריה שייכת המלאי שלך:

קריטריונים להזמנה אסינכרונית

  • לא ניתן לשנות הזמנה אסינכרונית ב-'Google הזמנת מקומות' .
  • לא ניתן לבצע הזמנות אסינכרוניות שדורשות תשלומים.
  • המוכרים צריכים לאשר או לדחות את ההזמנה דרך המערכת של השותף באינטרנט (לדוגמה, חלונית האירוח של המסעדה). קריאה למוכר בשם המשתמש כדי לקבוע אם המוכר מאשר או דוחה הזמנה לא מותרת.
  • אין תמיכה בהצעה של מוכר חדש למועד הזמנה חדש. עליך לאשר או לדחות את בקשת ההזמנה במצב המקורי.

הפעלה של הזמנות סינכרוניות בלבד

ברירת המחדל של ההטמעה הרגילה היא הזמנות סינכרוניות. כדי לקבל מידע נוסף, ניתן לעיין במדריך השילוב מקצה לקצה.

הפעלה של הזמנה אסינכרונית

אם חלק מהמוכרים או כולם משתמשים בתהליך הזמנה אסינכרוני, יש לבצע את השינויים הבאים:

  • מצב אישור: כל הייצוגים של משבצות זמינות כוללים עכשיו שדה confirmation_mode שמתאר את אופן אישור ההזמנות במשבצת הזמן הזו. צריך לציין את confirmation_mode בכל משבצת זמן של זמינות עבור הפרטים הבאים:

    • בפיד הזמינות, confirmation_mode מצוין ברמת הזמינות
    • בשיטות ה-API של שרת ההזמנות, confirmation_mode מצוין ברמת המיקום
    • בשיטות ה-API לעדכונים בזמן אמת, confirmation_mode צוין ברמת הזמינות
  • סטטוס הזמנה:כל הייצוגים של הזמנות מכילים שדה status שמייצג את מצב ההזמנה. נוספו שלושה ערכי סטטוס אסינכרוניים חדשים: PENDING_CONFIRMATION, DECLINED_BY_MERCHANT וFAILED. יש להשתמש בערכי הסטטוס החדשים האלה במהלך עיבוד היצירות, הדחיות והכשלים של הזמנות אסינכרוניות.
  • עדכונים בהזמנות: כל העדכונים האסינכרוניים של סטטוס ההזמנות צריכים להיות מדווחים דרך שיטת bookings.patch של Booking ההתראה.

בתרשים הבא מוצג אופן השימוש במצב אישור ובסטטוס הזמנה באינטראקציה אופיינית של הזמנה אסינכרונית.

איור 1: תהליך הזמנה אסינכרוני
איור 1: תהליך הזמנה אסינכרוני
  1. הפידים של הזמינות עודכנו כך שמצב האישור של כל משבצת זמן פנוי צוין. חשוב לכלול את המידע הזה בפיד כדי שנוכל להסביר למשתמש את האופי האסינכרוני של ההזמנה בשלב מוקדם בתהליך.
  2. כשמתבצעת התקשרות עם BatchAvailabilityLookup או CheckAvailability, אנחנו מעבירים את מצב האישור, ורצוי גם את אותו מצב אישור. כך מובטחת למשתמש מסר מתאים.
  3. כשמתבצעת קריאה אל CreateBooking, אנחנו מעבירים את מצב האישור כדי לציין את מצב האישור הצפוי. כששולחים בקשה להזמנה אסינכרונית, ההזמנה מוחזרת עם הסטטוס PENDING_MERCHANT_CONFIRMATION.
  4. כשהמוכר מאשר או דוחה בקשת הזמנה, סטטוס ההזמנה מתעדכן באמצעות השיטה Bookings.patch לעדכון בזמן אמת. אם ברצונך לדחות אוטומטית הזמנות שלא ענו עליהן בזמן, יש לעשות זאת באותה שיטת עדכון בזמן אמת.

פידים של זמינות

בפיד הזמינות, מציינים אם כל משבצת היא סינכרונית או אסינכרונית. כדי לעשות זאת, צריך להגדיר את השדה 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
    }
  ]
}

אסינכרוני

{
  "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"
}

יצירה

חשוב להחזיר את הסטטוס הנכון של ההזמנה באמצעות האפשרויות הזמינות שלמטה:

// 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"
  }
}

עדכון ההזמנה

בגרסה הראשונית של האסינכרוני, אין תמיכה בשינויים של משתמשים בהזמנה קיימת. במקום זאת, המשתמש צריך לבטל את ההזמנה וליצור הזמנה חדשה.

עדכונים בזמן אמת

כדי לקבל עדכונים בזמן אמת על זמינות המוצר, יש לציין את 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 להתראות על הזמנות

כדי לקבל עדכונים סינכרוניים של סטטוס הזמנה, צריך לבצע את השיטה של Booking Alert API bookings.patch.

כשמעדכנים את הסטטוס, חשוב לכלול את שם השדה 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