REST Resource: inventory.partners.merchants.services.availability

المرجع: مدى التوفّر

خانة توفّر خدمة التاجر، مع الإشارة إلى الوقت وعدد الأماكن

تمثيل JSON 
{
  "startTime": string,
  "duration": string,
  "spotsTotal": string,
  "spotsOpen": string,
  "availabilityTag": string,
  "resources": {
    object (Resources)
  },
  "paymentOptionId": [
    string
  ],
  "recurrence": {
    object (Recurrence)
  },
  "scheduleException": [
    {
      object (ScheduleException)
    }
  ],
  "deposit": {
    object (Deposit)
  },
  "noShowFee": {
    object (NoShowFee)
  },
  "requireCreditCard": enum (RequireCreditCard),
  "ticketTypeId": [
    string
  ],
  "durationRequirement": enum (DurationRequirement),
  "schedulingRuleOverrides": {
    object (SchedulingRuleOverrides)
  },
  "confirmationMode": enum (ConfirmationMode)
}
الحقول
startTime

string (Timestamp format)

وقت بدء خانة المواعيد

طابع زمني بتنسيق RFC3339 UTC "Zulu" ، بدقة نانو ثانية وما يصل إلى تسعة أرقام كسرية. أمثلة: "2014-10-02T15:01:23Z" و"2014-10-02T15:01:23.045123456Z"
duration

string (Duration format)

مدة خانة المواعيد

مدة بالثواني مؤلفة من تسعة أرقام كسور وتنتهي بـ "s". مثال: "3.5s".
spotsTotal

string (int64 format)

إجمالي عدد الأماكن والأماكن المفتوحة لهذا التوافر. أمثلة:

  • صف يوغا يضم 10 أماكن و3 محجوزة: availability {spotsTotal: 10, spotsOpen: 7 ...}
  • جلسة تدليك على كرسي تم حجزها بالكامل: availability {spotsTotal: 1, spotsOpen: 0 ...}

ملاحظة: في حال إرسال الطلبات باستخدام تنسيق ضغط مدى التوفّر المحدّد أدناه، سيتم استنتاج هذين الحقلَين.

  • يشير التكرار إلى spotsTotal=1 وspotsOpen=1.
  • يتضمن استثناء الجدول الزمني spotsTotal=1 وspotsOpen=0.
spotsOpen

string (int64 format)

عدد الأماكن المفتوحة.
availabilityTag

string

سلسلة اختيارية مبهمة لتحديد خانة مدى التوفّر هذه. وفي حال ضبطها، سيتم تضمينها في الطلبات التي تؤدي إلى حجز/تعديل/إلغاء المواعيد.
resources

object (Resources)

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

على سبيل المثال، نفس فصل اليوغا مع اثنين من المدربين:

availability { resources { staffId: "1" staffName: "Amy" }
               spotsTotal: 10 spotsOpen: 7 }
availability { resources { staffId: "2" staffName: "John" }
               spotsTotal: 5 spotsOpen: 2 }
paymentOptionId[]

string

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

يلغي هذا الحقل أي معرّفات payment_option_ids المحدَّدة في رسالة الخدمة. وبالمثل، لا يجب أن تكون معرّفات payment_option_id المحددة هنا موجودة في رسالة الخدمة، ولكن يجب تحديدها على مستوى التاجر.
recurrence

object (Recurrence)

معلومات التكرار الخاصة بمدى التوفّر، والتي تمثل أكثر من وقت بدء واحد. يجب أن يحتوي التكرار على مواعيد ليوم عمل واحد.
scheduleException[]

object (ScheduleException)

الأوقات التي تتعذّر فيها جدولة هذه الخدمة. للحد من عدد رسائل scheduleException، يمكنك الانضمام إلى الاستثناءات المجاورة.
deposit

object (Deposit)

مبلغ إيداع اختياري مقابل هذا مدى التوفّر تلغي هذه العلامة إيداع الخدمة في حال تحديد مبلغ إيداع.
noShowFee

object (NoShowFee)

اختيارية بدون رسوم عرض لهذا مدى التوفّر. تلغي هذه العلامة رسوم عدم العرض في حال تحديد رسوم.
requireCreditCard

enum (RequireCreditCard)

تشير هذه السمة إلى ما إذا كان على المستخدم تقديم بطاقة ائتمان لحجز خانة مدى التوفّر هذه. إذا لم يتم ضبط القيمة، يتم اكتسابها من مستوى الخدمة في حال ضبطها هناك. (اختياري)
ticketTypeId[]

string

تشير هذه السمة إلى قائمة بأنواع التذاكر المتوافقة مع خانة مدى التوفّر هذه. في حال ترك هذه السياسة بدون ضبط، ستتوفّر جميع أنواع التذاكر في الخدمة الرئيسية لهذه الخانة. تجدر الإشارة إلى أنّه يجب تحديد قيم هذا الحقل في الخدمة الرئيسية. أمثلة:

  • خدمة تتضمّن أربعة أنواع من التذاكر: TicketType {ticketTypeId: "adult_1" ShortDescription: "Adult Fridays"} TicketType {ticketTypeId: "adult_2" ShortDescription: "Adult calendars"} نوع التذاكر {ticketTypeId: "youth_1" ShortDescription: "Youth weeks"} TicketType {ticketTypeId: "youth_2" ShortDescription: "Youth weeks"}

لتمثيل المستودع خلال أيام الأسبوع: availability {ticketTypeId: "adult_1" ticketTypeId: "youth_1"...}. لتمثيل المستودع خلال موسم الأعياد: availability {ticketTypeId: "adult_2" ticketTypeId: "youth_2"...}.

  • خدمة تتضمَّن ثلاثة أنواع من التذاكر: TicketTypeId: "adult" ShortDescription: "Adult"} نوع التذكرة {ticketTypeId: "youth" ShortDescription: "Youth"} نوع التذكرة {ticketTypeId: "senior" ShortDescription: "Adult"}

للإشارة إلى أنّ جميع أنواع التذاكر الثلاثة متوفّرة لهذه الخانة الزمنية، استخدِم إما availability {ticketTypeId: "adult" ticketTypeId: "youth" ticketTypeId: "senior" ...} أو "مدى التوفّر {...}" (يجب عدم ضبط ticketsTypeId في هذه الخانة).

(اختياري)
durationRequirement

enum (DurationRequirement)

شرط عرض مدّة الخانات و/أو وقت الانتهاء. سيتم تجاهل هذا الحقل في حال عدم توفّر الخانة. لا تُستخدم في مجال "نشاطات مقترَحة". (اختياري)
schedulingRuleOverrides

object (SchedulingRuleOverrides)

قواعد جدولة مدى التوفّر. إذا تمت تعبئة الحقول، سيتم إلغاء أي قواعد جدولة مقابلة لـ Scheduleالقواعد على مستوى الخدمة.
confirmationMode

enum (ConfirmationMode)

تمثّل هذه السمة وضع التأكيد الذي سيتم استخدامه عند حجز هذا مدى التوفّر. يجب تأكيد أو رفض محاولات إنشاء حجوزات للتوفّر باستخدام وضع تأكيد ConfirmATION_Mode_SYNCHRONOUS على الفور. يجب رفض محاولات إنشاء حجوزات للتوفّر باستخدام وضع التأكيد في ConfirmATION_Mode_ASYNCHRONOUS على الفور أو إنشاؤها بالحالة "معلّق".

المراجِع

يتم استخدام المورد لتمييز خانات التوفر عن بعضها البعض عندما يكون مختلف الموظفين أو الغرف جزءًا من الخدمة. يمكن أن تظهر خانات متعددة لنفس الخدمة والفاصل الزمني عندما يكون لديهم موارد مختلفة.

تمثيل JSON 
{
  "staffId": string,
  "staffName": string,
  "roomId": string,
  "roomName": string,
  "partySize": integer
}
الحقول
staffId

string

بطاقة تعريف اختيارية لموظف يقدّم الخدمة. يحدّد هذا الحقل الموظف في كل التجّار والخدمات وسجلّات مدى التوفّر. كما يجب أن يكون مستقرًا بمرور الوقت للسماح بالارتباط مع الحجوزات السابقة. يجب أن يكون هذا الحقل متوفّرًا إذا كان employeeName.
staffName

string

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

string

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

string

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

integer

ينطبق ذلك على تناول الطعام فقط: عدد الأشخاص الذين يمكن اصطحابهم خلال هذه الفترة الزمنية. يمكن ربط مطعم بعدة خانات في الوقت نفسه، ويحدد كل منها حجم حفل مختلفًا، على سبيل المثال، يمكن حجز شخصين أو 3 أو 4 أشخاص لإجراء حجز.

التكرار

تكون رسائل التكرار اختيارية، ولكنها تسمح بتمثيل أكثر إحكامًا لخانات التوافر المتكررة باستمرار. عادة ما تمثل جدول العمل اليومي. بعد ذلك، يتم استخدام رسائل ScheduleException لتمثيل النطاقات الزمنية المحجوزة/غير المتاحة خلال يوم العمل.

المتطلبات:

  1. يجب ألا يؤدي توسيع خانات مدى التوفر أو التكرارات إلى إنشاء خانات متطابقة. في حال تطابق أرقام التعريف ووقت البدء والمدة والموارد، يتم اعتبار الخانات متطابقة.
  2. لا تخلط بين تنسيق مدى التوفّر العادي والتكرار داخل خانات خدمة واحدة. تعود فائدة التكرار على التجّار أو الخدمات التي تقدّم مواعيد. يركّز الشكل العادي على التجّار أو الخدمات التي تتضمّن صفوفًا تم تحديد مواعيدها بانتظام.
  3. وينبغي ألا تدوم التكرارات لأكثر من 24 ساعة.
تمثيل JSON 
{
  "repeatUntil": string,
  "repeatEvery": string
}
الحقول
repeatUntil

string (Timestamp format)

الحد الأقصى الشامل للطابع الزمني للتوقيت العالمي المتفق عليه الذي يتكرر فيه مدى التوفّر حتى.

طابع زمني بتنسيق RFC3339 UTC "Zulu" ، بدقة نانو ثانية وما يصل إلى تسعة أرقام كسرية. أمثلة: "2014-10-02T15:01:23Z" و"2014-10-02T15:01:23.045123456Z"
repeatEvery

string (Duration format)

تحدِّد هذه السياسة الوقت الفاصل بين خانات التوفّر المتتالية.

مثال: يؤدي مدى التوفّر لمدة 20 دقيقة، وتكرار كل 30 دقيقة، ووقت البدء من 9:00 صباحًا، والتكرار حتى 11:00 صباحًا إلى خانات مواعيد من 9:20 صباحًا إلى 9:30 صباحًا ومن 9:30 صباحًا إلى 9:50 صباحًا ومن 10:20 صباحًا ومن 10:30 صباحًا إلى 10:50 صباحًا و2:30 صباحًا. (معلومات مطلوبة)

مدة بالثواني مؤلفة من تسعة أرقام كسور وتنتهي بـ "s". مثال: "3.5s".

ScheduleException

تمثل رسائل ScheduleException نطاقات زمنية محجوزة/غير متاحة خلال يوم العمل، وهي استثناءات للتكرار الموضح أعلاه. عند حجز الخانات الزمنية، يجب تعديل قائمة الاستثناءات لتعكس النطاقات الزمنية غير المتاحة حديثًا. ينبغي عدم تعديل التكرار نفسه.

تمثيل JSON 
{
  "timeRange": {
    object (TimeRange)
  }
}
الحقول
timeRange

object (TimeRange)

النطاق الزمني للاستثناء. سيتم اعتبار أي خانات يصفها التكرار تتداخل مع هذا النطاق الزمني المغلق المفتوح غير متاحة.

مثال: إذا كان التكرار يحدد مدة 20 دقيقة، وتكرار كل 30 دقيقة، ووقت البدء من 9:00 ص، وتكرار حتى 11:00 ص، فعندئذ سيجعل إذن ScheduleException من خلال نطاق زمني من 9:45 صباحًا إلى 11:00 صباحًا الخانات من 9:30 صباحًا إلى 9:50 صباحًا ومن 10:30 صباحًا إلى 10:30 صباحًا

يُرجى العلم أنّه لن تتأثر الخانة التي تبدأ في الساعة 11 صباحًا بما أنّ النطاق الزمني مغلق.

DurationRequirement

ويشير هذا التعداد إلى المتطلّبات المتوفّرة للمستخدِم للإقرار بمدة/وقت الانتهاء المطلوبة أو الاطّلاع على مدة الخانات المطلوبة.

عمليات التعداد
DURATION_REQUIREMENT_UNSPECIFIED لم يتم تحديد وقت الانتهاء. وهذا هو الخيار التلقائي.
DO_NOT_SHOW_DURATION لا يظهر وقت الانتهاء للمستخدم.
MUST_SHOW_DURATION يجب عرض وقت الانتهاء للمستخدم قبل تحديد موعد.

SchedulingRuleOverrides

قواعد جدولة مستوى مدى التوفّر.

تمثيل JSON 
{
  "lastBookableSec": string,
  "firstBookableSec": string,
  "lastOnlineCancellableSec": string
}
الحقول
lastBookableSec

string (int64 format)

المرة الأخيرة (بالثواني) التي يمكن فيها حجز هذه الخانة. يجب أن يكون هذا الطابع الزمني قبل وقت بدء رأس الخانة الخاص بالخانة المُراد الالتزام بها (إذا كان من المفترض أن يتمكّن المستخدمون من الحجز بعد وقت البدء، استخدِم Scheduleالقواعدs.min_booking_before_end_time بمستوى الخدمة). في حال توفُّره، سيتم تجاهل أي شيء محدد في min_booking_buffer من قواعد Scheduleالقواعد الخاصة بالخدمة المقابلة.
firstBookableSec

string (int64 format)

المرة الأولى (بالثواني) التي يمكن فيها حجز هذه الخانة. يجب أن يكون هذا الطابع الزمني قبل تاريخ startSec للخانة أو lastBookableSec في حال تحديده.
lastOnlineCancellableSec

string (int64 format)

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

ConfirmationMode

أوضاع تأكيد الحجز المستخدَمة عند توفّر حجز

عمليات التعداد
CONFIRMATION_MODE_UNSPECIFIED لم يتم تحديد وضع التأكيد. وسيتم افتراض التأكيد المتزامن.
CONFIRMATION_MODE_SYNCHRONOUS سيتم تأكيد الحجوزات لهذا مدى التوفّر بشكلٍ متزامن.
CONFIRMATION_MODE_ASYNCHRONOUS سيتم تأكيد الحجوزات لهذا مدى التوفّر بشكل غير متزامن.

الطُرق

replace

 لاستبدال Availability للسمة Service الحالية الخاصة بتاجر يديره مجمّع السلع المحدّد وإرجاعه