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

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

يجب أن يحدد نظامك ما إذا كان الشخص مخوّلًا قبل استدعاء نقطة النهاية هذه. لا يتحقق 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"
}