解锁门/闸机控制器

向门/闸机控制器发送解锁命令，并等待物理继电器确认已解锁。

在调用此端点之前，您的系统必须确定该人员是否已获授权。Performance Hub 仅验证合作伙伴密钥、设施访问权限、门的归属和设备状态。

参数

door_id string 必填

列表端点返回的门/闸机控制器 ID。
facility_id string 二选一请提供为您的集成配置的设施标识符类型：直接关联集成使用 facility_id，关联标识符集成使用 linking_identifier。请勿同时发送两者；API 会使用为您的合作伙伴账户配置的标识符类型，并忽略另一个。了解详情

Performance Hub 设施 ID。直接关联集成必填。
linking_identifier string 二选一请提供为您的集成配置的设施标识符类型：直接关联集成使用 facility_id，关联标识符集成使用 linking_identifier。请勿同时发送两者；API 会使用为您的合作伙伴账户配置的标识符类型，并忽略另一个。了解详情

合作伙伴设施标识符。关联标识符集成必填。
member_id string 必填

合作伙伴会员 ID。用于审计日志记录和后续数据关联。
first_name string 必填

开门人员的名字。
last_name string 必填

开门人员的姓氏。
full_name string 可选

可选。如果省略，Performance Hub 会将 first_name 和 last_name 组合起来。
check_in_id string 可选

可选，来自您系统的签到 ID，用于关联。
idempotency_key string 可选

可选的重放保护密钥。对同一合作伙伴、设施和门重复使用相同的密钥时，如有现有结果，将返回该结果。

返回值

仅当设备确认继电器已实际解锁时才返回 200。门使用在 Performance Hub 设备管理中配置的保持时间；合作伙伴无法在单个请求中覆盖继电器时序。大多数确认应在 3-5 秒内完成。请将文档所述的超时视为明确的解锁失败，并仅按照您自己的安全规则进行重试。

常见失败情况：

403 integration_not_enabled：该设施未启用您的集成。
409 maintenance_mode_active：设施员工已为该门启用维护模式。
503 device_offline：门/闸机控制器处于离线状态或状态已过时。
504 unlock_confirmation_timeout：命令已发送，但在超时前未收到匹配的确认。

请求

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

响应

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

失败响应

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