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

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

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

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

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

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

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

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

الإعداد التلقائي هو الحجوزات المتزامنة. يُرجى الرجوع إلى وثائق الدمج التام بين الأطراف للمواعيد للحصول على مزيد من المعلومات.

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

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

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

    • في خلاصة مدى التوفّر، يتم تحديد السمة confirmation_mode على مستوى مدى التوفّر.
    • في طرق Booking Server API، يتم تحديد 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 التي يتم تعديلها في الوقت الفعلي. إذا أردت رفض الحجوزات تلقائيًا التي لا يتم الردّ عليها في الوقت المناسب، يمكنك إجراء ذلك باستخدام طريقة التعديل نفسها في الوقت الفعلي.

خلاصات مدى التوفّر

في خلاصة مدى التوفّر، حدِّد ما إذا كانت كل خانة متزامنة أو غير متزامنة. ولإجراء ذلك، عليك ضبط الحقل 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 أو Check مشاهد

في 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 أو 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 وحدِّد Book_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