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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

{
  "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-אסינכרוני

{
  "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 או Batch ExchangeServiceAvailability)

באמצעות ה-method 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 של התראות הזמנה

עדכונים אסינכרוניים בסטטוס ההזמנה צריכים להתבצע דרך ה-method 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