记录访问尝试或拒绝

记录您的系统已作出决定的访问尝试或拒绝。此操作不会联系门/闸机控制器，门也不会解锁。

当您的系统拒绝进入，或者某次尝试需要在不解锁的情况下显示在 Door & Gate Access 访问日志中时，请使用此端点。Performance Hub 不会评估会员状态、访问时间或其他访问规则。

被拒绝的事件会显示在 Door & Gate Access 访问日志中，其中包含 Denied 结果、您的合作伙伴名称、门、会员标识符（如果您发送了该标识符），以及以易读形式显示的原因代码。例如，membership_expired 显示为“Membership Expired”。reason_display_text 和 user_email 会与事件一起存储。

参数

door_id string 必填

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

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

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

denied 或 attempted。
reason string 可选

小写 snake_case 格式的原因代码，最多 64 个字符。当 outcome 为 denied 时必填。示例：membership_expired。
reason_display_text string 可选

易读的原因说明，最多 256 个字符。示例：Membership expired on 2026-04-01。
member_id string 可选

合作伙伴会员 ID。如果凭据未匹配到任何会员（例如未知卡片），请省略此参数。
user_email string 可选

尝试访问的人员的电子邮件地址。
timestamp string 可选

尝试发生的时间，采用带时区的 ISO 8601 格式。示例：2026-05-18T10:15:30Z。默认为收到请求的时间。不得晚于当前时间 5 分钟以上，也不得早于 30 天前。
idempotency_key string 可选

重放保护密钥，最多 128 个字符。对同一合作伙伴、设施和门重复使用相同的密钥将返回原始结果。

返回值

记录事件后返回 201。重放相同的 idempotency_key 将返回 200，并将 idempotent 设置为 true，不会创建新事件。

dry-run 密钥返回 200，并将 dry_run 设置为 true。不会记录任何内容。

常见失败情况：

400：请求正文无效、拒绝事件缺少 reason、时间戳超出范围，或 facility_id / linking_identifier 与已关联的设施不匹配。
403：密钥为只读密钥。
403 integration_not_enabled：该设施未启用您的集成。message 会说明原因。
404：在已关联的设施中未找到该门/闸机控制器。

请求

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

响应

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

幂等重放

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