Rekodkan percubaan atau penafian akses

Merekodkan percubaan atau penafian akses yang telah pun diputuskan oleh sistem anda. Door/Gate Controller tidak dihubungi dan pintu tidak dibuka kunci.

Gunakan ini apabila sistem anda menolak kemasukan, atau apabila sesuatu percubaan patut dipaparkan dalam Access Logs Door & Gate Access tanpa buka kunci. Performance Hub tidak menilai status keahlian, waktu akses atau peraturan akses lain.

Peristiwa yang ditolak dipaparkan dalam Access Logs Door & Gate Access dengan hasil Denied, nama rakan kongsi anda, pintu, pengecam ahli apabila anda menghantarnya dan kod sebab dalam bentuk yang boleh dibaca. Contohnya, membership_expired dipaparkan sebagai "Membership Expired". reason_display_text dan user_email disimpan bersama peristiwa tersebut.

Parameter

door_id string wajib

ID Door/Gate Controller yang dikembalikan oleh titik akhir senarai.
facility_id string salah satuBerikan jenis pengecam kemudahan yang dikonfigurasikan untuk integrasi anda: gunakan facility_id untuk integrasi Direct Link, atau linking_identifier untuk integrasi Linking Identifier. Jangan hantar kedua-duanya; API menggunakan jenis pengecam yang dikonfigurasikan untuk akaun rakan kongsi anda dan mengabaikan yang satu lagi. Ketahui lebih lanjut

ID kemudahan Performance Hub. Diperlukan untuk integrasi Direct Link.
linking_identifier string salah satuBerikan jenis pengecam kemudahan yang dikonfigurasikan untuk integrasi anda: gunakan facility_id untuk integrasi Direct Link, atau linking_identifier untuk integrasi Linking Identifier. Jangan hantar kedua-duanya; API menggunakan jenis pengecam yang dikonfigurasikan untuk akaun rakan kongsi anda dan mengabaikan yang satu lagi. Ketahui lebih lanjut

Pengecam kemudahan rakan kongsi. Diperlukan untuk integrasi Linking Identifier.
outcome string wajib

denied atau attempted.
reason string pilihan

Kod sebab snake_case huruf kecil, sehingga 64 aksara. Diperlukan apabila outcome ialah denied. Contoh: membership_expired.
reason_display_text string pilihan

Sebab yang boleh dibaca oleh manusia, sehingga 256 aksara. Contoh: Membership expired on 2026-04-01.
member_id string pilihan

ID ahli rakan kongsi. Tinggalkannya apabila kelayakan tidak sepadan dengan mana-mana ahli, seperti kad yang tidak dikenali.
user_email string pilihan

E-mel orang yang cuba mendapatkan akses.
timestamp string pilihan

Masa percubaan berlaku, dalam format ISO 8601 dengan zon waktu. Contoh: 2026-05-18T10:15:30Z. Lalai kepada masa permintaan diterima. Tidak boleh lebih daripada 5 minit pada masa hadapan atau lebih lama daripada 30 hari.
idempotency_key string pilihan

Kunci perlindungan main semula, sehingga 128 aksara. Menggunakan semula kunci yang sama untuk rakan kongsi, kemudahan dan pintu yang sama mengembalikan hasil asal.

Nilai pulangan

Mengembalikan 201 apabila peristiwa direkodkan. Memainkan semula idempotency_key yang sama mengembalikan 200 dengan idempotent ditetapkan kepada true dan tidak mencipta peristiwa lain.

Kunci dry-run mengembalikan 200 dengan dry_run ditetapkan kepada true. Tiada apa-apa yang direkodkan.

Kegagalan biasa:

400 - badan permintaan tidak sah, penafian tiada reason, cap masa di luar julat, atau facility_id / linking_identifier tidak sepadan dengan kemudahan yang dipautkan.
403 - kunci adalah read-only.
403 integration_not_enabled - integrasi anda tidak didayakan untuk kemudahan tersebut. message memberikan sebabnya.
404 - Door/Gate Controller tidak ditemui untuk kemudahan yang dipautkan.

Permintaan

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

Respons

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

Main semula idempoten

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