Mở khóa Door/Gate Controller

Gửi lệnh mở khóa đến Door/Gate Controller và chờ rơ-le vật lý xác nhận đã mở khóa.

Hệ thống của bạn phải quyết định người đó có được cấp phép hay không trước khi gọi endpoint này. Performance Hub chỉ xác minh khóa đối tác, quyền truy cập cơ sở, quyền sở hữu cửa và trạng thái thiết bị.

Tham số

door_id string bắt buộc

ID của Door/Gate Controller do endpoint liệt kê trả về.
facility_id string một trong haiCung cấp loại mã định danh cơ sở được cấu hình cho tích hợp của bạn: dùng facility_id cho tích hợp liên kết trực tiếp, hoặc linking_identifier cho tích hợp dùng mã định danh liên kết. Không gửi cả hai; API sử dụng loại mã định danh được cấu hình cho tài khoản đối tác của bạn và bỏ qua loại còn lại. Tìm hiểu thêm

ID cơ sở trong Performance Hub. Bắt buộc đối với tích hợp liên kết trực tiếp.
linking_identifier string một trong haiCung cấp loại mã định danh cơ sở được cấu hình cho tích hợp của bạn: dùng facility_id cho tích hợp liên kết trực tiếp, hoặc linking_identifier cho tích hợp dùng mã định danh liên kết. Không gửi cả hai; API sử dụng loại mã định danh được cấu hình cho tài khoản đối tác của bạn và bỏ qua loại còn lại. Tìm hiểu thêm

Mã định danh cơ sở của đối tác. Bắt buộc đối với tích hợp dùng mã định danh liên kết.
member_id string bắt buộc

ID hội viên của đối tác. Giá trị này được dùng cho nhật ký kiểm toán và liên kết dữ liệu sau này.
first_name string bắt buộc

Tên của người mở cửa.
last_name string bắt buộc

Họ của người mở cửa.
full_name string tùy chọn

Không bắt buộc. Nếu bỏ qua, Performance Hub sẽ ghép first_name và last_name.
check_in_id string tùy chọn

ID check-in không bắt buộc từ hệ thống của bạn để đối chiếu.
idempotency_key string tùy chọn

Khóa chống phát lại không bắt buộc. Dùng lại cùng một khóa cho cùng đối tác, cơ sở và cửa sẽ trả về kết quả hiện có nếu có.

Giá trị trả về

Chỉ trả về 200 khi thiết bị xác nhận rơ-le đã thực sự mở khóa. Cửa sử dụng thời gian giữ được cấu hình trong Quản lý thiết bị của Performance Hub; đối tác không thể ghi đè thời gian rơ-le cho từng yêu cầu. Hầu hết các xác nhận sẽ hoàn tất trong 3-5 giây. Hãy coi trường hợp hết thời gian chờ được nêu trong tài liệu là một lần mở khóa thất bại rõ ràng và chỉ thử lại theo các quy tắc an toàn của riêng bạn.

Các lỗi thường gặp:

403 integration_not_enabled - tích hợp của bạn chưa được bật cho cơ sở.
409 maintenance_mode_active - nhân viên cơ sở đã bật chế độ bảo trì cho cửa.
503 device_offline - Door/Gate Controller đang ngoại tuyến hoặc dữ liệu đã cũ.
504 unlock_confirmation_timeout - lệnh đã được gửi nhưng không nhận được xác nhận tương ứng trước khi hết thời gian chờ.

Yêu cầu

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

Phản hồi

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

Phản hồi lỗi

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