مقدمة

تتيح Performance Hub Partner API لمنصات الشركاء الخارجية التكامل بسلاسة مع الوحدات النمطية الأساسية في 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 فقط عندما تكون مستعدًا للتأثير في بيانات الإنتاج.

المصادقة وإدارة المفاتيح

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

التحقق من البيانات

الحقول المطلوبة موجودة لكل نقطة نهاية تستدعيها.
معرّفات المنشآت تتطابق مع طريقة الربط المهيّأة لديك.
المعرّفات القادمة من نظامك ثابتة ولا تتغير بين عمليات المزامنة.
عمليات الاستيراد الكبيرة مقسّمة إلى دفعات ضمن الحدود الموثّقة.
يمكن تحديد العناصر التي أخفقت في الدفعات وإعادة إرسالها.

اختبار نقاط النهاية

قبل الإطلاق، اختبر كل نقطة نهاية يعتمد عليها تكاملك:

يمكن قراءة المنظمات والمنشآت.
يمكن حفظ الأعضاء وتحديثهم.
تتم مزامنة خطط العضوية ومناطق الوصول وساعات الوصول بشكل صحيح.
تُقبل تسجيلات الدخول ويمكن ربطها بنظامك.
تستخدم لقطات التقارير فترة التقرير والمقاييس المتوقعة.
تم اختبار مسارات وحدات التحكم في الأبواب/البوابات على أجهزة حقيقية حيثما ينطبق ذلك.

الجاهزية لـ Access Time Window

إذا كان التكامل يوفّر Access Time Windows:

تجتاز الأمثلة المطلقة والأسبوعية قائمة التحقق لاعتماد المنتج.
قيم epoch أعداد صحيحة بالثواني وفق Unix دون علامات اقتباس؛ وقد تم اختبار الحدود الدقيقة [from, to).
تم التحقق من القيم الافتراضية بتوقيت UTC، والمناطق الزمنية المخصصة وفق IANA للتكامل، وانتقالات التوقيت الصيفي ذات الصلة.
ينسّق تسلسل مراجعات واحد ودائم ومتزايد باطّراد لكل عضو/مصدر التحديثاتِ التزايدية والتسوية وإعادة المحاولات.
يفهم المشغّلون سلوك الحذف، والاستبدال الكامل، وعدم التكرار، والتعارض، والبيانات القديمة، و[] الصريحة.
لكل scope_key، بما في ذلك default، تعيين معتمد في Performance Hub؛ وتم اختبار أن المفاتيح غير المعروفة تخفق بشكل مغلق.
تمت تهيئة وتيرة التحديث المتوقعة للتكامل، والحد الأقصى لعمر بيانات المصدر، وسلوك المصدر القديم، والتنبيهات.
ثبت أن إخفاق الجلب من المصدر لا يُصدر لقطة فارغة أو جزئية.
يستوفي تقارب تسلسل المراجعات في مرحلة الاختبار، والإلغاء/السحب، وحدود البدء والانتهاء على الأبواب الفعلية الأهدافَ المتفق عليها.
تم التحقق من القواعد العادية والمنح الدائمة بوصفها مسارات احتياطية، ولا يمكن للنوافذ تجاوز تعطيل المستخدم، أو blockAllAccess، أو الصيانة، أو Geofence.

الجاهزية للتحكم في الوصول

بالنسبة إلى تكاملات التحكم في الوصول:

يتخذ نظامك قرار الوصول قبل استدعاء 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 تهيئتها لكل حالة على حدة. إذا كنت تتوقع عمليات استيراد كبيرة الحجم، أو حركة مرور عند الإطلاق، أو عمليات ملء رجعي للتقارير، فاتفق على الإنتاجية المطلوبة قبل فترة التغيير.

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

أعِد المحاولة بأمان

استخدم التراجع الأُسّي مع حالات الإخفاق العابرة مثل 429 و500 و502 و503 و504.

تجنّب حلقات إعادة المحاولة المتلاحقة. ونقطة البداية الجيدة هي:

أعِد المحاولة بعد ثانية واحدة.
أعِد المحاولة بعد ثانيتين.
أعِد المحاولة بعد 4 ثوانٍ.
توقّف وأطلق تنبيهًا إذا استمر إخفاق العملية.

في حالات إخفاق التحقق مثل 400 أو 422، أصلح الطلب قبل إعادة المحاولة.

استخدم خاصية عدم التكرار (idempotency) حيثما كانت مدعومة

تدعم نقطة نهاية فتح قفل وحدة التحكم في الباب/البوابة المعلمة الاختيارية idempotency_key. وتؤدي إعادة استخدام المفتاح نفسه للشريك والمنشأة والباب أنفسهم إلى إرجاع النتيجة الموجودة عند توفرها.

استخدم مفتاحًا ثابتًا للإجراء الذي يُنفَّذ، مثل معرّف تسجيل الدخول أو معرّف حدث الوصول من نظامك.

لا تفترض أن كل نقطة نهاية للكتابة تدعم عدم التكرار ما لم يكن ذلك موثّقًا لنقطة النهاية تلك.

حافظ على نظافة بيانات المصدر

أرسل قيمًا ثابتة وموحّدة كلما أمكن ذلك:

استخدم معرّفات متسقة للأعضاء والخطط والمنشآت وتسجيلات الدخول من نظامك المصدر.
استخدم طوابع زمنية بتنسيق ISO 8601 للتواريخ والأوقات.
أرسل أرقام الهواتف بالتنسيق الدولي عند توفرها.
أرسل العملات باستخدام الحقول الموثّقة لكل نقطة نهاية.
تجنّب تحميل الحقول النصية الحرة ببيانات مكانها الحقول المنظَّمة.

صمّم لعمليات المزامنة التزايدية والكاملة

تحتاج معظم تكاملات الشركاء إلى كلتيهما:

عمليات مزامنة تزايدية للتغييرات اليومية.
عمليات مزامنة كاملة للتسوية لتصحيح الأحداث الفائتة أو عمليات الاستيراد التاريخية أو انحراف البيانات.

ينبغي أن يتمكن تكاملك من إعادة إرسال الحالة الحالية لعضو أو خطة عضوية أو لقطة تقرير دون الاعتماد على نجاح طلب سابق.

انشر Access Time Windows بأمان

تعامل مع قيمة access_time_windows لكل عضو على أنها لقطة كاملة ذات مراجعة مستقلة:

نسّق تسلسلًا واحدًا متزايدًا باطّراد لقيمة access_time_windows_revision عبر عمليات المزامنة التزايدية وعمليات التسوية.
أعِد محاولة أي تسليم غير مؤكد أو عابر بالمراجعة نفسها والحمولة الموحّدة نفسها.
احذف access_time_windows عندما لا تحدّثها.
لا ترسل [] إلا بعد أن يثبت جلب ناجح وموثوق من المصدر عدم بقاء أي نوافذ. ولا تحوّل أبدًا انتهاء مهلة في المصدر أو نتيجة جزئية أو إخفاقًا في التحليل إلى إلغاء.
حافظ على ثبات external_id وscope_key، واعتمد كل تعيين للنطاقات قبل بيئة الإنتاج.
راقب عمر بيانات المصدر وفقًا لسياسة الحداثة المتفق عليها لذلك التكامل.

راجع دليل منتجي Access Time Windows المرجعي للاطلاع على اللقطات الكاملة، والمناطق الزمنية، والتوقيت الصيفي، والإلغاء، ومتجهات الاختبار.

تعامل مع التحكم في الوصول بوصفه أمرًا بالغ الأهمية للسلامة

بالنسبة إلى عمليات فتح أقفال وحدات التحكم في الأبواب/البوابات:

يجب أن يحدد نظامك ما إذا كان يُسمح للشخص بالدخول قبل استدعاء 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

كائن المنظمة

السمات

org_id string مطلوب

المعرّف الفريد للمنظمة.
name string مطلوب

اسم المنظمة.

كائن المنظمة

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

عرض قائمة جميع المنظمات

يُرجع قائمة بالمنظمات التي يمكن لحساب الشريك الخاص بك الوصول إليها.

القيم المُرجعة

يُرجع كائن JSON يحتوي على الخاصية data التي تتضمن مصفوفة من كائنات المنظمات.

الطلب

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، والولاية أو المقاطعة، والمدينة.
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_id string مطلوب

المعرّف الفريد لخطة العضوية.
facility_id string أحدهماقدّم نوع معرّف المنشأة المهيّأ لتكاملك: استخدم facility_id لتكاملات الربط المباشر، أو linking_identifier لتكاملات معرّف الربط. لا ترسل كليهما؛ إذ تستخدم API نوع المعرّف المهيّأ لحساب الشريك الخاص بك وتتجاهل الآخر. اعرف المزيد

المعرّف الفريد للمنشأة من Performance Hub.
linking_identifier string أحدهماقدّم نوع معرّف المنشأة المهيّأ لتكاملك: استخدم facility_id لتكاملات الربط المباشر، أو 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 لعدد غير محدود).

كائن خطة العضوية

يستخدم هذا المثال facility_id. وفي تكامل معرّف الربط، أرسل بدلًا من ذلك "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"]]
  }
}

نزيل فندق – على مدار الساعة طوال أيام الأسبوع: وصول دائم، وهي حالة الاستخدام الأكثر شيوعًا.

{
  "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 مطلوب

مصفوفة من كائنات خطط العضوية المراد حفظها. الحد الأقصى الموصى به: 1000 عنصر لكل طلب لتحقيق أفضل أداء. تقسّم API العناصر إلى دفعات تلقائيًا لمعالجتها. يجب أن يتضمن كل عنصر إما facility_id (مطلوب إذا لم تستخدم linking_identifier) أو linking_identifier (مطلوب إذا لم تستخدم facility_id).

القيم المُرجعة

يُرجع رسالة بسيطة تؤكد عملية المزامنة.

الطلب

يستخدم هذا المثال facility_id. وفي تكامل معرّف الربط، أرسل بدلًا من ذلك "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_id string مطلوب

المعرّف الفريد للعضو.
facility_id string أحدهماقدّم نوع معرّف المنشأة المهيّأ لتكاملك: استخدم facility_id لتكاملات الربط المباشر، أو linking_identifier لتكاملات معرّف الربط. لا ترسل كليهما؛ إذ تستخدم API نوع المعرّف المهيّأ لحساب الشريك الخاص بك وتتجاهل الآخر. اعرف المزيد

المعرّف الفريد للمنشأة من Performance Hub.
linking_identifier string أحدهماقدّم نوع معرّف المنشأة المهيّأ لتكاملك: استخدم facility_id لتكاملات الربط المباشر، أو 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_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 لعضو الشريك أن يحمل وصولًا مؤقتًا أو متكررًا يوفّره نظام خارجي. هذه الصفحة هي دليل المنتج المرجعي لكل من access_time_windows وaccess_time_windows_revision.

Access Time Windows أذونات إضافية للسماح فقط. يمكن للنافذة النشطة أن تسمح بالوصول، لكن النافذة غير النشطة أو المنتهية أو القديمة أو غير المعيَّنة لا تمنع وصولًا تسمح به بالفعل قاعدة عادية أو منحة دائمة. ويظل تعطيل المستخدم، والحظر الصريح للأبواب، ووضع الصيانة، وGeofence، وحدود المعدل، وتوفر وحدة التحكم سارية.

تطبيقات أنظمة المصدر المحددة هي محوّلات منفصلة. ويجب أن تترجم بيانات المصدر لديها إلى هذا العقد المحايد تجاه الموردين دون تغيير معاني حقوله.

حقول لقطة العضو

access_time_windows array اختياري

لقطة Access Time Window الكاملة لهذا العضو ولمصدر الشريك هذا. ويمكن أن تجمع اللقطة بين نوافذ 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 أعداد صحيحة في JSON تمثّل ثواني Unix وتحدد لحظات زمنية بتوقيت 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] بتنسيق 24 ساعة HH:mm مع أصفار بادئة. يجب أن تكون الكتل غير فارغة ومرتبة وغير متداخلة. وend غير مشمولة. لا يمكن للكتلة أن تتجاوز منتصف الليل؛ قسّم الفاصل الزمني الليلي في المصدر إلى كتلة متأخرة في اليوم الأول وكتلة مبكرة في اليوم التالي.

المعرّفات الثابتة وتعيين النطاقات

يجب أن يكون external_id ثابتًا طوال عمر النافذة المنطقية وفريدًا ضمن لقطة العضو. حافظ على ثباته عند تغيّر الأوقات أو التسميات حتى يتمكن المشغّلون وسجلات التدقيق من ربط المراجعات. ولا تُعِد استخدامه لنافذة غير ذات صلة.

scope_key هو هدف الوصول المنطقي الثابت الخاص بك. وقيمته الافتراضية default. يعيّن مسؤول المنشأة كل مفتاح مسموح به إلى أهداف في Performance Hub على مستوى المنشأة بأكملها، أو باب، أو نطاق الوصول:

اللقطات الكاملة والمراجعات

تعامل مع الحقلين بوصفهما قسمًا ذا إصدارات مستقلة داخل عملية الإدراج أو التحديث للعضو:

الإدخال	النتيجة
حذف `access_time_windows`	تبقى اللقطة الحالية دون تغيير؛ ولا يلزم تقديم مراجعة
موجودة مع مراجعة أحدث	تُستبدل اللقطة المخزنة بالكامل لهذا العضو/المصدر
المراجعة نفسها والحمولة الموحّدة نفسها	إعادة إرسال آمنة من التكرار؛ ولا تتغير اللقطة
المراجعة نفسها وحمولة موحّدة مختلفة	تعارض؛ خصّص مراجعة جديدة بعد التسوية
مراجعة أقدم	يتم تخطي اللقطة القديمة؛ ولا يمكنها الكتابة فوق الحالة الأحدث
`access_time_windows: []` مع مراجعة أحدث	تلغي صراحةً جميع النوافذ التي يملكها المصدر

اللقطة كاملة وليست تصحيحًا جزئيًا. فإذا كانت المراجعة 1842 تتضمن النافذتين A وB، فإن المراجعة 1843 التي تتضمن B فقط تزيل A.

حافظ على تسلسل مراجعات منسّق واحد لكل شريك/عضو عبر عمليات معالجة webhook، والاستطلاع الدوري، وإعادة الإرسال، والتسوية الكاملة. ويُفضَّل استخدام تسلسل دائم في قاعدة البيانات. لا يمكن استخدام قيمة بالمللي ثانية وفق Unix بوصفها مراجعة إلا عندما تنسّق كل الجهات الكاتبة وتضمن ترتيبًا صارمًا وتفرّدًا؛ فهي قيمة مراجعة، وليست حقل epoch.

احتفظ بالطلب والمراجعة كما هما بالضبط حتى تُعرف استجابة API. أعِد محاولة اللقطة الموحَّدة نفسها بالمراجعة نفسها بعد انتهاء المهلة أو حدوث خطأ عابر. ولا تخصّص مراجعة جديدة لمجرد أن تسليم النقل غير مؤكد.

الإلغاء وانتهاء الصلاحية وإخفاقات المصدر

إلغاء نافذة واحدة: اجلب حالة المصدر الموثوقة بنجاح، وأزل تلك النافذة، وأرسل اللقطة الكاملة المتبقية بمراجعة أحدث.
إلغاء جميع النوافذ: أرسل access_time_windows: [] بمراجعة أحدث.
ترك نافذة مطلقة تنتهي: تتوقف عن السماح بالوصول عند to؛ وأرسل تسوية لاحقة دون الإدخال المنتهي للحفاظ على نظافة اللقطات.
إنهاء نافذة أسبوعية: أزلها في لقطة أحدث، أو استخدم active_until عندما يكون لدى المصدر لحظة انتهاء معروفة.
إخفاق جلب المصدر أو عدم اكتماله: لا ترسل [] ولا تنشر لقطة جزئية. أطلق تنبيهًا وأعِد محاولة الجلب. فتحويل إخفاق المصدر إلى لقطة فارغة يعني إلغاءً غير مقصود للوصول.
إخفاق طلب Partner API في التحقق: صحّح البيانات وأرسل مراجعة أحدث فقط إذا تغيّرت اللقطة الموحّدة. وأعِد محاولة حالات الإخفاق العابرة بالمراجعة الأصلية.

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

خوارزمية المنتج

استخدم مسار العمل التالي المستقل عن لغة البرمجة لكل تحديث للعضو:

قائمة التحقق للاعتماد

أكمل هذه الفحوصات في منشأة بيئة الاختبار باستخدام التعيين النهائي لـ scope_key:

تُقبل نافذة مطلقة مع حذف المنطقة الزمنية وتُقيَّم بتوقيت UTC.
تحافظ نافذة مطلقة بمنطقة زمنية مخصصة وفق IANA على لحظتَي from/to نفسيهما.
تتبع نافذة أسبوعية بمنطقة زمنية مخصصة وفق IANA التوقيت المحلي عبر انتقالات تقديم الساعة وتأخيرها.
تستبدل لقطة مختلطة مطلقة/أسبوعية اللقطة السابقة بالكامل.
يبدأ الوصول عند from تمامًا ويتوقف عند to تمامًا؛ ونهايات الكتل الأسبوعية غير مشمولة كذلك.
يسري تحديث الأوقات ضمن external_id نفسه بمراجعة أحدث.
يؤدي حذف access_time_windows إلى تغيير حقول العضو الأخرى دون تغيير النوافذ.
إعادة إرسال المراجعة/الحمولة نفسها آمنة من التكرار.
تُرجع المراجعة نفسها مع حمولة مختلفة تعارضًا ولا تغيّر اللقطة.
يُبلَّغ عن مراجعة أقدم خارج الترتيب بأنها قديمة، ولا يمكنها إرجاع الحالة إلى الوراء.
تلغي [] الأحدث النوافذَ التي يملكها المصدر؛ ولا يُرسل أي شيء عند إخفاق الجلب من المصدر.
يخفق scope_key غير المعروف أو غير المعيَّن بشكل مغلق ويُنشئ تحذيرًا مرئيًا للمشغّل.
تعمل تنبيهات عمر المصدر وسياسة المصدر القديم المهيّأة عند العتبة المتفق عليها.
يتقارب مسارا webhook والتسوية الكاملة إلى اللقطة نفسها وترتيب المراجعات نفسه.
يصل التسليم المتسلسل إلى Door & Gate Access ضمن الهدف المتفق عليه.
يمكن للنافذة النشطة السماح بالباب الفعلي المعيَّن، لكن لا يمكنها تجاوز تعطيل المستخدم، أو blockAllAccess، أو الصيانة، أو Geofence.
قبل النافذة وخارجها وبعدها، تظل القواعد العادية والمنح الدائمة تسمح بوصول المستخدمين المؤهلين بخلاف ذلك.

{
  "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 مطلوب

مصفوفة من كائنات الأعضاء المراد حفظها. الحد الأقصى الموصى به: 1000 عنصر لكل طلب لتحقيق أفضل أداء. تقسّم API العناصر إلى دفعات تلقائيًا لمعالجتها. يجب أن يتضمن كل عنصر إما facility_id (مطلوب إذا لم تستخدم linking_identifier) أو linking_identifier (مطلوب إذا لم تستخدم facility_id).

عندما يتضمن العضو access_time_windows، يجب أن يتضمن أيضًا access_time_windows_revision. والمصفوفة لقطة كاملة من المصدر، وليست تصحيحًا جزئيًا. احذفها للحفاظ على اللقطة الحالية، أو أرسل [] بمراجعة أحدث لإلغاء جميع النوافذ التي يملكها المصدر. اقرأ دليل Access Time Windows قبل تفعيل هذا الحقل.

القيم المُرجعة

يُرجع رسالة بسيطة تؤكد عملية المزامنة.

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

الطلب

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_id string اختياري

المعرّف الفريد لتسجيل الدخول. اختياري - يُنشأ تلقائيًا من الزوج member_id وtimestamp إذا لم يُقدَّم.
member_id string مطلوب

المعرّف الفريد للعضو.
facility_id string أحدهماقدّم نوع معرّف المنشأة المهيّأ لتكاملك: استخدم facility_id لتكاملات الربط المباشر، أو linking_identifier لتكاملات معرّف الربط. لا ترسل كليهما؛ إذ تستخدم API نوع المعرّف المهيّأ لحساب الشريك الخاص بك وتتجاهل الآخر. اعرف المزيد

المعرّف الفريد للمنشأة من Performance Hub.
linking_identifier string أحدهماقدّم نوع معرّف المنشأة المهيّأ لتكاملك: استخدم facility_id لتكاملات الربط المباشر، أو 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_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 مطلوب

مصفوفة من كائنات تسجيل الدخول المراد حفظها. الحد الأقصى الموصى به: 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_id string مطلوب

المعرّف الفريد لوحدة التحكم في الباب/البوابة. احفظه في نظامك بعد اكتشافه واستخدمه عند استدعاء نقطة نهاية فتح القفل.
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_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"
}

عرض قائمة وحدات التحكم في الأبواب/البوابات

يُرجع وحدات التحكم في الأبواب/البوابات المتاحة لتكاملك.

إذا لم يُقدَّم facility_id ولا linking_identifier، تُرجع API وحدات التحكم في الأبواب/البوابات في جميع المنشآت المرتبطة بحساب الشريك الخاص بك.

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 لتكاملات الربط المباشر، أو linking_identifier لتكاملات معرّف الربط. لا ترسل كليهما؛ إذ تستخدم API نوع المعرّف المهيّأ لحساب الشريك الخاص بك وتتجاهل الآخر. اعرف المزيد

معرّف المنشأة في Performance Hub. استخدمه لتكاملات الربط المباشر.
linking_identifier string اختياري أحدهماقدّم نوع معرّف المنشأة المهيّأ لتكاملك: استخدم facility_id لتكاملات الربط المباشر، أو linking_identifier لتكاملات معرّف الربط. لا ترسل كليهما؛ إذ تستخدم API نوع المعرّف المهيّأ لحساب الشريك الخاص بك وتتجاهل الآخر. اعرف المزيد

معرّف المنشأة/الموقع الخاص بك. استخدمه عندما يكون تكاملك مهيّأً لاستخدام معرّفات الربط.

القيم المُرجعة

يُرجع مصفوفة من كائنات وحدات التحكم في الأبواب/البوابات.

الطلب

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"
    }
  ]
}

الحصول على حالة وحدة التحكم في الباب/البوابة

يسترجع آخر حالة معروفة والتهيئة الأساسية لوحدة تحكم واحدة في باب/بوابة.

قدّم معرّف منشأة حتى يتمكن Performance Hub من التحقق من أن الباب ينتمي إلى منشأة يمكن لتكاملك الوصول إليها.

المعلمات

door_id string مطلوب

معرّف وحدة التحكم في الباب/البوابة الذي تُرجعه نقطة نهاية القائمة.
facility_id string أحدهماقدّم نوع معرّف المنشأة المهيّأ لتكاملك: استخدم facility_id لتكاملات الربط المباشر، أو linking_identifier لتكاملات معرّف الربط. لا ترسل كليهما؛ إذ تستخدم API نوع المعرّف المهيّأ لحساب الشريك الخاص بك وتتجاهل الآخر. اعرف المزيد

معرّف المنشأة في Performance Hub. مطلوب لتكاملات الربط المباشر.
linking_identifier string أحدهماقدّم نوع معرّف المنشأة المهيّأ لتكاملك: استخدم facility_id لتكاملات الربط المباشر، أو linking_identifier لتكاملات معرّف الربط. لا ترسل كليهما؛ إذ تستخدم API نوع المعرّف المهيّأ لحساب الشريك الخاص بك وتتجاهل الآخر. اعرف المزيد

معرّف المنشأة لدى الشريك. مطلوب لتكاملات معرّف الربط.

القيم المُرجعة

يُرجع كائن وحدة التحكم في الباب/البوابة.

الطلب

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"
  }
}

فتح قفل وحدة التحكم في الباب/البوابة

يرسل أمر فتح القفل إلى وحدة التحكم في الباب/البوابة وينتظر أن يؤكد المرحّل الفعلي أنه فتح القفل.

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

المعلمات

door_id string مطلوب

معرّف وحدة التحكم في الباب/البوابة الذي تُرجعه نقطة نهاية القائمة.
facility_id string أحدهماقدّم نوع معرّف المنشأة المهيّأ لتكاملك: استخدم facility_id لتكاملات الربط المباشر، أو linking_identifier لتكاملات معرّف الربط. لا ترسل كليهما؛ إذ تستخدم API نوع المعرّف المهيّأ لحساب الشريك الخاص بك وتتجاهل الآخر. اعرف المزيد

معرّف المنشأة في Performance Hub. مطلوب لتكاملات الربط المباشر.
linking_identifier string أحدهماقدّم نوع معرّف المنشأة المهيّأ لتكاملك: استخدم facility_id لتكاملات الربط المباشر، أو linking_identifier لتكاملات معرّف الربط. لا ترسل كليهما؛ إذ تستخدم API نوع المعرّف المهيّأ لحساب الشريك الخاص بك وتتجاهل الآخر. اعرف المزيد

معرّف المنشأة لدى الشريك. مطلوب لتكاملات معرّف الربط.
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 - وحدة التحكم في الباب/البوابة غير متصلة أو بياناتها قديمة.
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 Access دون فتح القفل. لا يقيّم Performance Hub حالة العضوية أو ساعات الوصول أو قواعد الوصول الأخرى.

يظهر حدث الرفض في سجلات الوصول ضمن Door & Gate Access بالنتيجة Denied، مع اسم الشريك الخاص بك، والباب، ومعرّف العضو عند إرساله، ورمز السبب بصيغة مقروءة. على سبيل المثال، يظهر membership_expired بالصيغة "Membership Expired". ويُخزَّن reason_display_text وuser_email مع الحدث.

المعلمات

door_id string مطلوب

معرّف وحدة التحكم في الباب/البوابة الذي تُرجعه نقطة نهاية القائمة.
facility_id string أحدهماقدّم نوع معرّف المنشأة المهيّأ لتكاملك: استخدم facility_id لتكاملات الربط المباشر، أو linking_identifier لتكاملات معرّف الربط. لا ترسل كليهما؛ إذ تستخدم API نوع المعرّف المهيّأ لحساب الشريك الخاص بك وتتجاهل الآخر. اعرف المزيد

معرّف المنشأة في Performance Hub. مطلوب لتكاملات الربط المباشر.
linking_identifier string أحدهماقدّم نوع معرّف المنشأة المهيّأ لتكاملك: استخدم facility_id لتكاملات الربط المباشر، أو linking_identifier لتكاملات معرّف الربط. لا ترسل كليهما؛ إذ تستخدم API نوع المعرّف المهيّأ لحساب الشريك الخاص بك وتتجاهل الآخر. اعرف المزيد

معرّف المنشأة لدى الشريك. مطلوب لتكاملات معرّف الربط.
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 - لم يُعثر على وحدة التحكم في الباب/البوابة للمنشأة المرتبطة.

الطلب

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"
}

إعادة الإرسال المتكررة الآمنة (Idempotent replay)

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

كائن لقطة التقرير

السمات

facility_id string أحدهماقدّم نوع معرّف المنشأة المهيّأ لتكاملك: استخدم facility_id لتكاملات الربط المباشر، أو linking_identifier لتكاملات معرّف الربط. لا ترسل كليهما؛ إذ تستخدم API نوع المعرّف المهيّأ لحساب الشريك الخاص بك وتتجاهل الآخر. اعرف المزيد

المعرّف الفريد للمنشأة من Performance Hub.
linking_identifier string أحدهماقدّم نوع معرّف المنشأة المهيّأ لتكاملك: استخدم facility_id لتكاملات الربط المباشر، أو linking_identifier لتكاملات معرّف الربط. لا ترسل كليهما؛ إذ تستخدم API نوع المعرّف المهيّأ لحساب الشريك الخاص بك وتتجاهل الآخر. اعرف المزيد

قيمة المعرّف الفريد لكل موقع يستخدمها الشريك (مثل "Branch ID" و"Location Code" و"Store Number"). اعرف المزيد
start_date string مطلوب

تاريخ بداية فترة اللقطة بتنسيق YYYY-MM-DD.
end_date string مطلوب

تاريخ نهاية فترة اللقطة بتنسيق YYYY-MM-DD.
metrics object مطلوب

كائن المقاييس الذي يحتوي على بيانات الأعضاء والإيرادات للفترة.

كائن لقطة التقرير

{
  "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 مطلوب

مصفوفة من كائنات لقطات التقارير المراد حفظها. الحد الأقصى 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 Window

يخفق التحقق من النوافذ قبل كتابة اللقطة غير الصالحة. ومن الأسباب الشائعة التي لا تُجدي معها إعادة المحاولة:

غياب 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 (تعارض)

يتعارض الطلب مع الحالة الحالية للمورد. في التحكم في الوصول، قد يشمل ذلك وجود وحدة التحكم في الباب/البوابة في وضع الصيانة.

422 Unprocessable Entity (كيان غير قابل للمعالجة)

الطلب بتنسيق JSON صالح لكنه يخفق في التحقق الدلالي. أصلح البيانات قبل إعادة المحاولة.

429 Too Many Requests (طلبات كثيرة جدًا)

تجاوز التكامل حد المعدل الموثّق. أعِد المحاولة باستخدام التراجع الأُسّي.

500 Internal Server Error (خطأ داخلي في الخادم)

تعذّر على Performance Hub إكمال الطلب بسبب خطأ داخلي. أعِد المحاولة مع التراجع. وإذا استمرت المشكلة، فتواصل مع الدعم مع ذكر نقطة النهاية والطابع الزمني ونص الاستجابة.

503 Service Unavailable (الخدمة غير متاحة)

خدمة أو جهاز تعتمد عليه العملية غير متاح. في عمليات فتح أقفال وحدات التحكم في الأبواب/البوابات، قد يعني ذلك أن وحدة التحكم غير متصلة.

504 Gateway Timeout (انتهاء مهلة البوابة)

انتهت مهلة العملية. في عمليات فتح أقفال وحدات التحكم في الأبواب/البوابات، يعني ذلك أن فتح القفل لم يُؤكَّد قبل انتهاء فترة المهلة.

إدارة الإصدارات

يُحدَّد إصدار Partner API في عنوان URL. والإصدار الحالي هو:

سياسة التغيير

يسعى Performance Hub إلى إجراء تغييرات إضافية ومتوافقة مع الإصدارات السابقة كلما أمكن ذلك.

أمثلة على التغييرات المتوافقة مع الإصدارات السابقة:

إضافة حقل اختياري جديد إلى الطلب.
إضافة حقل جديد إلى الاستجابة.
إضافة نقطة نهاية جديدة.
إضافة قيمة تعداد جديدة حيث يُتوقع من العملاء التعامل مع القيم غير المعروفة.
تحسين رسائل التحقق دون تغيير عقد رموز الحالة.

access_time_windows وaccess_time_windows_revision حقلان إضافيان في طلب العضو. والعملاء الحاليون الذين يحذفونهما يُبقون لقطة Access Time Window المخزنة دون تغيير. وتحافظ قاعدة الحذف هذه على التوافق مع الإدراج أو التحديث الجزئي؛ فالحذف لا يعادل إرسال مصفوفة فارغة.

أمثلة على التغييرات الجذرية:

إزالة حقل أو إعادة تسميته.
تغيير نوع حقل.
جعل حقل طلب اختياري مطلوبًا.
إزالة نقطة نهاية.
تغيير معنى رمز حالة موجود أو reason خاص بمجال معين.

الإهمال

عندما يلزم إجراء تغيير جذري، يتجنب Performance Hub تغيير الإصدار الحالي في مكانه كلما أمكن ذلك. وبدلًا من ذلك، سنطرح إصدارًا جديدًا أو مسار ترحيل ونبلغ الشركاء المتأثرين بالتغيير.

يمكن أن تتضمن إشعارات الإهمال ما يلي:

إدخالًا في سجل التغييرات.
تواصلًا مباشرًا مع الشركاء.
ملاحظات في Partner Console.
إرشادات الترحيل في الوثائق.

توصيات للعملاء

أنشئ عملاء يتحملون التغييرات الإضافية:

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

بالنسبة إلى أقسام العضو ذات المراجعات مثل 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

فئات التغييرات

تستخدم الإدخالات المستقبلية الفئات التالية:

الإضافات - نقطة نهاية أو حقل أو دليل أو إمكانية جديدة.
التغييرات - تغيّر السلوك أو الوثائق دون إزالة الدعم.
الإهمال - تظل الميزة متاحة ولكن يوجد مسار ترحيل مخطط له.
الإزالة - أُزيلت ميزة أو نقطة نهاية.
الإصلاحات - إصلاح خطأ أو تصحيح في الوثائق.
الأمان - تغيير في المصادقة أو التفويض أو معالجة البيانات أو إدارة المفاتيح.

الإضافات

إضافة لقطات access_time_windows للأعضاء محايدة تجاه الموردين، تجمع بين نوافذ مطلقة ونوافذ أسبوعية متكررة.
إضافة دلالات الترتيب حسب access_time_windows_revision، وإعادة الإرسال الآمنة من التكرار، والتعارض، وتخطي البيانات القديمة، والإلغاء الصريح.
إضافة إرشادات حول المناطق الزمنية وفق IANA، والتوقيت الصيفي، والتعيين المنطقي لـ scope_key، وحداثة المصدر، وتطبيق المنتج، والاعتماد.

الإضافات

إضافة وثائق برنامج الشركاء التي تغطي أنواع الشركاء، والانضمام، وأفضل الممارسات، والجاهزية لبدء التشغيل الفعلي، والأخطاء، وإدارة الإصدارات، والدعم.
إضافة مسار مخصص لاستفسارات "كن شريكًا" للشركاء التقنيين والتجاريين المحتملين.
إضافة وثائق توضح كيفية ظهور تكاملات الشركاء المعتمدة داخل دليل شركاء Performance Hub في منصة Performance Hub الأساسية.

الإضافات

إضافة وثائق التحكم في الوصول لوحدات التحكم في الأبواب/البوابات، بما في ذلك عمليات عرض القائمة والحالة وفتح القفل.
إضافة وثائق سلوك فتح القفل المتزامن: لا تُرجع API نتيجة نجاح إلا بعد أن تؤكد وحدة التحكم في الموقع أن المرحّل فتح القفل فعليًا.
إضافة وثائق دعم المعلمة الاختيارية idempotency_key في طلبات فتح أقفال وحدات التحكم في الأبواب/البوابات.