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

עליכם ליצור בקשת תמיכה חדשה בפורטל השותפים.

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

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

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

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

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

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

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

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

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

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

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

מלאי RTU ‏ (ReplaceServiceAvailability או BatchReplaceServiceAvailability)

באמצעות השיטה availability.replace (batch) או השיטה 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

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