개요
Core 서비스의 객실 도메인은 숙박 시설의 객실 및 객실 타입을 관리하는 API를 제공합니다. 객실 타입(RoomType)은 객실의 분류이며, 객실(Room)은 실제 물리적 객실을 나타냅니다. 객실 상태, 청소 상태, 점유 타임라인, 가격 정보 등을 관리할 수 있습니다.Queries
getSingleRoomType
특정 객실 타입의 상세 정보를 조회합니다.GraphQL Signature
파라미터
조회할 객실 타입 ID
응답
객실 타입 고유 식별자
객실 타입 이름 (예: “디럭스”, “스위트”)
객실 타입 설명
소속 숙박시설 ID
우선순위 (높을수록 우선)
기본 숙박 인원
최대 숙박 인원
해당 타입의 전체 객실 수
판매 중지된 객실 수
권한
- 로그인 필요
예제
getSingleRoom
특정 객실의 상세 정보를 조회합니다.GraphQL Signature
파라미터
조회할 객실 ID
응답
객실 고유 식별자
객실 번호/이름 (예: “101호”, “A동 202호”)
소속 객실 타입 ID
객실 상태:
NOT_USING: 미사용USING: 사용중LEFT: 퇴실SELECTED: 선택됨POWER_DOWN: 전원 차단
청소 상태:
CLEAN: 청소 완료DIRTY: 청소 필요CLEANING: 청소중NEED_CLEANING: 청소 요망URGENT_CLEANING: 긴급 청소 필요INSPECTION: 점검중NEED_INSPECTION: 점검 필요
판매 상태:
ALL: 전체 판매OTA: OTA 전용DISABLED: 판매 중지
계산된 복합 상태 (state, cleanState, 예약 정보를 종합):
available: 판매 가능availableDirty: 판매 가능 (청소 필요)cleaning: 청소중usingRental: 대실 사용중usingStay: 숙박 사용중reservedRental: 대실 예약reservedStay: 숙박 예약expired: 만료됨disabled: 판매 중지- 기타 다양한 상태 조합
현재 진행중인 예약 정보
다음 예정된 예약 정보
객실 편의시설 목록
권한
- 로그인 필요
예제
getRoomOccupancyTimelines
객실 점유 타임라인을 조회합니다. 특정 기간 동안의 객실 점유 상태를 확인할 수 있습니다.GraphQL Signature
파라미터
숙박시설 ID
필터 옵션:
roomTypeId: 특정 객실 타입으로 필터링roomId: 특정 객실으로 필터링sortKey: 정렬 기준 (기본값:startAt)sortDirection: 정렬 방향 (asc또는desc)
조회할 항목 수 (기본값: 20)
페이지네이션 커서
응답
타임라인 항목 배열
페이지네이션 정보
권한
- 숙박시설 관리 권한 필요
예제
Mutations
createRoomType
새로운 객실 타입을 생성합니다.GraphQL Signature
파라미터
객실 타입 생성 정보
객실 타입 이름 (예: “스탠다드”, “디럭스”, “스위트”)
- 제약: “일반객실”은 예약된 이름으로 사용 불가
소속 숙박시설 ID
객실 타입 설명
우선순위 (높을수록 우선)
기본 숙박 인원
최대 숙박 인원
객실 타입 별칭
권한
- 숙박시설 관리자(MANAGER) 권한 필요
- 활성화된 숙박시설만 가능
예제
에러 처리
DUPLICATED_DATA_FOUND
동일한 이름의 객실 타입이 이미 존재합니다.
DEFAULT_DATA_FOUND
“일반객실”은 예약된 이름으로 사용할 수 없습니다.
REQUIRED_ACTIVATED_ACCOMMODATION
활성화되지 않은 숙박시설에는 객실 타입을 생성할 수 없습니다.
updateRoomType
객실 타입 정보를 수정합니다.GraphQL Signature
파라미터
수정할 객실 타입 ID
객실 타입 이름
객실 타입 설명
우선순위
기본 숙박 인원
최대 숙박 인원
권한
- 숙박시설 관리자(MANAGER) 권한 필요
deleteRoomType
객실 타입을 삭제합니다.GraphQL Signature
파라미터
삭제할 객실 타입 ID
제약사항
- 해당 타입에 속한 객실이 있으면 삭제 불가
- 기본 객실 타입이면서 유일한 타입인 경우 삭제 불가
권한
- 숙박시설 관리자(MANAGER) 권한 필요
에러 처리
ROOM_TYPE_HAS_ROOM
해당 객실 타입에 속한 객실이 존재하여 삭제할 수 없습니다.
createRoom
새로운 객실을 생성합니다.GraphQL Signature
파라미터
객실 생성 정보
객실 번호/이름 (예: “101호”, “A동 202호”)
소속 숙박시설 ID
소속 객실 타입 ID (미지정시 기본 객실 타입 사용)
초기 객실 상태 (기본값:
NOT_USING)판매 상태 (기본값:
ALL)정렬 순서
우선순위
RCU(Room Control Unit) ID
CCU(Central Control Unit) ID
암호화 키
편의시설 목록
응답
자동 생성된 Mifare 카드 키
권한
- 숙박시설 관리자(MANAGER) 권한 필요
- 활성화된 숙박시설만 가능
예제
에러 처리
DUPLICATED_DATA_FOUND
동일한 이름의 객실이 이미 존재합니다.
INVALID_PARAMETER
편의시설 이름 또는 아이콘에 허용되지 않는 문자가 포함되어 있습니다.
updateRoom
객실 정보를 수정합니다.GraphQL Signature
파라미터
수정할 객실 ID
객실 번호/이름
객실 타입 ID
객실 상태
판매 상태
청소 상태
정렬 순서
우선순위
편의시설 목록
권한
- 숙박시설 스태프(STAFF) 이상 권한 필요
updateRooms
여러 객실을 일괄 수정합니다.GraphQL Signature
파라미터
수정할 객실 정보 배열
권한
- 숙박시설 관리자(MANAGER) 권한 필요
특징
- 일괄 처리를 위해 트랜잭션 사용
- 각 객실별 감사 로그 자동 기록
deleteRoom
객실을 삭제합니다.GraphQL Signature
파라미터
삭제할 객실 ID
권한
- 숙박시설 관리자(MANAGER) 권한 필요
setRoomState
객실 상태를 변경합니다.GraphQL Signature
파라미터
객실 ID
변경할 객실 상태:
NOT_USING: 미사용USING: 사용중LEFT: 퇴실SELECTED: 선택됨POWER_DOWN: 전원 차단
권한
- 숙박시설 스태프(STAFF) 이상 권한 필요
예제
setRoomCleanState
객실 청소 상태를 변경합니다.GraphQL Signature
파라미터
객실 ID
변경할 청소 상태:
CLEAN: 청소 완료DIRTY: 청소 필요CLEANING: 청소중NEED_CLEANING: 청소 요망URGENT_CLEANING: 긴급 청소 필요INSPECTION: 점검중NEED_INSPECTION: 점검 필요
권한
- 숙박시설 스태프(STAFF) 이상 권한 필요
setRoomStateByStaff
스태프가 청소 상태를 단계적으로 진행합니다 (DIRTY → CLEANING → CLEAN).GraphQL Signature
파라미터
객실 ID
동작
DIRTY→CLEANING: 청소 시작CLEANING→CLEAN: 청소 완료- 기타 상태에서는 오류 발생
권한
- 숙박시설 메이드(MAID) 이상 권한 필요
assignRoomRequest
예약에 대해 사용 가능한 객실을 자동으로 배정합니다.GraphQL Signature
파라미터
배정할 객실 타입 ID
객실 선택 방식:
priority: 우선순위 높은 객실 우선random: 무작위 선택updatedAt: 가장 오래 업데이트되지 않은 객실 우선
예약 타입 (
rental 또는 stay)사용 시작 일시
사용 종료 일시
예약 ID
배정 조건
- 객실 상태:
NOT_USING - 청소 상태:
CLEAN - 판매 상태:
ALL또는 예약 타입에 맞는 상태 - 카드 상태:
guest가 아님 - 해당 기간에 다른 예약 없음
권한
- 관리자(ADMIN) 권한 필요
예제
에러 처리
NO_AVAILABLE_ROOM
배정 가능한 객실이 없습니다.
INVALID_ORDER_BY_ASSIGN_REQUEST
유효하지 않은 orderBy 값입니다.
createRoomOccupancyTimeline
객실 점유 타임라인을 생성합니다. 특정 기간 동안 객실의 점유 상태를 기록합니다.GraphQL Signature
파라미터
객실 ID
점유 상태:
OCCUPIED: 점유됨DISABLED: 사용 중지
시작 일시
종료 일시
메모
재고 수량 포함 여부
연관된 예약 ID
제약사항
endAt은startAt보다 이후여야 함- 동일 기간에 동일 상태의 타임라인 중복 불가
권한
- 숙박시설 스태프(STAFF) 이상 권한 필요
예제
에러 처리
INVALID_PARAMETER
종료 일시가 시작 일시보다 이전입니다.
ROOM_OCCUPANCY_TIMELINE_DUPLICATED
동일 기간에 중복된 타임라인이 존재합니다.
updateRoomOccupancyTimeline
객실 점유 타임라인을 수정합니다.GraphQL Signature
파라미터
타임라인 ID
시작 일시
종료 일시
메모
권한
- 숙박시설 스태프(STAFF) 이상 권한 필요
deleteRoomOccupancyTimeline
객실 점유 타임라인을 삭제합니다.GraphQL Signature
파라미터
삭제할 타임라인 ID
권한
- 숙박시설 스태프(STAFF) 이상 권한 필요
createPrice
객실 타입의 가격 정보를 생성합니다.GraphQL Signature
파라미터
객실 타입 ID
가격 타입 (예:
rental, stay)시간대별 가격 정보:
startTime: 시작 시간endTime: 종료 시간price: 가격type: 타입
연관된 ARI 패키지 ID
제약사항
- 동일한 타입의 시간대가 겹치면 안 됨
- 동일한
priceType및ariPackageId조합 중복 불가
권한
- 숙박시설 관리자(MANAGER) 권한 필요
에러 처리
OVERLAPPING_PRICE_TIMES
시간대가 겹치는 가격 정보가 있습니다.
DUPLICATED_DATA_FOUND
동일한 가격 정보가 이미 존재합니다.
updatePrice
가격 정보를 수정합니다.GraphQL Signature
파라미터
수정할 가격 ID
가격 타입
시간대별 가격 정보
권한
- 숙박시설 관리자(MANAGER) 권한 필요
deletePrice
가격 정보를 삭제합니다.GraphQL Signature
파라미터
삭제할 가격 ID
권한
- 숙박시설 관리자(MANAGER) 권한 필요
Room Memo 관리
createRoomMemo
객실 메모를 생성합니다.updateRoomMemo
객실 메모를 수정합니다.setRoomMemo
객실 메모를 생성하거나 수정합니다 (upsert).deleteRoomMemo
객실 메모를 삭제합니다.Room Device 관리
createRoomDevice
객실 디바이스를 생성합니다.updateRoomDevice
객실 디바이스를 수정합니다.bulkUpdateRoomDevice
여러 객실 디바이스를 일괄 수정합니다.deleteRoomDevice
객실 디바이스를 삭제합니다.객실 상태 흐름
기본 객실 상태 (RoomState)
청소 상태 (CleanState)
복합 상태 (CalculatedState)
calculatedState는 다음 정보를 종합하여 계산됩니다:
- 객실 상태 (
state) - 청소 상태 (
cleanState) - 카드 상태 (
cardState) - 예약 정보 (
currentReservation,upcomingReservation) - 점유 타임라인 (
roomOccupancyTimeline)
주요 복합 상태
available: 판매 가능 (청소 완료, 사용 가능)availableDirty: 판매 가능하나 청소 필요cleaning: 청소중needCleaning: 청소 필요urgentCleaning: 긴급 청소 필요inspection: 점검중needInspection: 점검 필요usingRental: 대실 사용중usingStay: 숙박 사용중leftRental: 대실 퇴실leftStay: 숙박 퇴실reservedRental: 대실 예약reservedStay: 숙박 예약expired: 예약 만료expiredEst: 예약 만료 추정usingExpired: 사용중 (예약 만료)usingUnknown: 사용중 (예약 정보 없음)disabled: 판매 중지disabledSuspicious: 판매 중지 (카드 감지됨)powerDown: 전원 차단selected: 선택됨unknown: 알 수 없음
객실 타임라인
OccupancyStatus
객실 점유 타임라인의 상태:OCCUPIED: 예약으로 인한 점유DISABLED: 관리자가 설정한 사용 중지 기간
타임라인 사용 사례
- 예약 점유: 예약 생성 시 자동으로
OCCUPIED타임라인 생성 - 판매 중지: 보수 공사, 시설 점검 등으로
DISABLED타임라인 생성 - 재고 관리:
isIncludedToQuantity플래그로 판매 재고 수량 제어