تسجيل محاولة وصول أو رفض

يسجّل محاولة وصول أو رفضًا قرّره نظامك مسبقًا. لا يتم الاتصال بوحدة التحكم في الباب/البوابة، ولا يُفتح قفل الباب.

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