Door/Gate Controller 잠금 해제

Door/Gate Controller에 잠금 해제 명령을 보내고 물리적 릴레이가 잠금 해제를 확인할 때까지 기다립니다.

이 엔드포인트를 호출하기 전에 귀사의 시스템에서 해당 사람이 승인되었는지 결정해야 합니다. Performance Hub는 파트너 키, 시설 액세스, 출입문 소유권, 기기 상태만 확인합니다.

매개변수

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는 파트너 계정에 구성된 식별자 유형을 사용하고 다른 하나는 무시합니다. 자세히 알아보기

파트너 시설 식별자입니다. 연결 식별자 통합에 필요합니다.
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 Device Management에 구성된 유지 시간을 사용하며, 파트너는 요청별로 릴레이 타이밍을 재정의할 수 없습니다. 대부분의 확인은 3-5초 이내에 완료됩니다. 문서화된 제한 시간 초과는 명시적인 잠금 해제 실패로 처리하고, 자체 안전 규칙에 따라서만 재시도하십시오.

일반적인 실패:

403 integration_not_enabled - 시설에 대해 통합이 활성화되어 있지 않습니다.
409 maintenance_mode_active - 시설 직원이 출입문에 유지 관리 모드를 활성화했습니다.
503 device_offline - Door/Gate Controller가 오프라인이거나 오래된 상태입니다.
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"
}