إضافة حجوزات غير متزامنة

يتم تعريف الحجوزات المتزامنة على أنها حجوزات تم تأكيدها أو رفضها في الوقت الفعلي.

يتم تعريف الحجوزات غير المتزامنة على أنها حجوزات يؤكدها التاجر أو يرفضها في وقت لاحق.

يتم تحديد الحجز على أنّه متزامن أو غير متزامن على مستوى التوفّر. وهذا يعني أيضًا أنّه قد تتوفّر خانات توفّر متزامنة وغير متزامنة لدى التاجر وخدمة معيّنة.

لتحديد طريقة التنفيذ المناسبة، حدِّد أولاً الفئة التي يندرج ضمنها مستودعك:

معايير الحجز غير المتزامن

  • لا يمكن تعديل حجز غير متزامن في "مركز الإجراءات".
  • يجب أن يتمكّن التجّار من قبول الحجز أو رفضه من خلال نظام الشريك على الإنترنت (على سبيل المثال، لوحة المضيف للمطعم). لا يُسمح بالاتصال بالتاجر نيابةً عن المستخدم لتحديد ما إذا كان التاجر يقبل الحجز أو يرفضه.
  • لا يُسمح بعرض اقتراح من التاجر لوقت حجز جديد. يجب قبول طلب الحجز أو رفضه بالحالة الأصلية.

تفعيل الحجوزات المتزامنة فقط

يتم ضبط التنفيذ العادي تلقائيًا على الحجوزات المتزامنة. يُرجى الاطّلاع على مستندات الدمج التام بين الحجوزات للحصول على مزيد من المعلومات.

جارٍ تفعيل الحجز غير المتزامن

إذا كان بعض التجّار أو جميعهم يستخدمون مسار حجز غير متزامن، يجب إجراء التغييرات التالية:

  • وضع التأكيد: تحتوي الآن جميع الرسومات على خانات مدى التوفّر على الحقل confirmation_mode الذي يصف كيف يتم تأكيد الحجوزات في خانة مدى التوفّر هذه. حدِّد confirmation_mode لكل خانة مدى توفُّر لما يلي:

    • يتم تحديد confirmation_mode على مستوى مدى التوفّر في خلاصة مدى التوفّر.
    • في طرق واجهة برمجة تطبيقات خادم الحجز، يتم تحديد confirmation_mode على مستوى الخانة
    • في طرق واجهة برمجة التطبيقات للتحديثات في الوقت الفعلي، يتم تحديد 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.

غير متزامنة

{
  "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 أو 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.

عند تعديل الحالة، احرص على تضمين اسم الحقل 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 وحدِّد 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