Buka kunci Door/Gate Controller

Menghantar arahan buka kunci kepada Door/Gate Controller dan menunggu geganti fizikal mengesahkan bahawa ia telah dibuka kunci.

Sistem anda mesti memutuskan sama ada orang itu dibenarkan sebelum memanggil titik akhir ini. Performance Hub hanya mengesahkan kunci rakan kongsi, akses kemudahan, pemilikan pintu dan keadaan peranti.

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

ID ahli rakan kongsi. Ini digunakan untuk pengelogan audit dan pemautan data kemudian.
first_name string wajib

Nama pertama orang yang membuka pintu.
last_name string wajib

Nama akhir orang yang membuka pintu.
full_name string pilihan

Pilihan. Jika ditinggalkan, Performance Hub menggabungkan first_name dan last_name.
check_in_id string pilihan

ID daftar masuk pilihan daripada sistem anda untuk korelasi.
idempotency_key string pilihan

Kunci perlindungan main semula pilihan. Menggunakan semula kunci yang sama untuk rakan kongsi, kemudahan dan pintu yang sama mengembalikan hasil sedia ada apabila tersedia.

Nilai pulangan

Mengembalikan 200 hanya apabila peranti mengesahkan geganti telah dibuka kunci secara fizikal. Pintu menggunakan masa tahan yang dikonfigurasikan dalam Pengurusan Peranti Performance Hub; rakan kongsi tidak boleh mengatasi pemasaan geganti bagi setiap permintaan. Kebanyakan pengesahan sepatutnya selesai dalam 3-5 saat. Anggap tamat masa yang didokumenkan sebagai buka kunci yang gagal secara jelas dan cuba semula hanya mengikut peraturan keselamatan anda sendiri.

Kegagalan biasa:

403 integration_not_enabled - integrasi anda tidak didayakan untuk kemudahan tersebut.
409 maintenance_mode_active - kakitangan kemudahan telah mendayakan mod penyelenggaraan untuk pintu tersebut.
503 device_offline - Door/Gate Controller berada di luar talian atau datanya lapuk.
504 unlock_confirmation_timeout - arahan telah dihantar tetapi tiada pengesahan sepadan diterima sebelum tamat masa.

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