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

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

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

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

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

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

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

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

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

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

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

  • وضع التأكيد: تحتوي الآن كل تمثيلات خانات مدى التوفّر على حقل 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"
    }
  ]
}

Async وSync

{
  "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. وينطبق ذلك على الطرق التالية:

إعادة عرض معلومات المخزون (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"
        }
      ]
    }
  ]
}

Async وSync

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

الحالة الوصف
تم تأكيد الحجز أكّد التاجر الحجز.
فشل تعذّر على الشريك تأكيد الحجز أو رفضه مع التاجر
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