Membuka kunci Door/Gate Controller

Mengirimkan perintah buka kunci ke Door/Gate Controller dan menunggu relai fisik mengonfirmasi bahwa kunci telah terbuka.

Sistem Anda harus memutuskan apakah orang tersebut berwenang sebelum memanggil endpoint ini. Performance Hub hanya memverifikasi kunci mitra, akses fasilitas, kepemilikan pintu, dan status perangkat.

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.
member_id string wajib

ID anggota mitra. Ini digunakan untuk pencatatan audit dan penautan data selanjutnya.
first_name string wajib

Nama depan orang yang membuka pintu.
last_name string wajib

Nama belakang orang yang membuka pintu.
full_name string opsional

Opsional. Jika dihilangkan, Performance Hub menggabungkan first_name dan last_name.
check_in_id string opsional

ID check-in opsional dari sistem Anda untuk korelasi.
idempotency_key string opsional

Kunci perlindungan pemutaran ulang opsional. Menggunakan kembali kunci yang sama untuk mitra, fasilitas, dan pintu yang sama akan mengembalikan hasil yang sudah ada jika tersedia.

Hasil

Mengembalikan 200 hanya jika perangkat mengonfirmasi bahwa relai secara fisik telah membuka kunci. Pintu menggunakan waktu tahan yang dikonfigurasi di Manajemen Perangkat Performance Hub; mitra tidak dapat mengganti pengaturan waktu relai per permintaan. Sebagian besar konfirmasi seharusnya selesai dalam 3-5 detik. Perlakukan batas waktu yang terdokumentasi sebagai buka kunci yang gagal secara eksplisit, dan coba ulang hanya sesuai dengan aturan keselamatan Anda sendiri.

Kegagalan umum:

403 integration_not_enabled - integrasi Anda tidak diaktifkan untuk fasilitas tersebut.
409 maintenance_mode_active - staf fasilitas telah mengaktifkan mode pemeliharaan untuk pintu tersebut.
503 device_offline - Door/Gate Controller sedang offline atau datanya usang.
504 unlock_confirmation_timeout - perintah telah dikirim tetapi tidak ada konfirmasi yang cocok diterima sebelum batas waktu.

Permintaan

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

Respons

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

Respons kegagalan

{
  "status": "failed",
  "reason": "device_offline",
  "door_id": "00000000000000000000000000000007",
  "facility_id": "550e8400-e29b-41d4-a716-446655440000",
  "event_id": "00000000-0000-0000-0000-000000000045"
}