Skip to main content

개요

Core 서비스의 객실 도메인은 숙박 시설의 객실 및 객실 타입을 관리하는 API를 제공합니다. 객실 타입(RoomType)은 객실의 분류이며, 객실(Room)은 실제 물리적 객실을 나타냅니다. 객실 상태, 청소 상태, 점유 타임라인, 가격 정보 등을 관리할 수 있습니다.

Queries

getSingleRoomType

특정 객실 타입의 상세 정보를 조회합니다.

GraphQL Signature

파라미터

ID!
required
조회할 객실 타입 ID

응답

ID!
객실 타입 고유 식별자
String!
객실 타입 이름 (예: “디럭스”, “스위트”)
String
객실 타입 설명
ID!
소속 숙박시설 ID
Int
우선순위 (높을수록 우선)
Int
기본 숙박 인원
Int
최대 숙박 인원
Int
해당 타입의 전체 객실 수
Int
판매 중지된 객실 수

권한

  • 로그인 필요

예제


getSingleRoom

특정 객실의 상세 정보를 조회합니다.

GraphQL Signature

파라미터

ID!
required
조회할 객실 ID

응답

ID!
객실 고유 식별자
String!
객실 번호/이름 (예: “101호”, “A동 202호”)
ID!
소속 객실 타입 ID
RoomState
객실 상태: - NOT_USING: 미사용 - USING: 사용중 - LEFT: 퇴실 - SELECTED: 선택됨 - POWER_DOWN: 전원 차단
CleanState
청소 상태: - CLEAN: 청소 완료 - DIRTY: 청소 필요 - CLEANING: 청소중 - NEED_CLEANING: 청소 요망 - URGENT_CLEANING: 긴급 청소 필요 - INSPECTION: 점검중 - NEED_INSPECTION: 점검 필요
SaleState
판매 상태: - ALL: 전체 판매 - OTA: OTA 전용 - DISABLED: 판매 중지
CalculatedState
계산된 복합 상태 (state, cleanState, 예약 정보를 종합): - available: 판매 가능 - availableDirty: 판매 가능 (청소 필요) - cleaning: 청소중 - usingRental: 대실 사용중 - usingStay: 숙박 사용중 - reservedRental: 대실 예약 - reservedStay: 숙박 예약 - expired: 만료됨 - disabled: 판매 중지 - 기타 다양한 상태 조합
Reservation
현재 진행중인 예약 정보
Reservation
다음 예정된 예약 정보
[Amenity]
객실 편의시설 목록

권한

  • 로그인 필요

예제


getRoomOccupancyTimelines

객실 점유 타임라인을 조회합니다. 특정 기간 동안의 객실 점유 상태를 확인할 수 있습니다.

GraphQL Signature

파라미터

ID!
required
숙박시설 ID
RoomOccupancyTimelineFilterInput
필터 옵션: - roomTypeId: 특정 객실 타입으로 필터링 - roomId: 특정 객실으로 필터링 - sortKey: 정렬 기준 (기본값: startAt) - sortDirection: 정렬 방향 (asc 또는 desc)
Int
조회할 항목 수 (기본값: 20)
String
페이지네이션 커서

응답

[Edge]
타임라인 항목 배열
PageInfo
페이지네이션 정보

권한

  • 숙박시설 관리 권한 필요

예제


Mutations

createRoomType

새로운 객실 타입을 생성합니다.

GraphQL Signature

파라미터

CreateRoomTypeInput!
required
객실 타입 생성 정보
String!
required
객실 타입 이름 (예: “스탠다드”, “디럭스”, “스위트”)
ID!
required
소속 숙박시설 ID
String
객실 타입 설명
Int
우선순위 (높을수록 우선)
Int
기본 숙박 인원
Int
최대 숙박 인원
String
객실 타입 별칭

권한

  • 숙박시설 관리자(MANAGER) 권한 필요
  • 활성화된 숙박시설만 가능

예제

에러 처리

동일한 이름의 객실 타입이 이미 존재합니다.
활성화되지 않은 숙박시설에는 객실 타입을 생성할 수 없습니다.

updateRoomType

객실 타입 정보를 수정합니다.

GraphQL Signature

파라미터

ID!
required
수정할 객실 타입 ID
String
객실 타입 이름
String
객실 타입 설명
Int
우선순위
Int
기본 숙박 인원
Int
최대 숙박 인원

권한

  • 숙박시설 관리자(MANAGER) 권한 필요

deleteRoomType

객실 타입을 삭제합니다.

GraphQL Signature

파라미터

ID!
required
삭제할 객실 타입 ID

제약사항

  • 해당 타입에 속한 객실이 있으면 삭제 불가
  • 기본 객실 타입이면서 유일한 타입인 경우 삭제 불가

권한

  • 숙박시설 관리자(MANAGER) 권한 필요

에러 처리

해당 객실 타입에 속한 객실이 존재하여 삭제할 수 없습니다.

createRoom

새로운 객실을 생성합니다.

GraphQL Signature

파라미터

CreateRoomInput!
required
객실 생성 정보
String!
required
객실 번호/이름 (예: “101호”, “A동 202호”)
ID!
required
소속 숙박시설 ID
ID
소속 객실 타입 ID (미지정시 기본 객실 타입 사용)
RoomState
초기 객실 상태 (기본값: NOT_USING)
SaleState
판매 상태 (기본값: ALL)
Int
정렬 순서
Int
우선순위
String
RCU(Room Control Unit) ID
String
CCU(Central Control Unit) ID
String
암호화 키
[AmenityInput]
편의시설 목록

응답

String
자동 생성된 Mifare 카드 키

권한

  • 숙박시설 관리자(MANAGER) 권한 필요
  • 활성화된 숙박시설만 가능

예제

에러 처리

동일한 이름의 객실이 이미 존재합니다.
편의시설 이름 또는 아이콘에 허용되지 않는 문자가 포함되어 있습니다.

updateRoom

객실 정보를 수정합니다.

GraphQL Signature

파라미터

ID!
required
수정할 객실 ID
String
객실 번호/이름
ID
객실 타입 ID
RoomState
객실 상태
SaleState
판매 상태
CleanState
청소 상태
Int
정렬 순서
Int
우선순위
[AmenityInput]
편의시설 목록

권한

  • 숙박시설 스태프(STAFF) 이상 권한 필요

updateRooms

여러 객실을 일괄 수정합니다.

GraphQL Signature

파라미터

[UpdateRoomInput!]!
required
수정할 객실 정보 배열

권한

  • 숙박시설 관리자(MANAGER) 권한 필요

특징

  • 일괄 처리를 위해 트랜잭션 사용
  • 각 객실별 감사 로그 자동 기록

deleteRoom

객실을 삭제합니다.

GraphQL Signature

파라미터

ID!
required
삭제할 객실 ID

권한

  • 숙박시설 관리자(MANAGER) 권한 필요

setRoomState

객실 상태를 변경합니다.

GraphQL Signature

파라미터

ID!
required
객실 ID
RoomState!
required
변경할 객실 상태: - NOT_USING: 미사용 - USING: 사용중 - LEFT: 퇴실 - SELECTED: 선택됨 - POWER_DOWN: 전원 차단

권한

  • 숙박시설 스태프(STAFF) 이상 권한 필요

예제


setRoomCleanState

객실 청소 상태를 변경합니다.

GraphQL Signature

파라미터

ID!
required
객실 ID
CleanState!
required
변경할 청소 상태: - CLEAN: 청소 완료 - DIRTY: 청소 필요 - CLEANING: 청소중 - NEED_CLEANING: 청소 요망 - URGENT_CLEANING: 긴급 청소 필요 - INSPECTION: 점검중 - NEED_INSPECTION: 점검 필요

권한

  • 숙박시설 스태프(STAFF) 이상 권한 필요

setRoomStateByStaff

스태프가 청소 상태를 단계적으로 진행합니다 (DIRTY → CLEANING → CLEAN).

GraphQL Signature

파라미터

ID!
required
객실 ID

동작

  • DIRTYCLEANING: 청소 시작
  • CLEANINGCLEAN: 청소 완료
  • 기타 상태에서는 오류 발생

권한

  • 숙박시설 메이드(MAID) 이상 권한 필요

assignRoomRequest

예약에 대해 사용 가능한 객실을 자동으로 배정합니다.

GraphQL Signature

파라미터

ID!
required
배정할 객실 타입 ID
String!
required
객실 선택 방식: - priority: 우선순위 높은 객실 우선 - random: 무작위 선택
  • updatedAt: 가장 오래 업데이트되지 않은 객실 우선
String
예약 타입 (rental 또는 stay)
DateTime!
required
사용 시작 일시
DateTime!
required
사용 종료 일시
ID!
required
예약 ID

배정 조건

  • 객실 상태: NOT_USING
  • 청소 상태: CLEAN
  • 판매 상태: ALL 또는 예약 타입에 맞는 상태
  • 카드 상태: guest가 아님
  • 해당 기간에 다른 예약 없음

권한

  • 관리자(ADMIN) 권한 필요

예제

에러 처리

배정 가능한 객실이 없습니다.
유효하지 않은 orderBy 값입니다.

createRoomOccupancyTimeline

객실 점유 타임라인을 생성합니다. 특정 기간 동안 객실의 점유 상태를 기록합니다.

GraphQL Signature

파라미터

ID!
required
객실 ID
OccupancyStatus!
required
점유 상태: - OCCUPIED: 점유됨 - DISABLED: 사용 중지
DateTime!
required
시작 일시
DateTime!
required
종료 일시
String
메모
Boolean
재고 수량 포함 여부
ID
연관된 예약 ID

제약사항

  • endAtstartAt보다 이후여야 함
  • 동일 기간에 동일 상태의 타임라인 중복 불가

권한

  • 숙박시설 스태프(STAFF) 이상 권한 필요

예제

에러 처리

종료 일시가 시작 일시보다 이전입니다.
동일 기간에 중복된 타임라인이 존재합니다.

updateRoomOccupancyTimeline

객실 점유 타임라인을 수정합니다.

GraphQL Signature

파라미터

ID!
required
타임라인 ID
DateTime
시작 일시
DateTime
종료 일시
String
메모

권한

  • 숙박시설 스태프(STAFF) 이상 권한 필요

deleteRoomOccupancyTimeline

객실 점유 타임라인을 삭제합니다.

GraphQL Signature

파라미터

ID!
required
삭제할 타임라인 ID

권한

  • 숙박시설 스태프(STAFF) 이상 권한 필요

createPrice

객실 타입의 가격 정보를 생성합니다.

GraphQL Signature

파라미터

ID!
required
객실 타입 ID
String!
required
가격 타입 (예: rental, stay)
[PriceTimeInput]
시간대별 가격 정보: - startTime: 시작 시간 - endTime: 종료 시간 - price: 가격 - type: 타입
ID
연관된 ARI 패키지 ID

제약사항

  • 동일한 타입의 시간대가 겹치면 안 됨
  • 동일한 priceTypeariPackageId 조합 중복 불가

권한

  • 숙박시설 관리자(MANAGER) 권한 필요

에러 처리

시간대가 겹치는 가격 정보가 있습니다.
동일한 가격 정보가 이미 존재합니다.

updatePrice

가격 정보를 수정합니다.

GraphQL Signature

파라미터

ID!
required
수정할 가격 ID
String
가격 타입
[PriceTimeInput]
시간대별 가격 정보

권한

  • 숙박시설 관리자(MANAGER) 권한 필요

deletePrice

가격 정보를 삭제합니다.

GraphQL Signature

파라미터

ID!
required
삭제할 가격 ID

권한

  • 숙박시설 관리자(MANAGER) 권한 필요

Room Memo 관리

createRoomMemo

객실 메모를 생성합니다.

updateRoomMemo

객실 메모를 수정합니다.

setRoomMemo

객실 메모를 생성하거나 수정합니다 (upsert).

deleteRoomMemo

객실 메모를 삭제합니다.
권한: 숙박시설 스태프(STAFF) 이상 권한 필요

Room Device 관리

createRoomDevice

객실 디바이스를 생성합니다.

updateRoomDevice

객실 디바이스를 수정합니다.

bulkUpdateRoomDevice

여러 객실 디바이스를 일괄 수정합니다.

deleteRoomDevice

객실 디바이스를 삭제합니다.
권한: 숙박시설 관리자(MANAGER) 권한 필요

객실 상태 흐름

기본 객실 상태 (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: 관리자가 설정한 사용 중지 기간

타임라인 사용 사례

  1. 예약 점유: 예약 생성 시 자동으로 OCCUPIED 타임라인 생성
  2. 판매 중지: 보수 공사, 시설 점검 등으로 DISABLED 타임라인 생성
  3. 재고 관리: isIncludedToQuantity 플래그로 판매 재고 수량 제어

관련 API