บันทึกความพยายามในการเข้าถึงหรือการปฏิเสธ

บันทึกความพยายามในการเข้าถึงหรือการปฏิเสธที่ระบบของคุณตัดสินไว้แล้ว ระบบจะไม่ติดต่อ Door/Gate Controller และประตูจะไม่ปลดล็อก

ใช้ปลายทางนี้เมื่อระบบของคุณปฏิเสธการเข้า หรือเมื่อต้องการให้ความพยายามปรากฏในบันทึกการเข้าถึงของ Door & Gate Access โดยไม่มีการปลดล็อก Performance Hub ไม่ได้ประเมินสถานะสมาชิก ชั่วโมงการเข้าถึง หรือกฎการเข้าถึงอื่น ๆ

เหตุการณ์ที่ถูกปฏิเสธจะปรากฏในบันทึกการเข้าถึงของ Door & Gate Access พร้อมผลลัพธ์ Denied ชื่อพาร์ทเนอร์ของคุณ ประตู ตัวระบุสมาชิกเมื่อคุณส่งมา และรหัสเหตุผลในรูปแบบที่อ่านได้ ตัวอย่างเช่น membership_expired จะแสดงเป็น "Membership Expired" ระบบจะจัดเก็บ reason_display_text และ user_email ไว้พร้อมกับเหตุการณ์

พารามิเตอร์

• door_id string จำเป็น

  ID ของ Door/Gate Controller ที่ส่งคืนจากปลายทางแสดงรายการ

• facility_id string อย่างใดอย่างหนึ่งระบุประเภทตัวระบุสถานที่ที่กำหนดค่าไว้สำหรับการผสานรวมของคุณ: ใช้ facility_id สำหรับการผสานรวมแบบ Direct Link หรือใช้ linking_identifier สำหรับการผสานรวมแบบ Linking Identifier อย่าส่งทั้งสองค่า API จะใช้ประเภทตัวระบุที่กำหนดค่าไว้สำหรับบัญชีพาร์ทเนอร์ของคุณและละเว้นอีกค่าหนึ่ง ดูข้อมูลเพิ่มเติม

  ID สถานที่ของ 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 ไม่บังคับ

  ID สมาชิกของพาร์ทเนอร์ ให้เว้นไว้เมื่อข้อมูลประจำตัวไม่ตรงกับสมาชิกรายใด เช่น บัตรที่ไม่รู้จัก

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

การส่งซ้ำแบบ Idempotent

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