출입 시도 또는 거부 기록

귀사의 시스템에서 이미 결정한 출입 시도 또는 거부를 기록합니다. Door/Gate Controller에는 연결하지 않으며 출입문은 잠금 해제되지 않습니다.

귀사의 시스템이 입장을 거부하거나, 잠금 해제 없이 시도를 Door & Gate Access 접근 로그에 표시해야 할 때 사용하십시오. Performance Hub는 멤버십 상태, 출입 시간 또는 기타 출입 규칙을 평가하지 않습니다.

거부 이벤트는 Door & Gate Access 접근 로그에 Denied 결과, 파트너 이름, 출입문, 회원 식별자(보낸 경우), 읽기 쉬운 형태의 사유 코드와 함께 표시됩니다. 예를 들어 membership_expired는 "Membership Expired"로 표시됩니다. reason_display_text와 user_email은 이벤트와 함께 저장됩니다.

매개변수

door_id string 필수

목록 엔드포인트에서 반환된 Door/Gate Controller 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 선택

최대 64자의 소문자 snake_case 사유 코드입니다. 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를 재전송하면 idempotent가 true로 설정된 200을 반환하며 다른 이벤트를 만들지 않습니다.

dry-run 키는 dry_run이 true로 설정된 200을 반환합니다. 아무것도 기록되지 않습니다.

일반적인 실패:

400 - 본문이 잘못되었거나, 거부에 reason이 없거나, 타임스탬프가 범위를 벗어났거나, facility_id / linking_identifier가 연결된 시설과 일치하지 않습니다.
403 - 키가 읽기 전용입니다.
403 integration_not_enabled - 시설에 대해 통합이 활성화되어 있지 않습니다. message에 사유가 표시됩니다.
404 - 연결된 시설에서 Door/Gate Controller를 찾을 수 없습니다.

요청

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
}