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)
  },
  "prepayment": {
    object (Prepayment)
  },
  "requireCreditCard": enum (RequireCreditCard),
  "ticketTypeId": [
    string
  ],
  "durationRequirement": enum (DurationRequirement),
  "schedulingRuleOverrides": {
    object (SchedulingRuleOverrides)
  },
  "confirmationMode": enum (ConfirmationMode),
  "linkoutRequiredReason": enum (LinkoutRequiredReason)
}
שדות
startTime

string (Timestamp format)

שעת ההתחלה של משבצת לפגישה.

הפלט שנוצר תמיד יהיה בפורמט RFC 3339, עם נורמליזציה של Z ושימוש ב-0, 3, 6 או 9 ספרות אחרי הנקודה. אפשר להשתמש גם בהיסטים אחרים חוץ מ-Z. דוגמאות: "2014-10-02T15:01:23Z", ‏ "2014-10-02T15:01:23.045123456Z" או "2014-10-02T15:01:23+05:30".
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.
  • ‫ScheduleException מרמז על 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_ids) שמצוינים כאן לא צריכים להופיע בהודעה על השירות, אבל הם צריכים להיות מוגדרים ברמת המוכר.
recurrence

object (Recurrence)

פרטי החזרה של הזמינות, שמייצגים יותר משעת התחלה אחת. כל מופע של הפגישה החוזרת צריך להיות ביום עסקים אחד.
scheduleException[]

object (ScheduleException)

השעות שבהן אי אפשר לתזמן את השירות הזה. כדי לצמצם את מספר ההודעות scheduleException, כדאי לאחד חריגות סמוכות.
deposit

object (Deposit)

סכום הפיקדון האופציונלי לזמינות הזו. מבטל את הפיקדון על השירות אם צוין פיקדון.
noShowFee

object (NoShowFee)

עמלה אופציונלית על אי-הגעה למימוש הזמינות הזו. התג הזה מבטל את עמלת אי-ההגעה לשירות, אם צוינה כזו.
prepayment

object (Prepayment)

אופציונלי. מידע אופציונלי על תשלום מראש לגבי הזמינות הזו.
requireCreditCard

enum (RequireCreditCard)

המאפיין הזה מציין אם המשתמש צריך לספק כרטיס אשראי כדי להזמין את משבצת הזמינות הזו. אם הערך לא מוגדר, הוא עובר בירושה מרמת השירות אם הוא מוגדר שם. (אופציונלי)
ticketTypeId[]

string

רשימה של סוגי הכרטיסים הנתמכים למשבצת הזמינות הזו. אם לא מגדירים את הערך הזה, כל סוגי הכרטיסים בשירות ההורה זמינים למשבצת הזו. הערה: הערכים של השדה הזה צריכים להיות מוגדרים בשירות ההורה. דוגמאות:

  • שירות עם ארבעה סוגי כרטיסים: TicketType {ticketTypeId: "adult_1" shortDescription: "Adult weekdays"} TicketType {ticketTypeId: "adult_2" shortDescription: "Adult weekends"} TicketType {ticketTypeId: "youth_1" shortDescription: "Youth weekdays"} TicketType {ticketTypeId: "youth_2" shortDescription: "Youth weekends"}

כדי לייצג את המלאי במהלך ימי חול: availability {ticketTypeId: "adult_1" ticketTypeId: "youth_1"...}. כדי לייצג את המלאי במהלך החגים: availability {ticketTypeId: "adult_2" ticketTypeId: "youth_2"...}.

  • שירות עם שלושה סוגי כרטיסים: TicketType {ticketTypeId: "adult" shortDescription: "Adult"} TicketType {ticketTypeId: "youth" shortDescription: "Youth"} TicketType {ticketTypeId: "senior" shortDescription: "Senior"}

כדי לציין שכל שלושת סוגי הכרטיסים זמינים למשבצת הזמן הזו, משתמשים באפשרות availability {ticketTypeId: "adult" ticketTypeId: "youth" ticketTypeId: "senior" ...} או באפשרות `availability {...}' (לא מגדירים את ticketTypeId במשבצת הזמן הזו).

(אופציונלי)
durationRequirement

enum (DurationRequirement)

הדרישה להצגת משך הזמן של חלונות הזמן ו/או שעת הסיום שלהם. המערכת תתעלם מהשדה הזה אם משבצת הזמן לא פנויה. לא נעשה בו שימוש בנישה 'פעילויות'. (אופציונלי)
schedulingRuleOverrides

object (SchedulingRuleOverrides)

כללים לקביעת זמינות. אם השדות מאוכלסים, הם יבטלו את כל כללי התזמון התואמים ב-SchedulingRules ברמת השירות.
confirmationMode

enum (ConfirmationMode)

מצב האישור שישמש להזמנת הזמינות הזו. ניסיונות ליצור הזמנות לזמינויות עם מצב אישור של CONFIRMATION_MODE_SYNCHRONOUS חייבים להיות מאושרים או נדחים באופן מיידי. ניסיונות ליצור הזמנות לזמינויות עם מצב אישור של CONFIRMATION_MODE_ASYNCHRONOUS צריכים להידחות באופן מיידי או להיווצר עם הסטטוס PENDING.
linkoutRequiredReason

enum (LinkoutRequiredReason)

אופציונלי. הסיבה שבגללה נדרש קישור לאתר חיצוני במשבצת הזו. אם המאפיין הזה מוגדר, למשאב המוכר של המשבצת הזו צריך להיות LinkoutTemplate תקין. (אופציונלי)

משאבים

המשאב משמש להבחנה בין משבצות זמן פנויות כשצוותים שונים או חדרים שונים הם חלק מהשירות. יכולים להיות כמה משבצות לאותו שירות ובאותו מרווח זמן, אם הן משתמשות במשאבים שונים.

ייצוג ב-JSON 
{
  "staffId": string,
  "staffName": string,
  "roomId": string,
  "roomName": string,
  "partySize": integer,
  "roomDescription": {
    object (Text)
  }
}
שדות
staffId

string

מזהה אופציונלי של איש צוות שמספק את השירות. השדה הזה מזהה את איש הצוות בכל הרשומות של המוֹכרים, השירותים והזמינות. הוא גם צריך להיות יציב לאורך זמן כדי לאפשר התאמה להזמנות קודמות. השדה הזה חייב להיות נוכח אם השדה staffName נוכח.
staffName

string

שם אופציונלי של איש צוות שמספק את השירות. השדה הזה יוצג למשתמשים שמבצעים הזמנה, והוא צריך להיות קריא לבני אדם, ולא מזהה אטום. חובה לציין את השדה הזה אם מציינים את staffId.
roomId

string

מזהה אופציונלי של החדר שבו השירות ממוקם. השדה הזה מזהה את החדר אצל כל המוֹכרים, השירותים ורשומות הזמינות. הוא גם צריך להיות יציב לאורך זמן כדי לאפשר התאמה להזמנות קודמות. השדה הזה חייב להיות קיים אם השדה roomName קיים.
roomName

string

שם אופציונלי של החדר שבו נמצא השירות. השדה הזה יוצג למשתמשים שמבצעים הזמנה, והוא צריך להיות קריא לבני אדם, ולא מזהה אטום. (אופציונלי, אבל חובה אם מצוין roomId) כשמזמינים מקום במסעדה, שם החדר צריך לשמש רק לציון אזורי ישיבה כמו הבר או המרפסת, ולא צריך להשתמש בו לציון תפריטים במחיר קבוע, פעילויות מיוחדות או כל ערך אחר שלא קשור לחדר (כמו הזמנה או ארוחת ערב). מומלץ מאוד שלא יהיה חדר שמשויך לאזור הישיבה שמוגדר כברירת מחדל.
partySize

integer

רלוונטי רק להזמנת מקומות במסעדות: מספר הסועדים שאפשר להושיב במשבצת הזמן הזו. מסעדה יכולה להיות משויכת לכמה משבצות זמן לאותה שעה, כשכל אחת מהן מציינת מספר שונה של אנשים, למשל אם אפשר להזמין מקום ל-2, 3 או 4 אנשים.
roomDescription

object (Text)

אופציונלי. תיאור החדר שמותאם לשוק המקומי. אם המאפיין מוגדר, צריך לספק ערך ברירת מחדל. מומלץ לספק גם שפות נפוצות ללוקאל של המוכר. (אופציונלי)

חזרה

הודעות על חזרתיות הן אופציונליות, אבל הן מאפשרות להציג בצורה קומפקטית יותר משבצות זמינות שחוזרות על עצמן באופן עקבי. הם בדרך כלל מייצגים את לוח הזמנים של יום העבודה. לאחר מכן, נעשה שימוש בהודעות ScheduleException כדי לייצג טווחי זמן מוזמנים או לא זמינים במהלך יום העבודה.

דרישות:

  1. הגדלת מספר המשבצות או המופעים לא יכולה ליצור משבצות זהות. אם הערכים של המאפיינים id,‏ startTime,‏ duration ו-resources זהים, המשבצות נחשבות זהות.
  2. אל תערבבו בין פורמט הזמינות הרגיל לבין חזרתיות במשבצות הזמן של אותו שירות. היתרונות של תזמון חוזר רלוונטיים למוכרים או לשירותים שמציעים אפשרות לקביעת פגישות. הפורמט הרגיל מיועד למוכרים או לספקי שירותים שמציעים שיעורים קבועים.
  3. מומלץ שהחזרה על עצמה לא תימשך יותר מ-24 שעות.
ייצוג ב-JSON 
{
  "repeatUntil": string,
  "repeatEvery": string
}
שדות
repeatUntil

string (Timestamp format)

חותמת הזמן בשעון UTC שמציינת את הזמן האחרון שבו הזמינות חוזרת על עצמה.

הפלט שנוצר תמיד יהיה בפורמט RFC 3339, עם נורמליזציה של Z ושימוש ב-0, 3, 6 או 9 ספרות אחרי הנקודה. אפשר להשתמש גם בהיסטים אחרים חוץ מ-Z. דוגמאות: "2014-10-02T15:01:23Z", ‏ "2014-10-02T15:01:23.045123456Z" או "2014-10-02T15:01:23+05:30".
repeatEvery

string (Duration format)

ההגדרה הזו מגדירה את הזמן בין משבצות זמינות עוקבות.

דוגמה: אם מגדירים זמינות עם משך של 20 דקות, חזרה כל 30 דקות, שעת התחלה של 9:00 ושעת סיום של 11:00, המשבצות שיופיעו הן 9:00-9:20,‏ 9:30-9:50,‏ 10:00-10:20,‏ 10:30-10:50 ו-11:00-11:20. (חובה)

משך זמן בשניות עם עד תשע ספרות אחרי הנקודה, שמסתיים ב-'s'. דוגמה: "3.5s".

ScheduleException

הודעות ScheduleException מייצגות טווחי זמן מוזמנים או לא זמינים במהלך יום העבודה, שהם חריגים לחזרה שמתוארת למעלה. ככל שיותר משבצות זמן מוזמנות, צריך לעדכן את רשימת החריגים כדי לשקף את טווחי הזמן החדשים שבהם אין זמינות. אין לשנות את המחזוריות עצמה.

ייצוג ב-JSON 
{
  "timeRange": {
    object (TimeRange)
  }
}
שדות
timeRange

object (TimeRange)

טווח הזמן של החריגה. כל המשבצות שמתוארות על ידי חזרתיות שחופפות לטווח הזמן הזה של סגירה ופתיחה ייחשבו כלא זמינות.

לדוגמה: אם התזמון החוזר מציין משך של 20 דקות, חזרה כל 30 דקות, שעת התחלה של 9:00 ושעת סיום של 11:00, אז חריגה מהתזמון עם טווח זמן של 9:45 עד 11:00 תגרום לכך שהמשבצות בשעות 9:30-9:50,‏ 10:00-10:20 ו-10:30-10:50 לא יהיו זמינות.

הערה: טווח הזמן הוא סגור-פתוח, ולכן המשבצת שמתחילה ב-11:00 לא תושפע.

תשלום מראש

תשלום שהמשתמש עשוי להיות מחויב עליו כחלק מההזמנה.

ייצוג ב-JSON 
{
  "priceInfo": {
    object (PriceInfo)
  }
}
שדות
priceInfo

object (PriceInfo)

קונטיינר לפרטי המחיר.

PriceInfo

קונטיינר לפרטי המחיר.

ייצוג ב-JSON 
{
  "priceType": enum (PriceType),

  // Union field price_options can be only one of the following:
  "price": {
    object (Price)
  },
  "priceRange": {
    object (PriceRange)
  }
  // End of list of possible types for union field price_options.
}
שדות
priceType

enum (PriceType)

הגדרה של אופן החלת המחיר או טווח המחירים (לכל אדם או קבוע)
שדה איחוד price_options. אפשרויות המחיר הן מחיר מדויק או טווח מחירים. הערך price_options יכול להיות רק אחד מהבאים:
price

object (Price)

המחיר של שירות או עמלה.
priceRange

object (PriceRange)

הגבול העליון ו/או התחתון של שירות או עמלה.

PriceRange

עוטף טווח של סכומים כספיים שמוגדר כבלתי מוגבל, אלא אם שני הערכים מוגדרים. צריך לציין לפחות אחד מהערכים minAmount ו-maxAmount.

ייצוג ב-JSON 
{
  "minPrice": {
    object (Price)
  },
  "maxPrice": {
    object (Price)
  }
}
שדות
minPrice

object (Price)

סכום מינימלי.
maxPrice

object (Price)

הסכום המקסימלי. תמיד צריך להיות גדול מ-minPrice.

DurationRequirement

הערך הזה מציין אילו דרישות קיימות כדי שהמשתמש יאשר או יראה את משך הזמן או את שעת הסיום של משבצות הזמן המבוקשות.

טיפוסים בני מנייה (enum)
DURATION_REQUIREMENT_UNSPECIFIED לא צוין הטיפול בשעת הסיום. זוהי ברירת המחדל.
DO_NOT_SHOW_DURATION שעת הסיום לא מוצגת למשתמש.
MUST_SHOW_DURATION שעת הסיום צריכה להיות מוצגת למשתמש לפני שהוא קובע פגישה.

SchedulingRuleOverrides

כללים לתזמון רמת הזמינות.

ייצוג ב-JSON 
{
  "lastBookableSec": string,
  "firstBookableSec": string,
  "lastOnlineCancellableSec": string
}
שדות
lastBookableSec

string (int64 format)

הפעם האחרונה (בשניות) שבה אפשר לקבוע פגישה במשבצת הזו. חותמת הזמן הזו צריכה להיות לפני startSec של משבצת הזמן כדי שהיא תכובד (אם המשתמשים צריכים להיות מסוגלים להזמין אחרי שעת ההתחלה, צריך להשתמש ב-SchedulingRules.min_booking_before_end_time ברמת השירות). אם המאפיין הזה מופיע, הוא יבטל את כל מה שצוין ב-min_booking_buffer של SchedulingRules בשירות המתאים.
firstBookableSec

string (int64 format)

הפעם הראשונה (בשניות) שבה אפשר לקבוע פגישה במשבצת זמן זו. חותמת הזמן הזו צריכה להיות לפני startSec של משבצת הזמן, או לפני lastBookableSec אם צוין.
lastOnlineCancellableSec

string (int64 format)

אם הערך מוגדר, זהו הזמן האחרון (בשניות מאז ראשית זמן יוניקס) שבו אפשר לבטל את משבצת הפגישה הספציפית הזו דרך 'Google הזמנת מקומות'. השדה הזה יבטל את כל כללי הביטול ברמת השירות. (אופציונלי)

ConfirmationMode

מצבי האישור שבהם נעשה שימוש כשמזמינים זמינויות.

טיפוסים בני מנייה (enum)
CONFIRMATION_MODE_UNSPECIFIED לא צוין מצב האישור. האישור יתבצע באופן סינכרוני.
CONFIRMATION_MODE_SYNCHRONOUS הזמנות שמתבצעות כשהזמינות הזו מוצגת יאושרו באופן סינכרוני.
CONFIRMATION_MODE_ASYNCHRONOUS האישור של הזמנות לזמינות הזו יתבצע באופן אסינכרוני.

LinkoutRequiredReason

הסיבה לכך שמשבצת מסוימת כוללת חוויית מעבר לאתר אחר.

טיפוסים בני מנייה (enum)
LINKOUT_REQUIRED_REASON_UNSPECIFIED ערך ברירת המחדל: לא לשימוש, שווה לערך unknown.
PAYMENT_REQUIRED כדי להזמין את המשבצת צריך לשלם בפלטפורמה של השותף.

Methods

replace

 מחליפה את Availability של Service קיים של מוכר שמנוהל על ידי האגרגטור שצוין, ומחזירה אותו.