Mencatat upaya akses atau penolakan

Mencatat upaya akses atau penolakan yang telah diputuskan oleh sistem Anda. Door/Gate Controller tidak dihubungi, dan pintu tidak terbuka.

Gunakan ini ketika sistem Anda menolak masuk, atau ketika suatu upaya perlu muncul di Access Logs Door & Gate Access tanpa pembukaan kunci. Performance Hub tidak mengevaluasi status keanggotaan, jam akses, atau aturan akses lainnya.

Peristiwa yang ditolak muncul di Access Logs Door & Gate Access dengan hasil Denied, nama mitra Anda, pintunya, pengidentifikasi anggota jika Anda mengirimkannya, dan kode alasan dalam bentuk yang mudah dibaca. Misalnya, membership_expired ditampilkan 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 endpoint list.

• facility_id string salah satuBerikan jenis pengidentifikasi fasilitas yang dikonfigurasi untuk integrasi Anda: gunakan facility_id untuk integrasi direct-link, atau linking_identifier untuk integrasi linking-identifier. Jangan kirim keduanya; API menggunakan jenis pengidentifikasi yang dikonfigurasi untuk akun mitra Anda dan mengabaikan yang lainnya. Pelajari lebih lanjut

  ID fasilitas Performance Hub. Wajib untuk integrasi direct-link.

• linking_identifier string salah satuBerikan jenis pengidentifikasi fasilitas yang dikonfigurasi untuk integrasi Anda: gunakan facility_id untuk integrasi direct-link, atau linking_identifier untuk integrasi linking-identifier. Jangan kirim keduanya; API menggunakan jenis pengidentifikasi yang dikonfigurasi untuk akun mitra Anda dan mengabaikan yang lainnya. Pelajari lebih lanjut

  Pengidentifikasi fasilitas mitra. Wajib untuk integrasi linking-identifier.

• outcome string wajib

  denied atau attempted.

• reason string opsional

  Kode alasan dalam snake_case huruf kecil, hingga 64 karakter. Wajib jika outcome bernilai denied. Contoh: membership_expired.

• reason_display_text string opsional

  Alasan yang mudah dibaca, hingga 256 karakter. Contoh: Membership expired on 2026-04-01.

• member_id string opsional

  ID anggota mitra. Hilangkan jika kredensial tidak cocok dengan anggota mana pun, misalnya kartu yang tidak dikenal.

• user_email string opsional

  Email orang yang mencoba mengakses.

• timestamp string opsional

  Waktu terjadinya upaya, dalam format ISO 8601 dengan zona waktu. Contoh: 2026-05-18T10:15:30Z. Default-nya adalah waktu permintaan diterima. Tidak boleh lebih dari 5 menit di masa depan atau lebih lama dari 30 hari.

• idempotency_key string opsional

  Kunci perlindungan pemutaran ulang, hingga 128 karakter. Menggunakan kembali kunci yang sama untuk mitra, fasilitas, dan pintu yang sama akan mengembalikan hasil aslinya.

Hasil

Mengembalikan 201 saat peristiwa dicatat. Memutar ulang idempotency_key yang sama mengembalikan 200 dengan idempotent bernilai true dan tidak membuat peristiwa lain.

Kunci dry-run mengembalikan 200 dengan dry_run bernilai true. Tidak ada yang dicatat.

Kegagalan umum:

• 400 - isi permintaan tidak valid, penolakan tidak memiliki reason, stempel waktu di luar rentang, atau facility_id / linking_identifier tidak cocok dengan fasilitas yang tertaut.
• 403 - kunci bersifat read-only.
• 403 integration_not_enabled - integrasi Anda tidak diaktifkan untuk fasilitas tersebut. message memberikan alasannya.
• 404 - Door/Gate Controller tidak ditemukan untuk fasilitas yang tertaut.

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

Pemutaran ulang 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
}