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

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

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

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

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

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

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

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

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

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

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

  • وضع التأكيد: تحتوي جميع طرق عرض خانات الأوقات المتاحة الآن على الحقل 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 في واجهة برمجة التطبيقات الخاصة بإشعارات الحجز.

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

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

وحدة 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 في 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