본문으로 건너뛰기

예약/결제 제어

관리자의 예약/결제 조회, 취소, 변경, 대리 예약 API입니다. 모든 요청에 관리자 세션 쿠키가 필요합니다.

예약/결제 목록 조회​

GET /admin/reservations

지점의 예약/결제 현황을 조회합니다.

Headers​

이름필수설명
CookieO관리자 세션 쿠키

Query Parameters​

파라미터타입필수설명
branchStringO지점 영문명 (지점 코드 참고)
base_dateStringO기준 날짜 (yyyyMMdd)
base_hourStringO기준 시간 (0 ~ 23)
GET /api/admin/reservations?branch=Gwanghwamun&base_date=20260305&base_hour=14

Response​

{
  "status": "success",
  "errorType": null,
  "errorCode": null,
  "message": null,
  "data": {
    "booking": [
      { "id": "abc123", "time": "1-202603051400" }
    ],
    "paid": [
      { "id": "142", "time": "2-202603051500" },
      { "id": "142", "time": "2-202603051510" }
    ],
    "bookingMargin": ["1-202603051350"],
    "paidMargin": ["2-202603051450", "2-202603051530"],
    "disabledRooms": ["5"]
  }
}

data 필드

필드타입설명
bookingIdTime[]예약 진행 중 목록 (ID + 슬롯)
paidIdTime[]결제 완료 목록 (ID + 슬롯)
bookingMarginString[]예약 진행 중 마진 슬롯
paidMarginString[]결제 완료 마진 슬롯
disabledRoomsString[]비활성화된 룸 번호

IdTime

필드타입설명
idString예약/결제 ID (상세 조회에 사용)
timeString슬롯 ({room}-{YYYYMMDDHHmm})

예약/결제 상세 조회​

GET /admin/reservation/{id}

개별 예약/결제를 상세 조회합니다. dataType에 따라 응답 구조가 다릅니다.

Path Parameters​

파라미터타입필수설명
idStringO목록 조회에서 받은 ID

Response​

{
  "status": "success",
  "errorType": null,
  "errorCode": null,
  "message": null,
  "data": {
    "dataType": "paid",
    "paidName": "홍길동",
    "paidMobileNum": "01012345678",
    "paidEmail": "user@example.com",
    "paidStartDateTime": "202603051400",
    "paidEndDateTime": "202603051550",
    "paidBranchEng": "Gwanghwamun",
    "paidBranchKor": "광화문",
    "paidRoom": "1",
    "paidMachine": "Capsule A",
    "paidTotalAmount": "12000",
    "paidMethod": "카드",
    "paidDateTime": "202603051230"
  }
}

결제 완료 (dataType = "paid") 필드

필드타입Nullable설명
dataTypeStringN"paid"
paidNameStringN예약자 이름
paidMobileNumStringN휴대폰 번호
paidEmailStringY이메일
paidStartDateTimeStringN시작 시간
paidEndDateTimeStringN종료 시간
paidBranchEngStringN지점 영문명
paidBranchKorStringN지점 한글명
paidRoomStringN방 번호
paidMachineStringN머신(침대) 이름
paidTotalAmountStringN결제 금액
paidMethodStringN결제 수단
paidDateTimeStringN결제 완료 시간

예약 진행 중 (dataType = "booking") 필드

필드타입Nullable설명
dataTypeStringN"booking"
bookingTtlLongNRedis TTL (남은 초)
bookingStatusStringNbeforePaymentTab / paymentTab / waitingForDeposit
bookingBranchEngStringN지점 영문명
bookingBranchKorStringN지점 한글명
bookingRoomStringN방 번호
bookingMachineStringN머신 이름
bookingStartDateTimeStringN시작 시간
bookingEndDateTimeStringN종료 시간
bookingAmountStringY결제 금액
bookingNameStringY예약자 이름
bookingMobileNumStringY휴대폰 번호
bookingEmailStringY이메일
bookingVirtualaccountBankNameStringY가상계좌 은행명
bookingVirtualaccountAccountNumberStringY가상계좌 번호
bookingVirtualaccountDueDateStringY입금 기한

취소 (환불)​

DELETE /admin/reservation/{id}

진행 중인 예약을 취소하거나 결제 완료 건을 환불합니다.

Path Parameters​

파라미터타입필수설명
idStringO예약/결제 ID

Query Parameters​

파라미터타입필수설명
bookingStatusStringO상세 조회에서 확인한 현재 상태
가상계좌 입금 완료 후 환불

가상계좌 입금 완료 건을 취소할 경우 아래 추가 파라미터가 필수입니다:

파라미터타입필수설명
refundReceiveAccountBankStringO환불 은행 코드 (은행 코드 참고)
refundReceiveAccountNumberStringO환불 계좌번호
refundReceiveAccountHolderNameStringO예금주

Response​

{
  "status": "success",
  "errorType": null,
  "errorCode": null,
  "message": null,
  "data": null
}

변경​

PUT /admin/reservation/{payId}

결제 완료된 예약의 룸/시간을 변경합니다. 결제 금액은 변동되지 않습니다.

Path Parameters​

파라미터타입필수설명
payIdStringO결제 ID

Request Body​

파라미터타입필수설명
roomStringO변경할 방 번호 (최대 10자)
startDateTimeStringO변경할 시작 시간 (YYYYMMDDHHmm, 정확히 12자)
endDateTimeStringO변경할 종료 시간 (YYYYMMDDHHmm, 정확히 12자)
reasonStringX변경 사유 (최대 500자)
요청 예시
{
  "room": "3",
  "startDateTime": "202603051500",
  "endDateTime": "202603051700",
  "reason": "고객 요청으로 룸 변경"
}

Response​

{
  "status": "success",
  "errorType": null,
  "errorCode": null,
  "message": null,
  "data": null
}
최대 예약 시간

최대 예약 시간은 5시간입니다.

결제 없이 대리 예약​

관리자가 결제 없이 예약을 등록하는 2단계 프로세스입니다.

Step 1: 예약 시도​

POST /admin/reservation

파라미터타입필수설명
branchStringO지점 영문명 (지점 코드 참고)
roomintO방 번호
startDateTimeStringO시작 시간 (YYYYMMDDHHmm)
endDateTimeStringO종료 시간 (YYYYMMDDHHmm)
요청 예시
{
  "branch": "Gwanghwamun",
  "room": 1,
  "startDateTime": "202603051400",
  "endDateTime": "202603051600"
}

성공 시 ADMIN_PAY_SESSIONID 쿠키 발급 (5분 TTL).

Set-Cookie: ADMIN_PAY_SESSIONID=admin-abc123; Path=/; HttpOnly
{
  "status": "success",
  "errorType": null,
  "errorCode": null,
  "message": null,
  "data": null
}

Step 2: 예약 확정​

POST /admin/payment

Headers​

이름필수설명
Content-TypeOapplication/json
CookieOADMIN_PAY_SESSIONID (Step 1에서 발급)

Request Body​

파라미터타입필수설명
nameStringX예약자 이름 (최대 50자)
mobileNumStringX휴대폰 번호 (최대 20자)
emailStringX이메일 (최대 100자)
reasonStringX대리 예약 사유 (최대 500자)
정보

회원/비회원 모두 등록 가능합니다. 예약자 정보는 선택사항입니다.

요청 예시
{
  "name": "홍길동",
  "mobileNum": "01012345678",
  "email": null,
  "reason": "전화 예약 접수"
}
{
  "status": "success",
  "errorType": null,
  "errorCode": null,
  "message": null,
  "data": null
}

가상계좌 발급​

관리자가 가상계좌를 발급하는 2단계 프로세스입니다.

Step 1: 예약 시도​

위의 대리 예약 Step 1과 동일합니다.

Step 2: 가상계좌 발급​

POST /admin/v2/virtual-accounts

Headers​

이름필수설명
Content-TypeOapplication/json
CookieOADMIN_PAY_SESSIONID (Step 1에서 발급)

Request Body​

파라미터타입필수설명
amountintO결제 금액
orderNameStringO주문명 (1~100자)
nameStringO예약자 이름 (최대 100자)
mobileNumStringO휴대폰 번호
emailStringX이메일
bankCodeStringO은행 코드 (은행 코드 참고)
요청 예시
{
  "amount": 12000,
  "orderName": "광화문 1번방 14:00~16:00",
  "name": "홍길동",
  "mobileNum": "01012345678",
  "email": null,
  "bankCode": "88"
}
{
  "status": "success",
  "errorType": null,
  "errorCode": null,
  "message": null,
  "data": {
    "dataType": "virtualaccount"
  }
}
입금 기한

가상계좌 입금 기한은 10분입니다. 미입금 시 자동 취소됩니다 (Redis TTL 만료 → 네이버 예약 자동 취소).

예약 시도 취소​

DELETE /admin/reservation

관리자가 진행 중인 예약 시도를 취소하고 Redis 자원을 해제합니다. 대리 예약 또는 가상계좌 발급 진행 중 취소 시 사용합니다.

Headers​

이름필수설명
CookieOADMIN_PAY_SESSIONID

Response​

{
  "status": "success",
  "errorType": null,
  "errorCode": null,
  "message": null,
  "data": null
}