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

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

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

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

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

קריטריונים לאסינכרוניות של קביעת פגישות

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

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

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

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

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

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

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

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

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

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

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

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

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

{
  "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. ההנחיה הזו חלה על השיטות הבאות:

Inventory 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"
        }
      ]
    }
  ]
}

Booking Notification API

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

כשמעדכנים את הסטטוס, חשוב לכלול את שם השדה status ב-updateMask.

סטטוס תיאור
אושר merchant confirmed the booking
נכשל השותף לא הצליח לאשר או לדחות את ההזמנה אצל המוכר
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 ומציינים את booking_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