도어락 제어

SSE(Server-Sent Events) 기반 비동기 도어락 해제 API입니다.

해제 흐름

---

V2 도어락 해제 요청

POST /door/v2/unlock

비동기로 도어락 해제를 요청합니다. 응답으로 requestId를 받고, SSE로 결과를 구독합니다.

Headers

이름	필수	설명
Content-Type	O	application/json

Request Body

파라미터	타입	필수	설명
branch	String	O	지점 영문명 (지점 코드 참고)
doorlockType	String	O	"front" (현관) 또는 "room" (룸)
key	String	O	도어락 인증키 (doorlockKey)

요청 예시

{
  "branch": "Gwanghwamun",
  "doorlockType": "front",
  "key": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

doorlockKey

doorlockKey는 결제 확인 성공 시 생성되는 UUID입니다. 카드 결제는 즉시, 가상계좌는 입금 완료 후 생성됩니다.

Response

200 성공

{
  "status": "success",
  "errorType": null,
  "errorCode": null,
  "message": null,
  "data": {
    "requestId": "req-20260305-abc123"
  }
}

data 필드

필드	타입	설명
requestId	String	SSE 구독에 사용할 요청 ID

400 검증 실패

{
  "status": "error",
  "errorType": "ResourceNotExistException",
  "errorCode": null,
  "message": "유효하지 않은 도어락 키입니다.",
  "data": null
}

410 시간 초과

예약 시간 외 접근 시:

{
  "status": "error",
  "errorType": "ResourceValidTimePassedException",
  "errorCode": null,
  "message": "도어락 해제 가능 시간이 아닙니다.",
  "data": null
}

해제 가능 시간

• 예약 시작 2분 전부터 해제 가능
• 예약 종료 2분 전까지 해제 가능

---

SSE 결과 구독

GET /door/v2/unlock/subscribe

도어락 해제 결과를 실시간으로 수신합니다. 7초 타임아웃.

Query Parameters

파라미터	타입	필수	설명
requestId	String	O	해제 요청에서 받은 ID
key	String	O	도어락 인증키 (doorlockKey)

GET /api/door/v2/unlock/subscribe?requestId=req-20260305-abc123&key=a1b2c3d4-...

Response

Content-Type: text/event-stream

SSE 이벤트

이벤트명	설명
door-result	도어락 해제 결과

해제 성공

event: door-result
data: {"status":"SUCCESS","device":"front","failoverKey":null}

해제 실패 (PIN 제공)

해제 실패 시 failoverKey(PIN 코드)가 포함됩니다:

event: door-result
data: {"status":"FAILED","device":"room_1","failoverKey":"1234"}

503 타임아웃

7초 내 응답이 없으면 SSE 연결이 종료됩니다:

{
  "status": "error",
  "errorType": "AsyncRequestTimeoutException",
  "errorCode": null,
  "message": "요청 시간이 초과되었습니다.",
  "data": null
}

door-result 필드

필드	타입	Nullable	설명
status	String	N	SUCCESS / FAILED / TIMEOUT
device	String	Y	도어 디바이스명 (예: front, room_1)
failoverKey	String	Y	실패 시 PIN 코드 (fallback)

Failover

도어락 해제 실패 시 PIN 코드가 failoverKey로 제공됩니다. 클라이언트는 이 PIN을 사용자에게 안내하여 수동 해제를 유도합니다.

---

도어락 타입

타입	대상	동작
front	출입문	지점의 모든 front 도어 동시 해제
room	객실문	예약된 특정 룸만 해제

---

V1 도어락 해제 (Deprecated)

POST /door/unlock

Deprecated

V1 동기 방식은 2026-01-31에 종료되었습니다. V2를 사용하세요.