Ghi lại lượt thử hoặc lượt từ chối ra vào

Ghi lại một lượt thử hoặc lượt từ chối ra vào mà hệ thống của bạn đã quyết định. Door/Gate Controller không được liên hệ và cửa không mở khóa.

Sử dụng endpoint này khi hệ thống của bạn từ chối cho vào, hoặc khi một lượt thử cần xuất hiện trong Nhật ký truy cập của Door & Gate Access mà không mở khóa. Performance Hub không đánh giá trạng thái hội viên, giờ ra vào hoặc các quy tắc ra vào khác.

Một sự kiện bị từ chối xuất hiện trong Nhật ký truy cập của Door & Gate Access với kết quả Denied, tên đối tác của bạn, cửa, mã định danh hội viên khi bạn gửi và mã lý do ở dạng dễ đọc. Ví dụ: membership_expired được hiển thị là "Membership Expired". reason_display_text và user_email được lưu cùng với sự kiện.

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.
outcome string bắt buộc

denied hoặc attempted.
reason string tùy chọn

Mã lý do dạng snake_case chữ thường, tối đa 64 ký tự. Bắt buộc khi outcome là denied. Ví dụ: membership_expired.
reason_display_text string tùy chọn

Lý do ở dạng dễ đọc, tối đa 256 ký tự. Ví dụ: Membership expired on 2026-04-01.
member_id string tùy chọn

ID hội viên của đối tác. Bỏ qua trường này khi thông tin xác thực không khớp với hội viên nào, chẳng hạn một thẻ không xác định.
user_email string tùy chọn

Email của người đã thử ra vào.
timestamp string tùy chọn

Thời điểm diễn ra lượt thử, theo định dạng ISO 8601 có múi giờ. Ví dụ: 2026-05-18T10:15:30Z. Mặc định là thời điểm nhận được yêu cầu. Không được muộn hơn hiện tại quá 5 phút hoặc cũ hơn 30 ngày.
idempotency_key string tùy chọn

Khóa chống phát lại, tối đa 128 ký tự. 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ả ban đầu.

Giá trị trả về

Trả về 201 khi sự kiện được ghi lại. Gửi lại cùng một idempotency_key sẽ trả về 200 với idempotent được đặt thành true và không tạo thêm sự kiện nào.

Khóa dry-run trả về 200 với dry_run được đặt thành true. Không có gì được ghi lại.

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

400 - nội dung yêu cầu không hợp lệ, lượt từ chối không có reason, dấu thời gian nằm ngoài phạm vi, hoặc facility_id / linking_identifier không khớp với cơ sở đã liên kết.
403 - khóa là loại chỉ đọc.
403 integration_not_enabled - tích hợp của bạn chưa được bật cho cơ sở. message cho biết lý do.
404 - không tìm thấy Door/Gate Controller cho cơ sở đã liên kết.

Yêu cầu

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

Phản hồi

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

Phát lại idempotent

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