מבוא

ה-Partner API של Performance Hub מאפשר לפלטפורמות שותפים חיצוניות להשתלב בצורה חלקה במודולי הליבה של Performance Hub. ה-API תומך בראייה ממוחשבת, בניתוח נתונים, ברישום גישה של חברים ובתובנות על מתקנים.

פורמט הבקשה

ה-API מקבל גופי בקשה בקידוד JSON ומחזיר תגובות בקידוד JSON.

הגבלת קצב

כדי להבטיח שימוש הוגן ויציבות מערכת, חשבונות Partner API מתחילים עם מגבלות ברירת מחדל:

5 בקשות לשנייה לכל נקודת קצה
מומלץ: 1000 פריטים לכל היותר בכל בקשת אצווה, לביצועים מיטביים
10MB לכל היותר לגודל המטען

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

כתובת URL בסיסית

https://partner-api.performancehub.co/partner/v1/

אימות

הגישה ל-Partner API מחייבת אימות באמצעות מפתחות API סודיים. צרו ונהלו את המפתחות שלכם דרך ה-Partner Console.

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

טפלו במפתחות ה-API שלכם בזהירות — הם מעניקים גישה מלאה לחשבון שלכם! לעולם אל תחשפו מפתחות אלה במאגרים ציבוריים, ביישומים בצד הלקוח או בכל מקום שבו הם עלולים להיפרץ.

אמתו בקשות באמצעות HTTP Basic Auth על ידי העברת מפתח ה-API שלכם כשם המשתמש. השאירו את הסיסמה ריקה.

ה-API מקבל רק חיבורי HTTPS מאובטחים. בקשות HTTP רגילות נדחות, וכך גם כל בקשה שחסרים בה פרטי הזדהות תקינים.

בקשה לדוגמה

curl https://partner-api.performancehub.co/partner/v1/organisations \
  -u sk_live_YOUR_PARTNER_SECRET_KEY:
# The colon prevents curl from asking for a password.

אימות המפתח הסודי

curl https://partner-api.performancehub.co/partner/v1/auth/ping \
  -u sk_live_YOUR_PARTNER_SECRET_KEY:
# Returns { "message": "You are successfully authorised as <PartnerName>" }

רשימת בדיקה לעלייה לאוויר

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

הגדרת ה-Partner Console

פרופיל השותף שלכם מלא.
כתובת ה-URL של הלוגו, האתר, הקטגוריה והתיאור מדויקים.
שיטת קישור הנתונים שלכם מוגדרת: Direct Link או Linking Identifier.
הקישור למתקנים נבדק עם מתקן אמיתי אחד לפחות.
נעשה שימוש בסוג המפתח הנכון:
- Dryrun לבדיקות כתיבה שאינן הרסניות.
- Read-only לצריכת נתונים בטוחה.
- Live רק כשאתם מוכנים להשפיע על נתוני הייצור.

אימות וניהול מפתחות

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

אימות נתונים

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

בדיקת נקודות קצה

לפני ההשקה, בדקו כל נקודת קצה שהאינטגרציה שלכם תלויה בה:

אפשר לקרוא ארגונים ומתקנים.
אפשר לשמור ולעדכן חברים.
תוכניות חברות, אזורי גישה ושעות גישה מסתנכרנים כראוי.
צ׳ק-אינים מתקבלים ואפשר להצליב אותם חזרה מול המערכת שלכם.
תמונות מצב של דוחות משתמשות בתקופת הדיווח ובמדדים הצפויים.
תהליכי Door/Gate Controller נבדקו על חומרה אמיתית, במקרים הרלוונטיים.

מוכנות ל-Access Time Windows

אם האינטגרציה מספקת Access Time Windows:

דוגמאות מוחלטות ושבועיות עוברות את רשימת הבדיקה להסמכת יצרנים.
ערכי epoch הם מספרים שלמים של שניות Unix ללא מירכאות; גבולות [from, to) מדויקים נבדקו.
ברירות המחדל של UTC, אזורי הזמן המותאמים אישית של IANA שבהם האינטגרציה משתמשת ומעברי שעון קיץ רלוונטיים אומתו.
זרם גרסאות עמיד ומונוטוני אחד לכל חבר/מקור מתאם עדכונים מצטברים, התאמות וניסיונות חוזרים.
המפעילים מבינים את ההתנהגות במקרים של השמטה, החלפה מלאה, אידמפוטנטיות, התנגשות, נתונים ישנים ו-[] מפורש.
לכל scope_key, כולל default, יש מיפוי מאושר ב-Performance Hub; נבדק שמפתחות לא מוכרים גורמים לסירוב גישה.
קצב הרענון הצפוי של האינטגרציה, הגיל המרבי של נתוני המקור, ההתנהגות כשהמקור אינו עדכני וההתראות מוגדרים.
הוכח שכשל בשליפה ממערכת המקור אינו שולח תמונת מצב ריקה או חלקית.
התכנסות זרם ה-stage, ביטול/שלילה וגבולות ההתחלה והסיום בדלת הפיזית עומדים ביעדים שסוכמו.
כללים רגילים והרשאות קבועות אומתו כנתיבי גיבוי, וחלונות אינם יכולים לעקוף השבתת משתמש, blockAllAccess, תחזוקה או גידור גאוגרפי.

מוכנות לבקרת גישה

באינטגרציות של בקרת גישה:

המערכת שלכם מקבלת את החלטת הגישה לפני הקריאה ל-Performance Hub.
האינטגרציה מטפלת ב-device_offline, ב-maintenance_mode_active וב-unlock_confirmation_timeout.
המפעילים מבינים שזמן קצוב שפג פירושו שהפתיחה לא אושרה.
היומנים שלכם שומרים את ה-event_id וה-command_id שהוחזרו.
יש לכם תהליך גיבוי ידני לצוות המתקן.

טיפול בשגיאות וניסיונות חוזרים

תגובות 400, 401, 403, 404, 409 ו-422 מוצגות למפעילים או לצוותי התמיכה, במקום לנסות אותן שוב באופן עיוור.
תגובות 429, 500, 502, 503 ו-504 משתמשות בלוגיקת ניסיון חוזר מוגבלת עם השהיה.
כשלים חוזרים יוצרים התראה במערכת שלכם.
האינטגרציה לעולם אינה משמיטה רשומות שנכשלו בשקט.

יכולת מעקב

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

השקה בסביבת הייצור

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

לאחר שבדיקות אלה הושלמו, האינטגרציה שהגדרתם תופיע במדריך השותפים של Performance Hub בתוך פלטפורמת הליבה של Performance Hub.

שיטות מומלצות

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

זיהוי מתקנים בעקביות

בחרו בשיטת הקישור שהוגדרה לחשבון השותף שלכם והשתמשו בה בעקביות:

Direct Link - השתמשו ב-facility_id של Performance Hub שמוחזר מנקודת הקצה של המתקנים.
Linking Identifier - השתמשו במזהה המיקום שלכם, כגון מזהה סניף, קוד מיקום או מספר חנות.

אל תשלחו את שני המזהים באותה בקשה. Performance Hub מפענח בקשות לפי שיטת הקישור שהוגדרה לחשבון השותף שלכם.

להנחיות הגדרה, ראו שיטות קישור של שותפים.

כתיבה באצוות בזהירות

ה-Partner API מקבל גופי בקשה בפורמט JSON ומתוכנן לתהליכי סנכרון מבוססי אצוות, במקומות שבהם הדבר מתועד. שמרו על אצוות מוגבלות בגודלן וניתנות לשליחה חוזרת.

הנחיות ברירת מחדל:

השתמשו בעד 1000 פריטים בכל בקשת אצווה לביצועים מיטביים.
שמרו על מטענים מתחת ל-10MB.
הישארו בגבול של 5 בקשות לשנייה לכל נקודת קצה.

מגבלות הקצב ניתנות לשינוי, ומנהל חשבון השותף שלכם ב-Performance Hub יכול להגדיר אותן לפי כל מקרה לגופו. אם אתם צופים ייבוא בנפח גבוה, תעבורת השקה או השלמה לאחור של נתוני דוחות, סכמו על התפוקה הנדרשת לפני חלון השינויים.

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

ניסיונות חוזרים בבטחה

השתמשו בהשהיה מעריכית (exponential backoff) עבור כשלים חולפים כגון 429, 500, 502, 503 ו-504.

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

נסו שוב לאחר שנייה אחת.
נסו שוב לאחר 2 שניות.
נסו שוב לאחר 4 שניות.
עצרו ושלחו התראה אם הפעולה עדיין נכשלת.

בכשלי אימות נתונים כגון 400 או 422, תקנו את הבקשה לפני ניסיון חוזר.

שימוש באידמפוטנטיות במקומות שבהם היא נתמכת

נקודת הקצה של פתיחת Door/Gate Controller תומכת בפרמטר אופציונלי idempotency_key. שימוש חוזר באותו מפתח עבור אותם שותף, מתקן ודלת מחזיר את התוצאה הקיימת, כשיש כזו.

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

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

שמירה על נתוני מקור נקיים

שלחו ערכים יציבים ומנורמלים בכל מקום אפשרי:

השתמשו במזהי חברים, תוכניות, מתקנים וצ׳ק-אינים עקביים ממערכת המקור שלכם.
השתמשו בחותמות זמן בפורמט ISO 8601 לתאריכים ולשעות.
שלחו מספרי טלפון בפורמט בינלאומי, כשהם זמינים.
שלחו מטבעות באמצעות השדות המתועדים לכל נקודת קצה.
הימנעו מהעמסת שדות טקסט חופשי בנתונים ששייכים לשדות מובנים.

תכנון לסנכרון מצטבר ולסנכרון מלא

רוב אינטגרציות השותפים צריכות את שניהם:

סנכרון מצטבר לשינויים היומיומיים.
סנכרון התאמה מלא לתיקון אירועים שהוחמצו, ייבוא נתונים היסטוריים או סטייה בנתונים.

האינטגרציה שלכם צריכה להיות מסוגלת לשלוח מחדש את המצב הנוכחי של חבר, תוכנית חברות או תמונת מצב של דוח, בלי להיות תלויה בהצלחה של בקשה קודמת.

פרסום Access Time Windows בבטחה

התייחסו לערך access_time_windows של כל חבר כאל תמונת מצב שלמה, עם גרסאות עצמאיות:

תאמו זרם אחד של access_time_windows_revision שעולה באופן מונוטוני בין תהליכי העבודה המצטברים לבין תהליכי ההתאמה.
שלחו שוב מסירה שתוצאתה לא ודאית או שנכשלה באופן חולף, עם אותה גרסה ואותו מטען מנורמל.
השמיטו את access_time_windows כשאינכם מעדכנים אותו.
שלחו [] רק לאחר ששליפה מוצלחת ממקור מוסמך מוכיחה שלא נותרו חלונות. לעולם אל תהפכו זמן קצוב שפג במערכת המקור, תוצאה חלקית או כשל בניתוח לשלילת גישה.
שמרו על external_id ו-scope_key יציבים, ואשרו כל מיפוי של טווח לפני המעבר לסביבת הייצור.
עקבו אחר גיל נתוני המקור ביחס למדיניות העדכניות שסוכמה לאותה אינטגרציה.

למידע על תמונות מצב שלמות, אזורי זמן, שעון קיץ, ביטול ווקטורי בדיקה, ראו את המדריך המוסמך ליצרני Access Time Windows.

התייחסות לבקרת גישה כקריטית לבטיחות

בפתיחות של Door/Gate Controller:

המערכת שלכם חייבת להחליט אם מותר לאדם להיכנס לפני הקריאה ל-Performance Hub.
Performance Hub מחזיר 200 רק לאחר שהבקר שבאתר מאשר שהממסר נפתח פיזית.
רוב האישורים מתקבלים תוך 3-5 שניות.
זמן קצוב שפג הוא פתיחה שנכשלה באופן מפורש, ולא הצלחה ברקע.
נסו שוב רק בהתאם לכללי הגישה והבטיחות שלכם.

תמיד תעדו את ה-event_id וה-command_id שמוחזרים מנקודת הקצה של הפתיחה.

ניטור האינטגרציה שלכם

השתמשו ביומני הבקשות של ה-Partner Console במהלך הפיתוח וההשקה. בסביבת הייצור, נהלו גם יומנים משלכם עם:

חותמת הזמן של הבקשה.
נקודת הקצה.
מזהה רשומת המקור.
מזהה המתקן.
קוד סטטוס ה-HTTP.
גוף התגובה או הודעת השגיאה של Performance Hub.

שדות אלה מאיצים מאוד את התמיכה ואת ההתאמה כשלקוח שואל מה קרה.

ארגונים

מייצג את הישות העסקית ברמה העליונה שמפעילה מתקן אחד או יותר המשולבים בפלטפורמת Performance Hub.

נקודות קצה

GET /partner/v1/organisations - List all organisations

האובייקט Organisation

מאפיינים

org_id string חובה

מזהה ייחודי של הארגון.
name string חובה

שם הארגון.

האובייקט Organisation

{
  "org_id": "00000000-0000-0000-0000-000000000050",
  "name": "Harbourside Group"
}

הצגת רשימת כל הארגונים

מחזיר רשימה של הארגונים הנגישים לחשבון השותף שלכם.

ערך מוחזר

מחזיר אובייקט JSON עם המאפיין data, שמכיל מערך של אובייקטי Organisation.

בקשה

curl https://partner-api.performancehub.co/partner/v1/organisations \
  -u sk_live_YOUR_PARTNER_SECRET_KEY:

תגובה

{
  "data": [
    {
      "org_id": "00000000-0000-0000-0000-000000000050",
      "name": "Harbourside Group"
    },
    {
      "org_id": "6ba7b811-9dad-11d1-80b4-00c04fd430c8",
      "name": "Wellness Studios Network"
    }
  ]
}

מתקנים

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

נקודות קצה

GET /partner/v1/facilities - List all facilities

אובייקט המתקן

מאפיינים

facility_id string חובה

מזהה ייחודי של המתקן.
org_id string חובה

מזהה ייחודי של ארגון האם.
name string חובה

שם המתקן.
brand string אופציונלי

שם המותג שבו המתקן משתמש.
website_url string אופציונלי

כתובת ה-URL של אתר המתקן.
place_data object אופציונלי

נתוני מיקום מ-Google Places API, הכוללים מדינה, כתובת מעוצבת, Google Place ID, מחוז ועיר.
social_links object אופציונלי

קישורים לרשתות החברתיות של המתקן.
timezone string אופציונלי

מזהה אזור זמן IANA (לדוגמה, "Australia/Sydney", "America/New_York").

אובייקט המתקן

{
  "facility_id": "550e8400-e29b-41d4-a716-446655440000",
  "org_id": "00000000-0000-0000-0000-000000000050",
  "name": "Harbourside Central",
  "brand": "Harbourside",
  "website_url": "https://example.com/central",
  "social_links": {
    "instagram": {
      "handle": "@harbourside.central"
    },
    "facebook": {
      "handle": "HarboursideCentral"
    }
  },
  "place_data": {
    "country": {
      "iso_code": "AU",
      "full_name": "Australia"
    },
    "formatted_address": "123 Main Street, Suite 100, Sydney NSW 2000, Australia",
    "google_place_id": "ChIJN1t_tDeuEmsRUsoyG83frY4",
    "province": {
      "abbreviation": "NSW",
      "full_name": "New South Wales"
    },
    "city": {
      "short_name": "Sydney",
      "full_name": "Sydney"
    }
  },
  "timezone": "Australia/Sydney"
}

הצגת רשימת כל המתקנים

מחזיר רשימה של המתקנים הנגישים לחשבון השותף שלכם.

ערך מוחזר

מחזיר אובייקט JSON עם המאפיין data, שמכיל מערך של אובייקטי מתקן.

בקשה

curl https://partner-api.performancehub.co/partner/v1/facilities \
  -u sk_live_YOUR_PARTNER_SECRET_KEY:

תגובה

{
  "data": [
    {
      "facility_id": "550e8400-e29b-41d4-a716-446655440000",
      "org_id": "00000000-0000-0000-0000-000000000050",
      "name": "Harbourside Central",
      "brand": "Harbourside",
      "website_url": "https://example.com/central",
      "place_data": {
        "country": {
          "iso_code": "AU",
          "full_name": "Australia"
        },
        "formatted_address": "123 Main Street, Sydney NSW 2000, Australia",
        "google_place_id": "ChIJN1t_tDeuEmsRUsoyG83frY4",
        "province": {
          "abbreviation": "NSW",
          "full_name": "New South Wales"
        },
        "city": {
          "short_name": "Sydney",
          "full_name": "Sydney"
        }
      },
      "timezone": "Australia/Sydney"
    }
  ]
}

תוכניות חברות

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

נקודות קצה

POST /partner/v1/membership-plans - Save a membership plan

האובייקט Membership Plan

מאפיינים

membership_plan_id string חובה

מזהה ייחודי של תוכנית החברות.
facility_id string אחד מהשנייםספקו את סוג מזהה המתקן שהוגדר לאינטגרציה שלכם: השתמשו ב-facility_id לאינטגרציות מסוג direct-link, או ב-linking_identifier לאינטגרציות מסוג linking-identifier. אל תשלחו את שניהם; ה-API משתמש בסוג המזהה שהוגדר לחשבון השותף שלכם ומתעלם מהסוג האחר. מידע נוסף

המזהה הייחודי של המתקן מ-Performance Hub.
linking_identifier string אחד מהשנייםספקו את סוג מזהה המתקן שהוגדר לאינטגרציה שלכם: השתמשו ב-facility_id לאינטגרציות מסוג direct-link, או ב-linking_identifier לאינטגרציות מסוג linking-identifier. אל תשלחו את שניהם; ה-API משתמש בסוג המזהה שהוגדר לחשבון השותף שלכם ומתעלם מהסוג האחר. מידע נוסף

ערך המזהה הייחודי שהשותף משתמש בו לכל מיקום (לדוגמה, "Branch ID", "Location Code", "Store Number"). מידע נוסף
name string חובה

שם התוכנית הקריא לבני אדם (לדוגמה, "Office tenant – business hours", "Student – term access", "Hotel guest", "10 Class Pack").
billing_cycle string אופציונלי

תדירות החיוב. אחד מהערכים weekly, fortnightly, monthly, annually או one_time.
price integer אופציונלי

העלות הבסיסית ביחידת המטבע הקטנה ביותר (סנטים עבור USD/AUD).
currency string אופציונלי

קוד מטבע לפי ISO 4217 (לדוגמה, "AUD", "USD").
description string אופציונלי

תיאור שיווקי או פנימי אופציונלי.
active_members integer אופציונלי

מספר החברים הפעילים שמשתמשים בתוכנית החברות הזו
is_recurring boolean אופציונלי

האם התוכנית מתחדשת אוטומטית.
is_trial boolean אופציונלי

האם זו הצעת ניסיון.
visible_to_public boolean אופציונלי

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

מספר הימים שבהם תוכנית החברות תקפה.
access_zones array אופציונלי

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

המספר המרבי של שיעורים מותרים (null ללא הגבלה).

האובייקט Membership Plan

דוגמה זו משתמשת ב-facility_id. באינטגרציה מסוג linking-identifier, שלחו במקום זאת "linking_identifier": "branch_downtown".

{
  "membership_plan_id": "plan_99999",
  "facility_id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Office tenant – business hours",
  "description": "Weekday access to the level 3 tenancy and the end-of-trip facilities",
  "billing_cycle": "monthly",
  "price": 8900,
  "currency": "AUD",
  "duration_days": 30,
  "is_recurring": true,
  "is_trial": false,
  "visible_to_public": false,
  "active_members": 245,
  "access_zones": [
    {
      "name": "Level 3 Tenancy",
      "description": "Lift lobby, offices and meeting rooms on level 3",
      "access_hours": {
        "mon": [["07:00", "19:00"]],
        "tue": [["07:00", "19:00"]],
        "wed": [["07:00", "19:00"]],
        "thu": [["07:00", "19:00"]],
        "fri": [["07:00", "19:00"]]
      }
    },
    {
      "name": "End-of-trip Facilities",
      "description": "Bike storage, lockers and showers",
      "access_hours": {
        "mon": [["06:00", "20:00"]],
        "tue": [["06:00", "20:00"]],
        "wed": [["06:00", "20:00"]],
        "thu": [["06:00", "20:00"]],
        "fri": [["06:00", "20:00"]]
      }
    }
  ],
  "class_limit": null
}

אזורי גישה

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

מבנה

כל אזור גישה כולל:

name string חובה

שם האזור (לדוגמה, "Level 3 Tenancy", "Library", "Guest Floors", "Main Gym Floor").
description string אופציונלי

תיאור של מה שכלול באזור הזה.
access_hours object אופציונלי

שעות גישה ספציפיות לאזור הזה. לפורמט טווחי הזמן, ראו שעות גישה.

דוגמה

בניין משרדים עם חדר כושר לדיירים שלו: גישה לשטח המושכר בשעות העבודה, ולחדר הכושר משעות הבוקר המוקדמות ועד שעות הערב המאוחרות.

{
  "access_zones": [
    {
      "name": "Level 3 Tenancy",
      "description": "Lift lobby, offices and meeting rooms on level 3",
      "access_hours": {
        "mon": [["07:00", "19:00"]],
        "tue": [["07:00", "19:00"]],
        "wed": [["07:00", "19:00"]],
        "thu": [["07:00", "19:00"]],
        "fri": [["07:00", "19:00"]]
      }
    },
    {
      "name": "Tenant Gym",
      "description": "Ground-floor gym and change rooms for building tenants",
      "access_hours": {
        "mon": [["05:00", "22:00"]],
        "tue": [["05:00", "22:00"]],
        "wed": [["05:00", "22:00"]],
        "thu": [["05:00", "22:00"]],
        "fri": [["05:00", "22:00"]],
        "sat": [["07:00", "18:00"]],
        "sun": [["07:00", "18:00"]]
      }
    }
  ]
}

שעות גישה

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

מבנה

{
  "mon": [["start_time", "end_time"]],
  "tue": [["start_time", "end_time"]],
  "wed": [["start_time", "end_time"]],
  "thu": [["start_time", "end_time"]],
  "fri": [["start_time", "end_time"]],
  "sat": [["start_time", "end_time"]],
  "sun": [["start_time", "end_time"]]
}

כל יום הוא מערך של טווחי זמן בפורמט HH:MM (שעון של 24 שעות). מערך ריק [] פירושו שאין גישה באותו יום. ימים שהושמטו מטופלים כמו מערך ריק.

תרחישי שימוש לדוגמה

דייר משרדים – שעות עבודה: גישה בשעות העבודה בימי חול בלבד.

{
  "access_hours": {
    "mon": [["07:00", "19:00"]],
    "tue": [["07:00", "19:00"]],
    "wed": [["07:00", "19:00"]],
    "thu": [["07:00", "19:00"]],
    "fri": [["07:00", "19:00"]]
  }
}

סטודנט – גישה בסמסטר: ספריית קמפוס שפתוחה בימי חול, עם הפסקה באמצע היום, ובשבת בבוקר.

{
  "access_hours": {
    "mon": [["08:00", "12:30"], ["13:30", "21:00"]],
    "tue": [["08:00", "12:30"], ["13:30", "21:00"]],
    "wed": [["08:00", "12:30"], ["13:30", "21:00"]],
    "thu": [["08:00", "12:30"], ["13:30", "21:00"]],
    "fri": [["08:00", "12:30"], ["13:30", "17:00"]],
    "sat": [["09:00", "13:00"]]
  }
}

חדר כושר – משכימי קום: גישה בבקרים בלבד בימי חול.

{
  "access_hours": {
    "mon": [["04:00", "12:00"]],
    "tue": [["04:00", "12:00"]],
    "wed": [["04:00", "12:00"]],
    "thu": [["04:00", "12:00"]],
    "fri": [["04:00", "12:00"]]
  }
}

אורח מלון – 24/7: גישה קבועה, תרחיש השימוש הנפוץ ביותר.

{
  "access_hours": {
    "mon": [["00:00", "23:59"]],
    "tue": [["00:00", "23:59"]],
    "wed": [["00:00", "23:59"]],
    "thu": [["00:00", "23:59"]],
    "fri": [["00:00", "23:59"]],
    "sat": [["00:00", "23:59"]],
    "sun": [["00:00", "23:59"]]
  }
}

דוגמה לפי אזור

תוכנית לאורחי מלון עם גישה מסביב לשעון לקומות האורחים ושעות קצרות יותר לבריכה:

{
  "access_zones": [
    {
      "name": "Guest Floors",
      "description": "Lifts and corridors on the guest room levels",
      "access_hours": {
        "mon": [["00:00", "23:59"]],
        "tue": [["00:00", "23:59"]],
        "wed": [["00:00", "23:59"]],
        "thu": [["00:00", "23:59"]],
        "fri": [["00:00", "23:59"]],
        "sat": [["00:00", "23:59"]],
        "sun": [["00:00", "23:59"]]
      }
    },
    {
      "name": "Swimming Pool",
      "description": "Access to the swimming pool and change rooms",
      "access_hours": {
        "mon": [["06:00", "20:00"]],
        "tue": [["06:00", "20:00"]],
        "wed": [["06:00", "20:00"]],
        "thu": [["06:00", "20:00"]],
        "fri": [["06:00", "20:00"]],
        "sat": [["08:00", "18:00"]],
        "sun": [["08:00", "18:00"]]
      }
    }
  ]
}

שמירת תוכנית חברות

יוצר או מעדכן רשומות של תוכניות חברות. ה-API קובע אם ליצור או לעדכן על סמך ה-membership_plan_id.

פרמטרים

membership_plans array חובה

מערך של אובייקטי Membership Plan לשמירה. מקסימום מומלץ: 1000 פריטים לבקשה לביצועים מיטביים. ה-API מחלק את הפריטים לאצוות לעיבוד באופן אוטומטי. כל פריט חייב לכלול את facility_id (חובה אם לא משתמשים ב-linking_identifier) או את linking_identifier (חובה אם לא משתמשים ב-facility_id).

ערך מוחזר

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

בקשה

דוגמה זו משתמשת ב-facility_id. באינטגרציה מסוג linking-identifier, שלחו במקום זאת "linking_identifier": "branch_downtown".

curl -X POST https://partner-api.performancehub.co/partner/v1/membership-plans \
  -u sk_live_YOUR_PARTNER_SECRET_KEY: \
  -H "Content-Type: application/json" \
  -d '{
    "membership_plans": [
      {
        "membership_plan_id": "plan_99999",
        "facility_id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "Student – term access",
        "description": "Library and student hub access for one teaching term",
        "billing_cycle": "one_time",
        "price": 4500,
        "currency": "AUD",
        "duration_days": 84,
        "is_recurring": false,
        "is_trial": false,
        "visible_to_public": true,
        "active_members": 245,
        "access_zones": [
          {
            "name": "Library",
            "description": "Reading rooms, study spaces and bookable rooms",
            "access_hours": {
              "mon": [["08:00", "21:00"]],
              "tue": [["08:00", "21:00"]],
              "wed": [["08:00", "21:00"]],
              "thu": [["08:00", "21:00"]],
              "fri": [["08:00", "17:00"]],
              "sat": [["09:00", "13:00"]]
            }
          },
          {
            "name": "Student Hub",
            "description": "Common room, kitchen and lockers",
            "access_hours": {
              "mon": [["07:00", "22:00"]],
              "tue": [["07:00", "22:00"]],
              "wed": [["07:00", "22:00"]],
              "thu": [["07:00", "22:00"]],
              "fri": [["07:00", "22:00"]]
            }
          }
        ],
        "class_limit": null
      }
    ]
  }'

תגובה

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

{
  "message": "Membership plan sync successful.",
  "metadata": {
    "success": 98,
    "skipped": 2,
    "skipped_items": [
      {
        "membership_plan_id": "plan_456",
        "facility_id": null,
        "reason": "Missing facility_id"
      }
    ]
  }
}

שדות המטא-נתונים:

success - מספר תוכניות החברות שעובדו בהצלחה
skipped - מספר התוכניות שדולגו (אם יש)
skipped_items - מערך של התוכניות שדולגו, עם הסיבות (אם יש)
dry-run - דגל בוליאני אם נעשה שימוש במפתח מסוג dryrun (אם רלוונטי)

חברים

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

פעולות upsert של חברים יכולות לכלול גם תמונת מצב שלמה של access_time_windows עם גרסה, שמכילה גישה מוחלטת וגישה שבועית חוזרת. קראו את Access Time Windows לפני הפקת שדות אלה. אלה הרשאות שמתווספות לקיימות, והן אינן מחליפות את הכללים הרגילים של המתקן או את ההרשאות הקבועות שלו.

נקודות קצה

POST /partner/v1/members - Save a member

האובייקט Member

מאפיינים

member_id string חובה

מזהה ייחודי של החבר.
facility_id string אחד מהשנייםספקו את סוג מזהה המתקן שהוגדר לאינטגרציה שלכם: השתמשו ב-facility_id לאינטגרציות מסוג direct-link, או ב-linking_identifier לאינטגרציות מסוג linking-identifier. אל תשלחו את שניהם; ה-API משתמש בסוג המזהה שהוגדר לחשבון השותף שלכם ומתעלם מהסוג האחר. מידע נוסף

המזהה הייחודי של המתקן מ-Performance Hub.
linking_identifier string אחד מהשנייםספקו את סוג מזהה המתקן שהוגדר לאינטגרציה שלכם: השתמשו ב-facility_id לאינטגרציות מסוג direct-link, או ב-linking_identifier לאינטגרציות מסוג linking-identifier. אל תשלחו את שניהם; ה-API משתמש בסוג המזהה שהוגדר לחשבון השותף שלכם ומתעלם מהסוג האחר. מידע נוסף

ערך המזהה הייחודי שהשותף משתמש בו לכל מיקום (לדוגמה, "Branch ID", "Location Code", "Store Number"). מידע נוסף
first_name string חובה

השם הפרטי של החבר.
last_name string חובה

שם המשפחה של החבר.
email string אופציונלי

כתובת דוא"ל.
mobile_phone string אופציונלי

מספר טלפון נייד בפורמט E.123 (לדוגמה, "+1 415 555 2671").
address object אופציונלי

אובייקט כתובת פיזית עם המאפיינים הבאים:
- address_line_1 (string) - כתובת הרחוב הראשית
- address_line_2 (string, optional) - שורת כתובת משנית
- city (string) - שם העיר
- state (string) - קוד המדינה/המחוז
- postal_code (string) - מיקוד
- country (string) - קוד מדינה לפי ISO 3166-1 alpha-2 (לדוגמה, "AU", "US")
- country_name (string, optional) - שם המדינה המלא
date_of_birth string אופציונלי

תאריך לידה בפורמט YYYY-MM-DD.
gender string אופציונלי

אחד מהערכים male, female, non_binary, prefer_not_to_say או unknown.
type string אופציונלי

סוג החבר (לדוגמה, staff, member, prospect).
tags array אופציונלי

מחרוזות או טקסטים קצרים לסיווג וזיהוי של חברים מסוימים (לדוגמה, ["vip", "personal-training", "student"]).
membership_status string אופציונלי

סטטוס החברות הנוכחי (לדוגמה, active, expired, on_hold).
membership_plans array אופציונלי

מערך של תוכניות החברות המשויכות לחבר.
profile_picture string אופציונלי

תמונת פרופיל בקידוד Base64 (אופציונלי).
created string אופציונלי

חותמת זמן בפורמט ISO 8601 של מועד יצירת החבר.
updated string אופציונלי

חותמת זמן בפורמט ISO 8601 של מועד העדכון האחרון של החבר.
access_time_windows array אופציונלי

תמונת מצב מלאה, ששייכת למקור, של Access Time Windows מוחלטים ו/או שבועיים חוזרים. השמיטו את השדה כדי להשאיר את תמונת המצב ללא שינוי; שלחו מערך ריק עם גרסה חדשה יותר כדי לשלול אותה. למבנים, לאימות, למיפוי הטווחים ולסמנטיקת ההחלפה, ראו Access Time Windows.
access_time_windows_revision integer חובה עם access_time_windows

מספר שלם אי-שלילי, בטוח לשימוש ב-JSON, שעולה באופן מונוטוני בזרם של החבר/המקור הזה. חובה בכל פעם ש-access_time_windows קיים.

האובייקט Member

{
  "member_id": "member_11111",
  "facility_id": "550e8400-e29b-41d4-a716-446655440000",
  // "linking_identifier": "branch_downtown",  // If using linking identifier
  "first_name": "John",
  "last_name": "Smith",
  "email": "john.smith@example.com",
  "mobile_phone": "+61 412 345 678",
  "date_of_birth": "1985-06-15",
  "gender": "male",
  "type": "member",
  "tags": ["vip", "personal-training"],
  "profile_picture": "/9j/4AAQSkZJRgABAQAAAQ...",
  "membership_status": "current",
  "created": "2024-01-15T10:30:00Z",
  "updated": "2024-01-20T14:45:00Z",
  "access_time_windows_revision": 1842,
  "access_time_windows": [
    {
      "external_id": "access-4b1782",
      "kind": "absolute",
      "from": 1792053000,
      "to": 1792058400,
      "timezone": "Australia/Perth",
      "scope_key": "after_hours_entry",
      "label": "Temporary site access"
    }
  ],
  "address": {
    "address_line_1": "456 Bourke Street",
    "address_line_2": "Apt 12",
    "city": "Melbourne",
    "state": "VIC",
    "postal_code": "3000",
    "country": "AU",
    "country_name": "Australia"
  },
  "membership_plans": [
    {
      "membership_plan_id": "plan_99999",
      "name": "Unlimited Monthly",
      "start_date": "2024-01-01T00:00:00Z",
      "status": "current",
      "is_current": true,
      "end_date": null
    }
  ]
}

חלונות זמן גישה

Access Time Windows מאפשרים לחבר שמגיע משותף (Partner Member) לשאת גישה זמנית או חוזרת שסופקה על ידי מערכת חיצונית. דף זה הוא המדריך המוסמך ליצרנים עבור access_time_windows ו-access_time_windows_revision.

Access Time Windows הם הרשאות שמתווספות לקיימות ומתירות בלבד. חלון פעיל יכול להתיר גישה, אבל חלון לא פעיל, שפג תוקפו, שאינו עדכני או שאינו ממופה אינו שולל גישה שכלל רגיל או הרשאה קבועה כבר מתירים. השבתת משתמש, חסימת דלת מפורשת, מצב תחזוקה, גידור גאוגרפי, מגבלות קצב וזמינות הבקר עדיין חלים.

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

שדות תמונת המצב של החבר

access_time_windows array אופציונלי

תמונת המצב המלאה של Access Time Windows עבור החבר ומקור השותף הזה. תמונת מצב יכולה לשלב חלונות absolute ו-weekly. השמיטו את השדה כדי להשאיר את תמונת המצב השמורה ללא שינוי; שלחו [] כדי לשלול כל חלון ששייך למקור הזה.
access_time_windows_revision integer חובה עם access_time_windows

מספר שלם אי-שלילי, בטוח לשימוש ב-JSON, שעולה באופן מונוטוני בזרם הגרסאות של החבר/המקור הזה. הוא חובה בכל פעם ש-access_time_windows קיים, ואסור שיעלה על 9007199254740991.

כל תמונת מצב מקבלת 50 חלונות לכל היותר. external_id, scope_key ו-label מקבלים 120 תווים לכל היותר. חלונות מוחלטים יכולים להשתרע על 90 ימים לכל היותר. יום שבועי מקבל שמונה מקטעים לא חופפים לכל היותר. נתונים לא תקינים נדחים, ולא נקטעים או מנוחשים.

מבני החלונות

חלון מוחלט מזהה מרווח מדויק אחד:

בקשה מלאה משולבת

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

כללי זמן וגבולות

from, to, active_from ו-active_until הם מספרים שלמים של שניות Unix ב-JSON, שמזהים נקודות זמן של UTC:

שלחו מספר שלם של JSON ללא מירכאות. מחרוזות מספריות, מספרי נקודה צפה, מחרוזות RFC 3339 ואלפיות שנייה של Unix נדחים.
כל מרווח הוא חצי-פתוח: [from, to). הגישה יכולה להתחיל בדיוק ב-from; היא כבר אינה פעילה בדיוק ב-to.
from חייב להיות קטן מ-to. כששני הגבולות השבועיים קיימים, active_from חייב להיות קטן מ-active_until.
אל תגזרו ערכי epoch מתאריך/שעה מקומיים ללא אזור זמן. תחילה המירו את זמן המקור לנקודת זמן של UTC, לאחר מכן חלקו את אלפיות השנייה של Unix ב-1000 וודאו שהתוצאה היא מספר שלם.

אזורי זמן ושעון קיץ

timezone חייב להיות אזור זמן IANA תקין, כגון UTC, Australia/Perth או America/New_York. ברירת המחדל היא UTC כשהוא מושמט.

חלונות מוחלטים: from ו-to כבר מזהים נקודות זמן מדויקות של UTC. timezone הוא מטא-נתונים לתצוגה ולביקורת בלבד; שינוי שלו לעולם אינו מזיז אף אחת מנקודות הזמן.
חלונות שבועיים: timezone מגדיר את שעון הקיר המקומי ואת כללי שעון הקיץ שמשמשים להערכת access_hours. אל תמירו מראש מקטעים שבועיים ל-UTC.
במעבר לשעון קיץ, שעה מקומית שאזור הזמן מדלג עליה לעולם אינה מתרחשת.
במעבר משעון קיץ, שתי נקודות הזמן האמיתיות שבהן חוזרת אותה שעה מקומית תואמות למקטע השבועי.
active_from ו-active_until נשארים נקודות זמן של UTC גם כשחלון שבועי משתמש באזור זמן שאינו UTC.

access_hours משתמש בערכים באותיות קטנות מ-sun עד sat. כל ערך הוא מערך של צמדי [start, end] בפורמט HH:mm של 24 שעות, עם אפסים מובילים. המקטעים חייבים להיות לא ריקים, מסודרים ולא חופפים. end אינו כלול. מקטע אינו יכול לחצות את חצות; פצלו מרווח לילי מהמקור למקטע מאוחר ביום הראשון ולמקטע מוקדם ביום שלמחרת.

מזהים יציבים ומיפוי טווחים

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

scope_key הוא יעד הגישה הלוגי והיציב שלכם. ברירת המחדל שלו היא default. מנהל מתקן ממפה כל מפתח מותר ליעדים ב-Performance Hub: כל המתקן, דלת או טווח גישה:

תמונות מצב מלאות וגרסאות

התייחסו לשני השדות כאל מחיצה עם ניהול גרסאות נפרד בתוך פעולת ה-upsert של החבר:

קלט	תוצאה
`access_time_windows` מושמט	תמונת המצב הקיימת נשארת ללא שינוי; אין צורך בגרסה
קיים עם גרסה חדשה יותר	כל תמונת המצב השמורה של החבר/המקור הזה מוחלפת
אותה גרסה ואותו מטען מנורמל	שליחה חוזרת אידמפוטנטית; אין שינוי בתמונת המצב
אותה גרסה ומטען מנורמל שונה	התנגשות; הקצו גרסה חדשה לאחר ביצוע התאמה
גרסה ישנה יותר	תמונת המצב הישנה מדולגת; היא אינה יכולה לדרוס מצב חדש יותר
`access_time_windows: []` עם גרסה חדשה יותר	שולל במפורש את כל החלונות ששייכים למקור

תמונת מצב היא שלמה, ולא תיקון חלקי. אם בגרסה 1842 יש חלונות A ו-B, אז גרסה 1843 שמכילה רק את B מסירה את A.

נהלו זרם גרסאות מתואם אחד לכל שותף/חבר, בין תהליכי webhook, תשאול, שליחה חוזרת והתאמה מלאה. עדיף להשתמש ברצף עמיד במסד נתונים. אפשר להשתמש בערך של אלפיות שנייה של Unix כגרסה רק כשכל הכותבים מתואמים ומבטיחים סדר וייחודיות מוחלטים; זהו ערך גרסה, ולא שדה epoch.

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

ביטול, פקיעת תוקף וכשלים במערכת המקור

ביטול חלון אחד: שלפו בהצלחה את המצב המוסמך מהמקור, הסירו את החלון הזה ושלחו את תמונת המצב המלאה שנותרה עם גרסה חדשה יותר.
ביטול כל החלונות: שלחו access_time_windows: [] עם גרסה חדשה יותר.
מתן אפשרות לחלון מוחלט לפוג: הוא מפסיק להתיר גישה ב-to; שלחו התאמה מאוחרת יותר ללא הרשומה שפג תוקפה כדי לשמור על תמונות מצב נקיות.
סיום חלון שבועי: הסירו אותו בתמונת מצב חדשה יותר, או השתמשו ב-active_until כשלמקור יש נקודת סיום ידועה.
השליפה מהמקור נכשלת או אינה שלמה: אל תשלחו [] ואל תפרסמו תמונת מצב חלקית. שלחו התראה ונסו שוב את השליפה. הפיכת כשל במערכת המקור לתמונת מצב ריקה היא שלילת גישה לא מכוונת.
בקשת Partner API נכשלת באימות: תקנו את הנתונים ושלחו גרסה חדשה יותר רק אם תמונת המצב המנורמלת משתנה. נסו שוב כשלים חולפים עם הגרסה המקורית.

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

אלגוריתם היצרן

השתמשו בתהליך העבודה הזה, הבלתי תלוי בשפת תכנות, בכל עדכון של חבר:

רשימת בדיקה להסמכה

השלימו את הבדיקות האלה במתקן stage באמצעות מיפוי ה-scope_key הסופי:

חלון מוחלט מתקבל כשאזור הזמן מושמט, ומוערך כ-UTC.
חלון מוחלט עם אזור זמן IANA מותאם אישית שומר על אותן נקודות זמן של from/to.
חלון שבועי עם אזור זמן IANA מותאם אישית עוקב אחר שעון הקיר המקומי במעברים לשעון קיץ וממנו.
תמונת מצב משולבת של חלונות מוחלטים/שבועיים מחליפה את תמונת המצב הקודמת לחלוטין.
הגישה מתחילה בדיוק ב-from ומסתיימת בדיוק ב-to; גם סופי המקטעים השבועיים אינם כלולים.
עדכון שעות תחת אותו external_id עם גרסה חדשה יותר נכנס לתוקף.
השמטת access_time_windows משנה שדות אחרים של החבר בלי לשנות את החלונות.
שליחה חוזרת של אותה גרסה/אותו מטען היא אידמפוטנטית.
אותה גרסה/מטען שונה מחזירה התנגשות ואינה משנה את תמונת המצב.
גרסה ישנה יותר שמגיעה שלא לפי הסדר מדווחת כלא עדכנית ואינה יכולה להחזיר את המצב לאחור.
[] חדש יותר שולל את החלונות ששייכים למקור; כשל בשליפה ממערכת המקור אינו שולח דבר.
scope_key לא מוכר או לא ממופה אינו מעניק גישה, ויוצר אזהרה שגלויה למפעילים.
התראות על גיל נתוני המקור ומדיניות המקור הלא עדכני שהוגדרה פועלות בסף שסוכם.
נתיבי ה-webhook וההתאמה המלאה מתכנסים לאותה תמונת מצב ולאותו סדר גרסאות.
המסירה בזרם מגיעה ל-Door & Gate Access בתוך היעד שסוכם.
חלון פעיל יכול להתיר גישה לדלת הפיזית הממופה, אבל אינו יכול לעקוף השבתת משתמש, blockAllAccess, תחזוקה או גידור גאוגרפי.
לפני חלון, מחוצה לו ואחריו, כללים רגילים והרשאות קבועות עדיין מתירים גישה למשתמשים שעומדים בתנאים בדרך אחרת.

{
  "external_id": "access-4b1782",
  "kind": "absolute",
  "from": 1792053000,
  "to": 1792058400,
  "timezone": "Australia/Perth",
  "scope_key": "after_hours_entry",
  "label": "Temporary site access"
}

שדות החובה הם external_id, kind, from ו-to. timezone, scope_key ו-label הם אופציונליים.

חלון שבועי מזהה מרווחים חוזרים לפי שעון הקיר המקומי, ובאופן אופציונלי מוגבל בנקודות זמן של UTC:

{
  "external_id": "weekly-early-access",
  "kind": "weekly",
  "timezone": "America/New_York",
  "access_hours": {
    "sun": [],
    "mon": [["06:00", "08:30"]],
    "tue": [["06:00", "08:30"]],
    "wed": [["06:00", "08:30"]],
    "thu": [["06:00", "08:30"]],
    "fri": [["06:00", "08:30"]],
    "sat": []
  },
  "active_from": 1790812800,
  "active_until": 1796083200,
  "scope_key": "main_entry",
  "label": "Weekday early access"
}

שדות החובה הם external_id, kind ו-access_hours. timezone, active_from, active_until, scope_key ו-label הם אופציונליים.

curl -X POST https://partner-api.performancehub.co/partner/v1/members \
  -u sk_live_YOUR_PARTNER_SECRET_KEY: \
  -H "Content-Type: application/json" \
  -d '{
    "members": [
      {
        "member_id": "member_11111",
        "facility_id": "550e8400-e29b-41d4-a716-446655440000",
        "first_name": "John",
        "last_name": "Smith",
        "access_time_windows_revision": 1842,
        "access_time_windows": [
          {
            "external_id": "access-4b1782",
            "kind": "absolute",
            "from": 1792053000,
            "to": 1792058400,
            "timezone": "Australia/Perth",
            "scope_key": "after_hours_entry",
            "label": "Temporary site access"
          },
          {
            "external_id": "weekly-early-access",
            "kind": "weekly",
            "timezone": "America/New_York",
            "access_hours": {
              "sun": [],
              "mon": [["06:00", "08:30"]],
              "tue": [["06:00", "08:30"]],
              "wed": [["06:00", "08:30"]],
              "thu": [["06:00", "08:30"]],
              "fri": [["06:00", "08:30"]],
              "sat": []
            },
            "active_from": 1790812800,
            "active_until": 1796083200,
            "scope_key": "main_entry",
            "label": "Weekday early access"
          }
        ]
      }
    ]
  }'

השתמשו ב-facility_id או ב-linking_identifier בהתאם לשיטת הקישור שהגדרתם. אל תשלחו את שניהם.

המרת epoch

2026-10-15T08:30:00Z מומר ל-1792053000:

UTC instant                 Unix milliseconds   Unix seconds sent
2026-10-15T08:30:00Z        1792053000000        1792053000

המרה בלתי תלויה בשפת תכנות:

instant = parse_source_timestamp_with_explicit_zone(source_timestamp)
milliseconds = instant.to_unix_milliseconds()
assert milliseconds modulo 1000 equals 0
seconds = milliseconds / 1000
assert seconds is a JSON-safe nonnegative integer

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

Partner scope_key           Performance Hub mapping
default                     Facility's configured default target
main_entry                  Access Scope "Main entrances"
after_hours_entry           Doors approved for after-hours entry

שותפים אינם שולחים בתוך חלון מזהים של מתקן, דלת או טווח גישה של Performance Hub. scope_key לא מוכר, מושבת או לא ממופה גורם לכך שהחלון הזה אינו מעניק גישה; הוא אינו מרחיב את הגישה. סכמו על המיפויים ובדקו אותם לפני ההשקה.

function publish_member(member_key):
    source_result = fetch_authoritative_access_state(member_key)

    if source_result.failed or source_result.incomplete:
        record_failure(member_key)
        schedule_retry(member_key)
        return without sending access_time_windows

    windows = []
    for source_window in source_result.current_windows:
        if source_window.is_absolute:
            windows.append({
                external_id: stable_window_id(source_window),
                kind: "absolute",
                from: to_integer_unix_seconds(source_window.start_instant),
                to: to_integer_unix_seconds(source_window.end_instant),
                timezone: source_window.display_timezone or "UTC",
                scope_key: stable_scope_key(source_window) or "default",
                label: safe_label(source_window)
            })
        else:
            windows.append({
                external_id: stable_window_id(source_window),
                kind: "weekly",
                timezone: valid_iana_zone(source_window.timezone) or "UTC",
                access_hours: split_validate_and_sort_weekly_blocks(source_window),
                active_from: optional_integer_unix_seconds(source_window.active_start),
                active_until: optional_integer_unix_seconds(source_window.active_end),
                scope_key: stable_scope_key(source_window) or "default",
                label: safe_label(source_window)
            })

    normalized_snapshot = validate_sort_and_deduplicate(windows)
    revision = next_durable_member_revision(member_key)
    request = member_upsert_with(normalized_snapshot, revision)
    persist_for_retry(member_key, request)

    response = post_request(request)
    if response.is_transient_or_unknown:
        retry_exact_request_with_same_revision(request)
    else if response.is_revision_conflict:
        reconcile_with_latest_committed_source_state(member_key)
    else if response.is_stale_skip:
        stop_replaying_this_revision_and_reconcile(member_key)

וקטורי בדיקה מינימליים

[
  {
    "name": "absolute-half-open",
    "window": {
      "external_id": "tv-absolute",
      "kind": "absolute",
      "from": 1792053000,
      "to": 1792058400
    },
    "expect": {
      "1792052999": "inactive",
      "1792053000": "active",
      "1792058399": "active",
      "1792058400": "inactive"
    }
  },
  {
    "name": "weekly-dst",
    "window": {
      "external_id": "tv-weekly-dst",
      "kind": "weekly",
      "timezone": "America/New_York",
      "access_hours": {
        "sun": [["01:00", "03:30"]],
        "mon": [],
        "tue": [],
        "wed": [],
        "thu": [],
        "fri": [],
        "sat": []
      }
    },
    "expect": "Evaluate local wall time: skipped times do not occur; both repeated 01:30 instants qualify."
  }
]

שלחו גם וקטורים שליליים עבור אלפיות שנייה של Unix, מחרוזות מספריות, מספרי נקודה צפה, אזורי IANA לא תקינים, from >= to, external_id כפול, מקטעים חופפים, מקטעים ליליים, יותר משמונה מקטעים ביום, יותר מ-50 חלונות ומפתחות טווח לא ממופים.

שמירת חבר

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

פרמטרים

members array חובה

מערך של אובייקטי Member לשמירה. מקסימום מומלץ: 1000 פריטים לבקשה לביצועים מיטביים. ה-API מחלק את הפריטים לאצוות לעיבוד באופן אוטומטי. כל פריט חייב לכלול את facility_id (חובה אם לא משתמשים ב-linking_identifier) או את linking_identifier (חובה אם לא משתמשים ב-facility_id).

כשחבר כולל access_time_windows, הוא חייב לכלול גם access_time_windows_revision. המערך הוא תמונת מצב מלאה של המקור, ולא תיקון חלקי. השמיטו אותו כדי לשמור על תמונת המצב הקיימת, או שלחו [] עם גרסה חדשה יותר כדי לשלול את כל החלונות ששייכים למקור. קראו את המדריך ל-Access Time Windows לפני הפעלת שדה זה.

ערך מוחזר

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

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

בקשה

curl -X POST https://partner-api.performancehub.co/partner/v1/members \
  -u sk_live_YOUR_PARTNER_SECRET_KEY: \
  -H "Content-Type: application/json" \
  -d '{
    "members": [
      {
        "member_id": "member_11111",
        "facility_id": "550e8400-e29b-41d4-a716-446655440000",
        // "linking_identifier": "branch_downtown",  // If using linking identifier
        "first_name": "John",
        "last_name": "Smith",
        "email": "john.smith@example.com",
        "mobile_phone": "+61 412 345 678",
        "date_of_birth": "1985-06-15",
        "gender": "male",
        "type": "member",
        "tags": ["vip", "personal-training"],
        "profile_picture": "/9j/4AAQSkZJRgABAQAAAQ...",
        "membership_status": "current",
        "created": "2024-01-15T10:30:00Z",
        "updated": "2024-01-20T14:45:00Z",
        "access_time_windows_revision": 1842,
        "access_time_windows": [
          {
            "external_id": "access-4b1782",
            "kind": "absolute",
            "from": 1792053000,
            "to": 1792058400,
            "timezone": "Australia/Perth",
            "scope_key": "after_hours_entry",
            "label": "Temporary site access"
          }
        ],
        "address": {
          "address_line_1": "456 Bourke Street",
          "address_line_2": "Apt 12",
          "city": "Melbourne",
          "state": "VIC",
          "postal_code": "3000",
          "country": "AU",
          "country_name": "Australia"
        },
        "membership_plans": [
          {
            "membership_plan_id": "plan_99999",
            "name": "Unlimited Monthly",
            "start_date": "2024-01-01T00:00:00Z",
            "status": "current",
            "is_current": true,
            "end_date": null
          }
        ]
      }
    ]
  }'

תגובה

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

{
  "message": "Member sync successful.",
  "metadata": {
    "success": 245,
    "skipped": 5,
    "skipped_items": [
      {
        "member_id": "member_123",
        "facility_id": null,
        "reason": "Facility integration is disabled in facility-partner-config"
      }
    ]
  }
}

שדות המטא-נתונים:

success - מספר החברים שעובדו בהצלחה
skipped - מספר החברים שדולגו (אם יש)
skipped_items - מערך של החברים שדולגו, עם הסיבות (אם יש)
dry-run - דגל בוליאני אם נעשה שימוש במפתח מסוג dryrun (אם רלוונטי)

צ׳ק-אינים

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

נקודות קצה

POST /partner/v1/check-ins - Save check-ins

האובייקט Check-In

מאפיינים

check_in_id string אופציונלי

מזהה ייחודי של הצ׳ק-אין. אופציונלי - אם לא סופק, הוא נוצר אוטומטית מהצמד member_id ו-timestamp.
member_id string חובה

המזהה הייחודי של החבר.
facility_id string אחד מהשנייםספקו את סוג מזהה המתקן שהוגדר לאינטגרציה שלכם: השתמשו ב-facility_id לאינטגרציות מסוג direct-link, או ב-linking_identifier לאינטגרציות מסוג linking-identifier. אל תשלחו את שניהם; ה-API משתמש בסוג המזהה שהוגדר לחשבון השותף שלכם ומתעלם מהסוג האחר. מידע נוסף

המזהה הייחודי של המתקן מ-Performance Hub.
linking_identifier string אחד מהשנייםספקו את סוג מזהה המתקן שהוגדר לאינטגרציה שלכם: השתמשו ב-facility_id לאינטגרציות מסוג direct-link, או ב-linking_identifier לאינטגרציות מסוג linking-identifier. אל תשלחו את שניהם; ה-API משתמש בסוג המזהה שהוגדר לחשבון השותף שלכם ומתעלם מהסוג האחר. מידע נוסף

ערך המזהה הייחודי שהשותף משתמש בו לכל מיקום (לדוגמה, "Branch ID", "Location Code", "Store Number"). מידע נוסף
check_in_type string אופציונלי

סוג הביקור. אחד מהערכים member, class, staff, guest או trial.
source string אופציונלי

האופן שבו הצ׳ק-אין נקלט. ערכים נפוצים כוללים manual, tag, rfid, kiosk, app. אפשר להשתמש גם בערכים נוספים כמו door_reader או booking.
class_id string אופציונלי

אופציונלי. אם הצ׳ק-אין קשור להזמנה לשיעור או לנוכחות בשיעור.
timestamp string חובה

חותמת זמן בפורמט ISO 8601 של מועד הצ׳ק-אין.

האובייקט Check-In

{
  // "check_in_id": "checkin_abc123",  // Optional - auto-generated from member_id + timestamp if not provided
  "member_id": "mem_12345",
  "facility_id": "550e8400-e29b-41d4-a716-446655440000",
  // "linking_identifier": "branch_downtown",  // If using linking identifier
  "check_in_type": "member",
  "source": "rfid",
  "timestamp": "2025-01-20T08:45:30Z"
}

שמירת צ׳ק-אינים

יוצר רשומות צ׳ק-אין. ה-API מסיר כפילויות באופן אוטומטי על סמך החבר, המתקן וחותמת הזמן.

פרמטרים

check_ins array חובה

מערך של אובייקטי Check-In לשמירה. מקסימום מומלץ: 1000 פריטים לבקשה לביצועים מיטביים. ה-API מחלק את הפריטים לאצוות לעיבוד באופן אוטומטי. כל פריט חייב לכלול את facility_id (חובה אם לא משתמשים ב-linking_identifier) או את linking_identifier (חובה אם לא משתמשים ב-facility_id).

ערך מוחזר

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

בקשה

curl -X POST https://partner-api.performancehub.co/partner/v1/check-ins \
  -u sk_live_YOUR_PARTNER_SECRET_KEY: \
  -H "Content-Type: application/json" \
  -d '{
    "check_ins": [
      {
        // "check_in_id": "checkin_abc123",  // Optional - auto-generated from member_id + timestamp if not provided
        "member_id": "mem_12345",
        "facility_id": "550e8400-e29b-41d4-a716-446655440000",
        // "linking_identifier": "branch_downtown",  // If using linking identifier
        "check_in_type": "member",
        "source": "rfid",
        "timestamp": "2025-01-20T08:45:30Z"
      }
    ]
  }'

תגובה

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

{
  "message": "Check-in sync successful.",
  "metadata": {
    "success": 523,
    "skipped": 3,
    "skipped_items": [
      {
        "member_id": "member_789",
        "facility_id": null,
        "reason": "No matching facility_id for the linking_identifier"
      }
    ]
  }
}

שדות המטא-נתונים:

success - מספר הצ׳ק-אינים שעובדו בהצלחה
skipped - מספר הצ׳ק-אינים שדולגו (אם יש)
skipped_items - מערך של הצ׳ק-אינים שדולגו, עם הסיבות (אם יש)
dry-run - דגל בוליאני אם נעשה שימוש במפתח מסוג dryrun (אם רלוונטי)

בקרת גישה

ה-Partner API יכול להפעיל חומרת Door/Gate Controller של Performance Hub במתקנים שבהם האינטגרציה שלכם מופעלת.

השתמשו ב-API זה כשמערכת ניהול החברים שלכם כבר החליטה שמותר לאדם להיכנס. Performance Hub אינו בודק סטטוס חברות, שעות גישה, כללי אזורי דלתות, בדיקות הונאה או לוגיקת השעיה. המערכת שלכם נשארת הגורם המוסמך להחלטות אלה.

בקשת הפתיחה היא סינכרונית. Performance Hub שולח את הפקודה לבקר שבאתר בזמן אמת ומחזיר 200 רק לאחר שהמכשיר מאשר שהממסר נפתח פיזית. רוב האישורים אמורים להתקבל תוך 3-5 שניות. אם לא מתקבל אישור בתוך חלון הזמן הקצוב, ה-API מחזיר כשל מפורש.

אפשר גם לתעד ניסיון גישה או דחייה שלא הגיעו לבקר. קריאה זו אינה פותחת את הדלת. היא כותבת אירוע ליומני הגישה של Door & Gate Access.

נקודות קצה

GET /partner/v1/access-control/doors - List available Door/Gate Controllers
GET /partner/v1/access-control/doors/{door_id} - Get Door/Gate Controller status
POST /partner/v1/access-control/doors/{door_id}/unlock - Unlock a Door/Gate Controller
POST /partner/v1/access-control/doors/{door_id}/access-events - Record an access attempt or denial

האובייקט Door/Gate Controller

מאפיינים

door_id string חובה

מזהה ייחודי של ה-Door/Gate Controller. שמרו אותו במערכת שלכם לאחר הגילוי והשתמשו בו בעת קריאה לנקודת הקצה של הפתיחה.
facility_id string חובה

מזהה המתקן ב-Performance Hub.
linking_identifier string אופציונלי

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

שם המכשיר הקריא לבני אדם, כפי שהוגדר ב-Performance Hub.
zone string אופציונלי

אזור הדלת או המיקום שלה, כגון Entrance.
status string חובה

online או offline.
relay_state string אופציונלי

המצב האחרון הידוע של הממסר, כגון locked או unlocked.
maintenance_mode string חובה

מצב התחזוקה הנוכחי. אחד מהערכים off, force-open או force-closed.
hold_time_seconds integer חובה

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

חותמת זמן בפורמט ISO של העדכון האחרון של המטא-נתונים של המכשיר.

האובייקט Door/Gate Controller

{
  "door_id": "00000000000000000000000000000007",
  "facility_id": "550e8400-e29b-41d4-a716-446655440000",
  "linking_identifier": "branch_downtown",
  "name": "Front Door",
  "zone": "Entrance",
  "status": "online",
  "online": true,
  "relay_state": "locked",
  "maintenance_mode": "off",
  "hold_time_seconds": 10,
  "last_seen": "2026-05-01T04:30:00.000Z"
}

הצגת רשימת Door/Gate Controllers

מחזיר את ה-Door/Gate Controllers הזמינים לאינטגרציה שלכם.

אם לא סופקו facility_id או linking_identifier, ה-API מחזיר את ה-Door/Gate Controllers בכל המתקנים המקושרים לחשבון השותף שלכם.

Recommended: Include a facility identifier whenever possible. Requests without `facility_id` or `linking_identifier` may take longer to load for partners with hundreds or thousands of Door/Gate Controllers.

פרמטרים

facility_id string אופציונלי אחד מהשנייםספקו את סוג מזהה המתקן שהוגדר לאינטגרציה שלכם: השתמשו ב-facility_id לאינטגרציות מסוג direct-link, או ב-linking_identifier לאינטגרציות מסוג linking-identifier. אל תשלחו את שניהם; ה-API משתמש בסוג המזהה שהוגדר לחשבון השותף שלכם ומתעלם מהסוג האחר. מידע נוסף

מזהה המתקן ב-Performance Hub. השתמשו בו באינטגרציות מסוג direct-link.
linking_identifier string אופציונלי אחד מהשנייםספקו את סוג מזהה המתקן שהוגדר לאינטגרציה שלכם: השתמשו ב-facility_id לאינטגרציות מסוג direct-link, או ב-linking_identifier לאינטגרציות מסוג linking-identifier. אל תשלחו את שניהם; ה-API משתמש בסוג המזהה שהוגדר לחשבון השותף שלכם ומתעלם מהסוג האחר. מידע נוסף

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

ערך מוחזר

מחזיר מערך של אובייקטי Door/Gate Controller.

בקשה

curl -X GET "https://partner-api.performancehub.co/partner/v1/access-control/doors?facility_id=550e8400-e29b-41d4-a716-446655440000" \
  -u sk_live_YOUR_PARTNER_SECRET_KEY:

תגובה

{
  "data": [
    {
      "door_id": "00000000000000000000000000000007",
      "facility_id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Front Door",
      "zone": "Entrance",
      "status": "online",
      "relay_state": "locked",
      "maintenance_mode": "off",
      "hold_time_seconds": 10,
      "last_seen": "2026-05-01T04:30:00.000Z"
    }
  ]
}

קבלת הסטטוס של Door/Gate Controller

מאחזר את המצב האחרון הידוע ואת התצורה הבסיסית של Door/Gate Controller יחיד.

ספקו מזהה מתקן כדי ש-Performance Hub יוכל לוודא שהדלת שייכת למתקן שהאינטגרציה שלכם יכולה לגשת אליו.

פרמטרים

door_id string חובה

מזהה ה-Door/Gate Controller שהוחזר מנקודת הקצה של הרשימה.
facility_id string אחד מהשנייםספקו את סוג מזהה המתקן שהוגדר לאינטגרציה שלכם: השתמשו ב-facility_id לאינטגרציות מסוג direct-link, או ב-linking_identifier לאינטגרציות מסוג linking-identifier. אל תשלחו את שניהם; ה-API משתמש בסוג המזהה שהוגדר לחשבון השותף שלכם ומתעלם מהסוג האחר. מידע נוסף

מזהה המתקן ב-Performance Hub. חובה באינטגרציות מסוג direct-link.
linking_identifier string אחד מהשנייםספקו את סוג מזהה המתקן שהוגדר לאינטגרציה שלכם: השתמשו ב-facility_id לאינטגרציות מסוג direct-link, או ב-linking_identifier לאינטגרציות מסוג linking-identifier. אל תשלחו את שניהם; ה-API משתמש בסוג המזהה שהוגדר לחשבון השותף שלכם ומתעלם מהסוג האחר. מידע נוסף

מזהה המתקן אצל השותף. חובה באינטגרציות מסוג linking-identifier.

ערך מוחזר

מחזיר אובייקט Door/Gate Controller.

בקשה

curl -X GET "https://partner-api.performancehub.co/partner/v1/access-control/doors/00000000000000000000000000000007?facility_id=550e8400-e29b-41d4-a716-446655440000" \
  -u sk_live_YOUR_PARTNER_SECRET_KEY:

תגובה

{
  "data": {
    "door_id": "00000000000000000000000000000007",
    "facility_id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Front Door",
    "zone": "Entrance",
    "status": "online",
    "relay_state": "locked",
    "maintenance_mode": "off",
    "hold_time_seconds": 10,
    "last_seen": "2026-05-01T04:30:00.000Z"
  }
}

פתיחת Door/Gate Controller

שולח פקודת פתיחה ל-Door/Gate Controller וממתין שהממסר הפיזי יאשר שהוא נפתח.

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

פרמטרים

door_id string חובה

מזהה ה-Door/Gate Controller שהוחזר מנקודת הקצה של הרשימה.
facility_id string אחד מהשנייםספקו את סוג מזהה המתקן שהוגדר לאינטגרציה שלכם: השתמשו ב-facility_id לאינטגרציות מסוג direct-link, או ב-linking_identifier לאינטגרציות מסוג linking-identifier. אל תשלחו את שניהם; ה-API משתמש בסוג המזהה שהוגדר לחשבון השותף שלכם ומתעלם מהסוג האחר. מידע נוסף

מזהה המתקן ב-Performance Hub. חובה באינטגרציות מסוג direct-link.
linking_identifier string אחד מהשנייםספקו את סוג מזהה המתקן שהוגדר לאינטגרציה שלכם: השתמשו ב-facility_id לאינטגרציות מסוג direct-link, או ב-linking_identifier לאינטגרציות מסוג linking-identifier. אל תשלחו את שניהם; ה-API משתמש בסוג המזהה שהוגדר לחשבון השותף שלכם ומתעלם מהסוג האחר. מידע נוסף

מזהה המתקן אצל השותף. חובה באינטגרציות מסוג linking-identifier.
member_id string חובה

מזהה החבר אצל השותף. משמש לרישום ביומן הביקורת ולקישור נתונים בהמשך.
first_name string חובה

השם הפרטי של האדם שפותח את הדלת.
last_name string חובה

שם המשפחה של האדם שפותח את הדלת.
full_name string אופציונלי

אופציונלי. אם הוא מושמט, Performance Hub משלב את first_name ו-last_name.
check_in_id string אופציונלי

מזהה צ׳ק-אין אופציונלי מהמערכת שלכם, לצורך הצלבה.
idempotency_key string אופציונלי

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

ערך מוחזר

מחזיר 200 רק כשהמכשיר מאשר שהממסר נפתח פיזית. הדלת משתמשת בזמן ההחזקה שהוגדר בניהול מכשירים ב-Performance Hub; שותפים אינם יכולים לעקוף את תזמון הממסר בכל בקשה. רוב האישורים אמורים להתקבל תוך 3-5 שניות. התייחסו לזמן הקצוב המתועד כפתיחה שנכשלה באופן מפורש, ונסו שוב רק בהתאם לכללי הבטיחות שלכם.

כשלים נפוצים:

403 integration_not_enabled - האינטגרציה שלכם אינה מופעלת עבור המתקן.
409 maintenance_mode_active - צוות המתקן הפעיל מצב תחזוקה עבור הדלת.
503 device_offline - ה-Door/Gate Controller לא מקוון או שהנתונים שלו אינם עדכניים.
504 unlock_confirmation_timeout - הפקודה נשלחה, אבל לא התקבל אישור תואם לפני תום הזמן הקצוב.

בקשה

curl -X POST https://partner-api.performancehub.co/partner/v1/access-control/doors/00000000000000000000000000000007/unlock \
  -u sk_live_YOUR_PARTNER_SECRET_KEY: \
  -H "Content-Type: application/json" \
  -d '{
    "facility_id": "550e8400-e29b-41d4-a716-446655440000",
    "member_id": "mem_12345",
    "first_name": "Jane",
    "last_name": "S.",
    "full_name": "Jane S.",
    "source": "door_reader",
    "idempotency_key": "unlock_20260501_0001"
  }'

תגובה

{
  "status": "unlocked",
  "door_id": "00000000000000000000000000000007",
  "facility_id": "550e8400-e29b-41d4-a716-446655440000",
  "event_id": "00000000-0000-0000-0000-000000000045",
  "command_id": "00000000-0000-0000-0000-000000000049",
  "hold_time_seconds": 10,
  "confirmed_at": "2026-05-01T04:30:00.000Z"
}

תגובת כשל

{
  "status": "failed",
  "reason": "device_offline",
  "door_id": "00000000000000000000000000000007",
  "facility_id": "550e8400-e29b-41d4-a716-446655440000",
  "event_id": "00000000-0000-0000-0000-000000000045"
}

תיעוד ניסיון גישה או דחייה

מתעד ניסיון גישה או דחייה שהמערכת שלכם כבר החליטה עליהם. אין פנייה ל-Door/Gate Controller, והדלת אינה נפתחת.

השתמשו בזה כשהמערכת שלכם מסרבת לכניסה, או כשניסיון צריך להופיע ביומני הגישה של Door & Gate Access ללא פתיחה. Performance Hub אינו בודק סטטוס חברות, שעות גישה או כללי גישה אחרים.

אירוע דחייה מופיע ביומני הגישה של Door & Gate Access עם התוצאה Denied, שם השותף שלכם, הדלת, מזהה החבר כשאתם שולחים אותו וקוד הסיבה בצורה קריאה. לדוגמה, membership_expired מוצג כ-"Membership Expired". reason_display_text ו-user_email נשמרים עם האירוע.

פרמטרים

door_id string חובה

מזהה ה-Door/Gate Controller שהוחזר מנקודת הקצה של הרשימה.
facility_id string אחד מהשנייםספקו את סוג מזהה המתקן שהוגדר לאינטגרציה שלכם: השתמשו ב-facility_id לאינטגרציות מסוג direct-link, או ב-linking_identifier לאינטגרציות מסוג linking-identifier. אל תשלחו את שניהם; ה-API משתמש בסוג המזהה שהוגדר לחשבון השותף שלכם ומתעלם מהסוג האחר. מידע נוסף

מזהה המתקן ב-Performance Hub. חובה באינטגרציות מסוג direct-link.
linking_identifier string אחד מהשנייםספקו את סוג מזהה המתקן שהוגדר לאינטגרציה שלכם: השתמשו ב-facility_id לאינטגרציות מסוג direct-link, או ב-linking_identifier לאינטגרציות מסוג linking-identifier. אל תשלחו את שניהם; ה-API משתמש בסוג המזהה שהוגדר לחשבון השותף שלכם ומתעלם מהסוג האחר. מידע נוסף

מזהה המתקן אצל השותף. חובה באינטגרציות מסוג linking-identifier.
outcome string חובה

denied או attempted.
reason string אופציונלי

קוד סיבה באותיות קטנות בפורמט snake_case, עד 64 תווים. חובה כאשר outcome הוא denied. דוגמה: membership_expired.
reason_display_text string אופציונלי

סיבה קריאה לבני אדם, עד 256 תווים. דוגמה: Membership expired on 2026-04-01.
member_id string אופציונלי

מזהה החבר אצל השותף. השמיטו אותו כשפרטי הזיהוי לא התאימו לאף חבר, למשל כרטיס לא מוכר.
user_email string אופציונלי

כתובת הדוא"ל של האדם שניסה לקבל גישה.
timestamp string אופציונלי

מתי התרחש הניסיון, בפורמט ISO 8601 עם אזור זמן. דוגמה: 2026-05-18T10:15:30Z. ברירת המחדל היא השעה שבה הבקשה מתקבלת. אסור שיהיה יותר מ-5 דקות בעתיד או ישן מ-30 ימים.
idempotency_key string אופציונלי

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

ערך מוחזר

מחזיר 201 כשהאירוע מתועד. שליחה חוזרת של אותו idempotency_key מחזירה 200 כאשר idempotent מוגדר ל-true, ואינה יוצרת אירוע נוסף.

מפתח dry-run מחזיר 200 כאשר dry_run מוגדר ל-true. שום דבר אינו מתועד.

כשלים נפוצים:

400 - הגוף אינו תקין, לדחייה אין reason, חותמת הזמן מחוץ לטווח, או ש-facility_id / linking_identifier אינו תואם למתקן מקושר.
403 - המפתח הוא לקריאה בלבד.
403 integration_not_enabled - האינטגרציה שלכם אינה מופעלת עבור המתקן. השדה message מציין את הסיבה.
404 - ה-Door/Gate Controller לא נמצא עבור המתקן המקושר.

בקשה

curl -X POST https://partner-api.performancehub.co/partner/v1/access-control/doors/00000000000000000000000000000007/access-events \
  -u sk_live_YOUR_PARTNER_SECRET_KEY: \
  -H "Content-Type: application/json" \
  -d '{
    "facility_id": "550e8400-e29b-41d4-a716-446655440000",
    "outcome": "denied",
    "reason": "membership_expired",
    "reason_display_text": "Membership expired on 2026-04-01",
    "member_id": "mem_12345",
    "user_email": "member@example.com",
    "timestamp": "2026-05-18T10:15:30Z",
    "idempotency_key": "evt_abc12345"
  }'

תגובה

{
  "status": "recorded",
  "event_id": "00000000-0000-0000-0000-000000000045",
  "outcome": "denied",
  "door_id": "00000000000000000000000000000007",
  "facility_id": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2026-05-18T10:15:30.000Z"
}

שליחה חוזרת אידמפוטנטית

{
  "status": "recorded",
  "event_id": "00000000-0000-0000-0000-000000000045",
  "outcome": "denied",
  "door_id": "00000000000000000000000000000007",
  "facility_id": "550e8400-e29b-41d4-a716-446655440000",
  "timestamp": "2026-05-18T10:15:30.000Z",
  "idempotent": true
}

דוחות מתקן

רשומה של נקודת זמן מסוימת, שמתעדת מדדים תפעוליים ופיננסיים מרכזיים של מתקן במהלך תקופה מסוימת.

נקודות קצה

POST /partner/v1/report-snapshots - Save report snapshots

האובייקט Report Snapshot

מאפיינים

facility_id string אחד מהשנייםספקו את סוג מזהה המתקן שהוגדר לאינטגרציה שלכם: השתמשו ב-facility_id לאינטגרציות מסוג direct-link, או ב-linking_identifier לאינטגרציות מסוג linking-identifier. אל תשלחו את שניהם; ה-API משתמש בסוג המזהה שהוגדר לחשבון השותף שלכם ומתעלם מהסוג האחר. מידע נוסף

המזהה הייחודי של המתקן מ-Performance Hub.
linking_identifier string אחד מהשנייםספקו את סוג מזהה המתקן שהוגדר לאינטגרציה שלכם: השתמשו ב-facility_id לאינטגרציות מסוג direct-link, או ב-linking_identifier לאינטגרציות מסוג linking-identifier. אל תשלחו את שניהם; ה-API משתמש בסוג המזהה שהוגדר לחשבון השותף שלכם ומתעלם מהסוג האחר. מידע נוסף

ערך המזהה הייחודי שהשותף משתמש בו לכל מיקום (לדוגמה, "Branch ID", "Location Code", "Store Number"). מידע נוסף
start_date string חובה

תאריך ההתחלה של תקופת תמונת המצב בפורמט YYYY-MM-DD.
end_date string חובה

תאריך הסיום של תקופת תמונת המצב בפורמט YYYY-MM-DD.
metrics object חובה

אובייקט מדדים שמכיל נתוני חברים והכנסות לתקופה.

האובייקט Report Snapshot

{
  "facility_id": "550e8400-e29b-41d4-a716-446655440000",
  // "linking_identifier": "branch_downtown",  // If using linking identifier
  "start_date": "2025-01-01",
  "end_date": "2025-01-31",
  "metrics": {
    "members": {
      "active": 1200,
      "new": 45,
      "cancelled": 12
    },
    "revenue": {
      "total_payments": 289000.00,
      "total_payments_count": 1200,
      "currency": "AUD"
    }
  }
}

שמירת תמונות מצב של דוחות

שולח מדדים תפעוליים ופיננסיים של מתקן במהלך תקופה מסוימת.

פרמטרים

snapshots array חובה

מערך של אובייקטי Report Snapshot לשמירה. 25 פריטים לכל היותר בכל בקשה. כל פריט חייב לכלול את facility_id (חובה אם לא משתמשים ב-linking_identifier) או את linking_identifier (חובה אם לא משתמשים ב-facility_id).

ערך מוחזר

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

בקשה

curl -X POST https://partner-api.performancehub.co/partner/v1/report-snapshots \
  -u sk_live_YOUR_PARTNER_SECRET_KEY: \
  -H "Content-Type: application/json" \
  -d '{
    "snapshots": [
      {
        "facility_id": "550e8400-e29b-41d4-a716-446655440000",
        // "linking_identifier": "branch_downtown",  // If using linking identifier
        "start_date": "2025-01-01",
        "end_date": "2025-01-31",
        "metrics": {
          "members": {
            "active": 1200,
            "new": 45,
            "cancelled": 12
          },
          "revenue": {
            "total_payments": 289000.00,
            "currency": "AUD"
          }
        }
      }
    ]
  }'

תגובה

{
  "message": "Report snapshot sync successful."
}

שגיאות

ה-Partner API משתמש בקודי סטטוס HTTP סטנדרטיים ובגופי תגובה בפורמט JSON כדי להסביר מדוע בקשה נכשלה.

מבנה תגובת השגיאה

רוב שגיאות ה-API מחזירות גוף JSON עם הודעה, ובמידת האפשר גם פרטים מובנים.

קודי סטטוס

כשלים ב-Access Time Windows

אימות החלונות נכשל לפני שתמונת המצב הלא תקינה נכתבת. סיבות נפוצות שאין טעם לנסות בהן שוב כוללות:

היעדר access_time_windows_revision כאשר access_time_windows קיים.
ערכי epoch מסוג מחרוזת, מספר נקודה צפה, או ערכים שנראים כאלפיות שנייה.
אזור זמן IANA לא תקין, מרווח הפוך, external_id כפול, מקטעים שבועיים חופפים, או מקטע לילי שלא פוצל.
ערך שחורג ממגבלות הכמות, האורך או הטווח המתועדות.

גרסה חוזרת עם תוכן מנורמל שונה מחזירה 409 Conflict. בצעו התאמה מול המצב המוסמך העדכני ביותר והקצו גרסה חדשה יותר; אל תמשיכו לנסות שוב את הצמד המתנגש. גרסה ישנה יותר מדווחת כתמונת מצב ישנה שדולגה, ואינה מורשית לדרוס מצב חדש יותר. scope_key לא מוכר או לא ממופה גורם לכך שההרשאה נשללת ולא ניתנת גישה, ויש להתייחס אליו כהתראת תצורה.

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

הנחיות לניסיון חוזר

נסו שוב את אלה עם השהיה מעריכית מוגבלת:

429
500
502
503
504

אל תנסו שוב את אלה באופן עיוור:

400
401
403
404
409
422

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

פרטים שיש לכלול בפנייה לתמיכה

כשאתם פונים לתמיכה, כללו:

נקודת הקצה ושיטת ה-HTTP.
חותמת זמן ואזור זמן.
מזהה מפתח השותף, לא המפתח הסודי.
מזהה המתקן שבו נעשה שימוש.
מזהה רשומת המקור מהמערכת שלכם.
סטטוס התגובה וגוף התגובה.
event_id או command_id, כשהם זמינים.

{
  "success": false,
  "message": "Request body.members[0].member_id is required"
}

חלק מנקודות הקצה הייעודיות לתחום מסוים מחזירות סטטוס וסיבה מפורשים. לדוגמה, כשלים בבקרת גישה כוללים שדות כגון reason, door_id, facility_id ו-event_id.

{
  "status": "failed",
  "reason": "device_offline",
  "door_id": "00000000000000000000000000000007",
  "facility_id": "550e8400-e29b-41d4-a716-446655440000",
  "event_id": "00000000-0000-0000-0000-000000000045"
}

400 Bad Request

הבקשה פגומה או שחסרים בה שדות חובה. תקנו את הבקשה לפני ניסיון חוזר.

401 Unauthorized

האימות נכשל. ודאו שאתם משתמשים ב-HTTP Basic Auth עם המפתח הסודי של ה-API כשם המשתמש ועם סיסמה ריקה.

403 Forbidden

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

404 Not Found

המשאב המבוקש לא נמצא או שאינו זמין לאינטגרציה שלכם.

409 Conflict

הבקשה מתנגשת במצב הנוכחי של המשאב. בבקרת גישה, הדבר יכול לכלול מצב שבו Door/Gate Controller נמצא במצב תחזוקה.

422 Unprocessable Entity

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

429 Too Many Requests

האינטגרציה חרגה ממגבלת הקצב המתועדת. נסו שוב עם השהיה מעריכית (exponential backoff).

500 Internal Server Error

Performance Hub לא הצליח להשלים את הבקשה בגלל שגיאה פנימית. נסו שוב עם השהיה. אם הבעיה נמשכת, פנו לתמיכה וציינו את נקודת הקצה, חותמת הזמן וגוף התגובה.

503 Service Unavailable

שירות או מכשיר שהבקשה תלויה בהם אינם זמינים. בפתיחות של Door/Gate Controller, המשמעות יכולה להיות שהבקר אינו מקוון.

504 Gateway Timeout

הזמן הקצוב לפעולה פג. בפתיחות של Door/Gate Controller, המשמעות היא שהפתיחה לא אושרה לפני תום חלון הזמן הקצוב.

ניהול גרסאות

גרסת ה-Partner API מצוינת בכתובת ה-URL. הגרסה הנוכחית היא:

מדיניות שינויים

Performance Hub שואף לבצע שינויים מצטברים ותואמים לאחור בכל מקום אפשרי.

דוגמאות לשינויים תואמים לאחור:

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

access_time_windows ו-access_time_windows_revision הם שדות שנוספו לבקשת Member. לקוחות קיימים שמשמיטים אותם שומרים על תמונת המצב השמורה של Access Time Windows ללא שינוי. כלל ההשמטה הזה שומר על תאימות ל-upsert חלקי; השמטה אינה שקולה לשליחת מערך ריק.

דוגמאות לשינויים שוברי תאימות:

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

הוצאה משימוש

כשנדרש שינוי שובר תאימות, Performance Hub יימנע ככל האפשר משינוי הגרסה הקיימת במקומה. במקום זאת, נציג גרסה חדשה או נתיב העברה, ונודיע על השינוי לשותפים המושפעים.

הודעות על הוצאה משימוש יכולות לכלול:

רשומה ביומן השינויים.
תקשורת ישירה עם השותפים.
הערות ב-Partner Console.
הנחיות העברה בתיעוד.

המלצות ללקוחות

בנו לקוחות שעמידים בפני שינויים מצטברים:

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

במחיצות עם גרסאות של Member, כגון Access Time Windows, שמרו את הגרסה שנשלחה ואת המטען המנורמל עד שהתוצאה ידועה. שימוש חוזר בגרסה עבור תוכן שהשתנה הוא התנגשות, ואילו שליחה חוזרת של אותו תוכן היא אידמפוטנטית. ראו Access Time Windows.

מפרטי OpenAPI

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

ראו מפרטי OpenAPI.

https://partner-api.performancehub.co/partner/v1/

יומן שינויים

יומן שינויים זה מתעד שינויים בולטים ב-Partner API וב-Partner Console שמשפיעים על התנהגות האינטגרציה.

2026-09-09

2026-05-06

2026-05-01

קטגוריות שינויים

רשומות עתידיות ישתמשו בקטגוריות הבאות:

Added - נקודת קצה, שדה, מדריך או יכולת חדשים.
Changed - שינוי בהתנהגות או בתיעוד, ללא הסרת תמיכה.
Deprecated - התכונה נשארת זמינה, אבל יש לה נתיב העברה מתוכנן.
Removed - תכונה או נקודת קצה הוסרו.
Fixed - תיקון באג או תיקון בתיעוד.
Security - שינוי באימות, בהרשאות, בטיפול בנתונים או בניהול מפתחות.

נוספו

נוספו תמונות מצב של access_time_windows לחברים, בלתי תלויות בספק, עם שילוב של חלונות מוחלטים וחלונות שבועיים חוזרים.
נוספו סמנטיקות של סידור לפי access_time_windows_revision, שליחה חוזרת אידמפוטנטית, התנגשות, דילוג על נתונים ישנים ושלילה מפורשת.
נוספו הנחיות בנושא אזור זמן IANA, שעון קיץ, מיפוי scope_key לוגי, עדכניות המקור, מימוש אצל היצרן והסמכה.

נוספו

נוסף תיעוד של תוכנית השותפים, הכולל סוגי שותפים, הצטרפות, שיטות מומלצות, מוכנות לעלייה לאוויר, שגיאות, ניהול גרסאות ותמיכה.
נוסף תהליך פנייה ייעודי, Become a Partner, לשותפים טכניים ומסחריים פוטנציאליים.
נוסף תיעוד של האופן שבו אינטגרציות שותפים מאושרות מופיעות במדריך השותפים של Performance Hub בתוך פלטפורמת הליבה של Performance Hub.

נוספו

נוסף תיעוד בקרת גישה של Door/Gate Controller, כולל פעולות הצגת רשימה, סטטוס ופתיחה.
נוסף תיעוד של התנהגות הפתיחה הסינכרונית: ה-API מחזיר הצלחה רק לאחר שהבקר שבאתר מאשר שהממסר נפתח פיזית.
נוסף תיעוד של התמיכה בפרמטר האופציונלי idempotency_key בבקשות פתיחה של Door/Gate Controller.