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

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

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

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

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

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

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

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

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

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

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

  • מצב אישור: כל הייצוגים של משבצות זמינות מכילים עכשיו את השדה 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 של ההזמנות.

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

איור 1: תהליך הזמנה אסינכרוני
איור 1: תהליך הזמנה אסינכרוני
  1. הפידים של הזמינות עודכנו כך שצוין מצב האישור של כל משבצת זמינות. חשוב לכלול את המידע הזה בפיד כדי שנוכל להסביר למשתמש את האופי האסינכרוני של ההזמנה בשלב מוקדם בתהליך.
  2. כשאנחנו מתקשרים אל BatchAvailabilityLookup או את CheckAvailability אנחנו מעבירים את מצב האישור, ועדיף שיהיה זהה למצב האישור. כך ניתן להבטיח שהמשתמש יראה את המסר המתאים.
  3. כשאנחנו מפעילים את CreateBooking, אנחנו מעבירים את מצב האישור כדי לציין את מצב האישור הצפוי. כשנשלחת הבקשה להזמנה אסינכרונית, ההזמנה מוחזרת בסטטוס PENDING_MERCHANT_CONFIRMATION.
  4. כשהמוכר מאשר או דוחה בקשה להזמנה, סטטוס ההזמנה מתעדכן באמצעות המתודה 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