개요
Core 서비스의 예약 도메인은 숙박시설의 예약 전체 생명주기를 관리합니다. 예약 조회, 체크인/체크아웃, 객실 배정, 설정 관리 등의 기능을 제공합니다.Query
getAccommodationReservations
숙박시설의 예약 목록을 페이지네이션하여 조회합니다.GraphQL Signature
파라미터
조회할 숙박시설 ID
필터 옵션:
keyword: 예약 검색 키워드 (예약ID, 고객명, 전화번호, 차량번호, 신분증번호)dateFilterType: 날짜 필터 타입 (useStartAt,useExpireAt,createdAt)includeMultipleNights: 다박 예약 포함 여부sortKey: 정렬 기준 (기본값:createdAt)sortDirection: 정렬 방향 (asc,desc- 기본값:desc)
한 번에 조회할 예약 수 (기본값: 20)
페이지네이션 커서
응답
예약 목록
node: 예약 상세 정보cursor: 페이지네이션 커서
페이지네이션 정보
hasNextPage: 다음 페이지 존재 여부endCursor: 마지막 커서 값
예제
키워드 검색
keyword 필터는 다음 정보를 검색합니다:
- 예약 ID: ULID 형식의 예약 고유번호
- 고객명: 예약자 이름
- 전화번호: 연락처 정보
- 차량번호: 차량 등록번호
- 신분증번호: 여권번호 등 신분증 정보
getAccommodationReservationsAggregate
예약 통계 정보를 조회합니다.GraphQL Signature
파라미터
통계를 조회할 숙박시설 ID
집계 필터 조건 (getAccommodationReservations와 동일)
응답
총 예약 수
총 성인 투숙객 수
총 어린이 투숙객 수
총 유아 투숙객 수
예제
getSingleReservation
특정 예약의 상세 정보를 조회합니다.GraphQL Signature
파라미터
조회할 예약 ID
권한
다음 중 하나의 권한이 필요합니다:- 숙박시설 관리 권한
- 서드파티 읽기 권한 (
ACC_RESERVATION_READ) - 관리자 영구 토큰
응답
예약 전체 정보
status: 예약 상태 (RESERVED,CONFIRMED,CHECKED_IN,CHECKED_OUT)type: 예약 타입 (lodge: 숙박,rent: 대실)sleeps/childSleeps/infantSleeps: 투숙 인원checkInCode: 체크인 코드memo: 관리자 메모request: 고객 요청사항
예제
getReservationReadyToCheckIn
체크인 코드로 체크인 가능한 예약을 조회합니다.GraphQL Signature
파라미터
숙박시설 ID
체크인 코드
자동 배정
예약 설정에서unlimitedCheckIn이 활성화된 경우:
- 객실이 미배정된 예약이 1건만 조회되면 자동으로 객실을 배정합니다
- 배정 후 최신 정보를 반환합니다
응답
체크인 가능한 예약 목록
- 상태:
CHECKED_IN,CHECKED_OUT제외 - 기간: 조회일 기준 전후 3일 범위
예제
getAccommodationGuestReservations
고객이 자신의 예약을 조회합니다 (SMS 인증 필요).GraphQL Signature
파라미터
숙박시설 ID
고객 이름
고객 전화번호
SMS 인증 토큰 (
requestMileageSMSAuth → confirmMileageSMSAuth로 발급)인증 흐름
requestMileageSMSAuth(phone, type: "reservation")로 SMS 발송confirmMileageSMSAuth(phone, number)로 인증 토큰 발급- 발급받은 토큰으로 예약 조회
응답
고객의 예약 목록
- 기간: 최근 30일 ~ 향후 1년
- 상태: 삭제되지 않은 예약만
에러 처리
AUTH_NUMBER_NOT_MATCH
인증 토큰이 유효하지 않거나 만료되었습니다.
예제
getLodgeReservationsInDate
특정 기간의 숙박 예약을 조회합니다.GraphQL Signature
파라미터
숙박시설 ID
조회 시작 날짜
조회 종료 날짜
응답
숙박(
lodge) 타입 예약 목록- 조건:
useStartAt <= endDateANDuseExpireAt >= startDate
getRentReservationsInDate
특정 기간의 대실 예약을 조회합니다.GraphQL Signature
파라미터
숙박시설 ID
조회 시작 날짜
조회 종료 날짜
응답
대실(
rent) 타입 예약 목록- 조건:
useStartAt >= startDateANDuseStartAt <= endDate
checkOtaNumberDuplications
OTA 예약번호 중복 검사를 수행합니다.GraphQL Signature
파라미터
숙박시설 ID
검사할 OTA 예약번호 목록
응답
중복된 OTA 예약번호 목록
Mutation
createReservationMemo
예약에 메모 또는 요청사항을 추가합니다.GraphQL Signature
파라미터
메모를 추가할 예약 ID
메모 타입:
MEMO: 관리자 메모REQUEST: 고객 요청사항
메모 내용
예제
updateReservationMemo
예약 메모를 수정합니다.GraphQL Signature
파라미터
수정할 메모 ID
변경할 메모 타입
변경할 메모 내용
deleteReservationMemo
예약 메모를 삭제합니다.GraphQL Signature
파라미터
삭제할 메모 ID
응답
삭제 성공 여부
reservationCheckIn
예약을 체크인 상태로 변경합니다.GraphQL Signature
파라미터
체크인할 예약 ID
체크아웃 제한 시간 (HH:mm 형식, 대실 무제한 체크인 설정 시 사용)
전제조건
- 예약에 객실이 배정되어 있어야 함 (
roomId != null) - 이미 체크인 이상 상태가 아니어야 함
무제한 체크인 (대실)
예약 설정에서unlimitedRentCheckIn이 활성화된 경우:
- 현재 시각을 체크인 시간으로 설정
- 원래 예약 기간만큼 연장하여 체크아웃 시간 계산
useExpireAtLimit이 제공되면 해당 시간을 초과하지 않도록 제한
에러 처리
ROOM_UNASSIGNED
객실이 배정되지 않은 예약입니다.
ALREADY_CHECKED_IN
이미 체크인 완료된 예약입니다.
예제
reservationCheckOut
예약을 체크아웃 상태로 변경합니다.GraphQL Signature
파라미터
체크아웃할 예약 ID
자동 처리
체크아웃 시 자동으로 다음 작업을 수행합니다:- 객실 상태를
NOT_USING으로 변경 - 객실 청소 상태를
DIRTY로 변경
예제
roomCheckIn
객실 번호로 해당 객실의 예약을 체크인합니다.GraphQL Signature
파라미터
체크인할 객실 ID
처리 로직
- 해당 객실의 현재 또는 예정된 예약 중 가장 빠른 예약을 체크인
- 조회 조건:
useExpireAt >= 현재시각 - 이미 체크인된 예약은 제외
에러 처리
ALREADY_CHECKED_IN
해당 예약이 이미 체크인 상태입니다.
roomCheckOut
객실 번호로 해당 객실의 예약을 체크아웃합니다.GraphQL Signature
파라미터
체크아웃할 객실 ID
처리 로직
- 해당 객실의 현재 사용 중인 예약을 체크아웃
- 조회 조건:
useStartAt <= 현재시각ANDuseExpireAt >= 현재시각 useExpireAt을 현재 시각으로 업데이트
assignRoomToReservation
예약에 객실을 배정합니다.GraphQL Signature
파라미터
객실을 배정할 예약 ID
배정할 객실 ID
객실 타입 ID (미제공 시 예약의 intendedRoomTypeId 사용)
객실 이름
수동 배정 여부 (자동 시간 조정 활성화 시 사용)
객실 가용성 검사
배정 전 다음을 확인합니다:- 해당 객실이 예약 기간 동안 사용 가능한지
- 다른 예약과 겹치지 않는지
자동 시간 조정
예약 설정에서useManualAssignAutoAdjustment가 활성화되고 isManualAssign: true인 경우:
- 숙박:
useStartAt을 현재 시각으로 조정 - 대실:
useStartAt을 현재 시각으로,useExpireAt을 원래 기간만큼 연장
자동 처리
객실 배정 시 자동으로:- 객실 상태를
USING으로 변경 - 감사 로그에 객실 상태 변경 기록
에러 처리
RESERVATION_NOT_FOUND
예약을 찾을 수 없습니다.
ROOM_NOT_AVAILABLE
해당 기간에 객실을 사용할 수 없습니다.
예제
cancelAssignReservation
예약의 객실 배정을 취소합니다.GraphQL Signature
파라미터
배정을 취소할 예약 ID
처리 로직
체크인 전 예약인 경우:- 객실 상태를
NOT_USING으로 변경 - 예약의
roomId를null로 설정
전제조건
- 예약에 객실이 배정되어 있어야 함
- 체크인 상태가 아니어야 함
에러 처리
ROOM_UNASSIGNED
객실이 배정되지 않은 예약입니다.
changeReservationRoom
예약의 배정 객실을 변경합니다.GraphQL Signature
파라미터
객실을 변경할 예약 ID
새로 배정할 객실 ID
객실 타입 ID (미제공 시 기존 타입 유지)
객실 이름
처리 로직
- 새 객실 상태를
USING으로 변경 - 예약의 객실 정보 업데이트 (
isReAssign: true) - 감사 로그에 객실 변경 기록
전제조건
- 예약에 기존 객실이 배정되어 있어야 함
에러 처리
ROOM_UNASSIGNED
객실이 배정되지 않은 예약입니다.
assignRoomToReservation을 사용하세요.modifyReservation
예약 정보를 수정합니다.GraphQL Signature
파라미터
수정할 예약 ID
체크인 시간
체크아웃 시간
성인 투숙객 수
어린이 투숙객 수
유아 투숙객 수
관리자 메모 내용 (메모가 없으면 생성, 있으면 업데이트)
고객 요청사항 내용 (요청사항이 없으면 생성, 있으면 업데이트)
권한
다음 중 하나의 권한이 필요합니다:- 숙박시설 관리 권한
- 서드파티 쓰기 권한 (
ACC_RESERVATION_WRITE)
메모 처리
memoContent: MEMO 타입 메모를 생성/수정requestContent: REQUEST 타입 메모를 생성/수정- 각 메모는 예약당 1개씩만 존재
키오스크 수정
키오스크를 통한 수정인 경우 (context.user.kioskId 존재):
- 스케줄 재조정 방지 (
preventReschedule: true)
예제
deleteReservation
예약을 삭제(취소)합니다.GraphQL Signature
파라미터
삭제할 예약 ID
취소 사유
권한
다음 중 하나의 권한이 필요합니다:- 숙박시설 관리 권한
- 서드파티 쓰기 권한 (
ACC_RESERVATION_WRITE)
삭제 정보
삭제 시 다음 정보가 기록됩니다:deletedAt: 삭제 시각reason: “DELETED_BY_USER”cancelledBy: 삭제 수행자 이름cancelReason: 취소 사유
예제
restoreReservation
삭제된 예약을 복구합니다.GraphQL Signature
파라미터
복구할 예약 ID
권한
다음 중 하나의 권한이 필요합니다:- 숙박시설 관리 권한
- 서드파티 쓰기 권한 (
ACC_RESERVATION_WRITE)
복구 처리
deletedAt을null로 설정- 예약 상태는 삭제 전 상태로 복구
setReservationSettings
예약 관련 설정을 저장합니다.GraphQL Signature
파라미터
설정을 저장할 숙박시설 ID
설정 목록 (key-value 쌍)
주요 설정
unlimitedCheckIn: 무제한 체크인 활성화unlimitedRentCheckIn: 대실 무제한 체크인 활성화unlimitedRentCheckInDays: 무제한 체크인 가능 요일 (0=일요일)useManualAssignAutoAdjustment: 수동 배정 시 자동 시간 조정useAutoStopSale: 자동 판매 중지 활성화autoStopSaleUntil: 자동 판매 중지 종료 시각
자동 판매 중지
useAutoStopSale 또는 autoStopSaleUntil 변경 시:
- 감사 로그에 해당 필드를 강조 표시 (
highlightFields)
캐시 관리
설정 변경 시 자동으로 캐시를 무효화합니다 (reservationSettingCache.flush)
예제
setRoomSettings
객실 관련 설정을 저장합니다.GraphQL Signature
파라미터
설정을 저장할 숙박시설 ID
설정 목록 (key-value 쌍)
주요 설정
useAssignRoom: 자동 객실 배정 활성화assignRoomBefore: 체크인 몇 시간 전에 자동 배정할지 (시간 단위)roomAssignOrderBy: 객실 배정 순서 기준
자동 배정 옵션 변경
assignRoomBefore 또는 useAssignRoom 변경 시:
- 이벤트 스토어에
ASSIGN_ROOM_OPTION_CHANGED이벤트 저장
캐시 관리
설정 변경 시 자동으로 캐시를 무효화합니다 (roomSettingCache.flush)
예제
게스트 세션 API
게스트 세션 토큰을 통해 고객이 직접 예약을 관리할 수 있습니다.getReservationGuestSessionToken
PIN 코드 검증 후 게스트 세션 토큰을 발급합니다.GraphQL Signature
파라미터
예약 ID
예약에 설정된 PIN 코드
응답
게스트 세션 토큰 (이후 게스트 전용 API 호출 시 사용)
예제
getSingleReservationByGuestSession
게스트 세션으로 예약 정보를 조회합니다.GraphQL Signature
파라미터
조회할 예약 ID
게스트 세션 토큰
checkInReservationByGuestSession
게스트가 직접 체크인합니다.GraphQL Signature
파라미터
체크인할 예약 ID
게스트 세션 토큰
전제조건
- 객실이 배정되어 있어야 함
- 체크인 또는 체크아웃 상태가 아니어야 함
checkOutReservationByGuestSession
게스트가 직접 체크아웃합니다.GraphQL Signature
파라미터
체크아웃할 예약 ID
게스트 세션 토큰
자동 처리
체크아웃 시 자동으로:- 객실 상태를
USING으로 변경 (체크아웃 직후 상태) - 객실 청소 상태를
DIRTY로 변경
controlRoomDeviceByGuestSession
게스트가 객실 디바이스를 제어합니다.GraphQL Signature
파라미터
예약 ID
게스트 세션 토큰
디바이스 타입:
"doorlock": 도어락 제어
디바이스별 추가 데이터
전제조건
- 세션 토큰이 유효해야 함 (
requireActive: true) - 예약에 객실이 배정되어 있어야 함
도어락 제어
deviceType: "doorlock"인 경우:
- 예약 데이터의
keyId를 사용하여 스마트 도어락 개방 - SmartAccess 어댑터를 통해 실제 도어락 제어
예제
예약 상태
예약은 다음과 같은 상태를 가집니다:| 상태 | 설명 |
|---|---|
RESERVED | 예약됨 |
CONFIRMED | 확정됨 |
CHECKED_IN | 체크인 완료 |
CHECKED_OUT | 체크아웃 완료 |
RESERVED < CONFIRMED < CHECKED_IN < CHECKED_OUT
예약 타입
| 타입 | 설명 |
|---|---|
lodge | 숙박 예약 (1박 이상) |
rent | 대실 예약 (시간 단위) |
사용 흐름
일반 예약 프로세스
- 예약 생성: 외부 시스템에서 예약 데이터 전송
- 객실 배정:
assignRoomToReservation으로 객실 배정 - 체크인:
reservationCheckIn또는roomCheckIn - 체크아웃:
reservationCheckOut또는roomCheckOut
무인 체크인 프로세스 (게스트)
- 인증번호 요청:
requestMileageSMSAuth(type: "reservation") - 인증 확인:
confirmMileageSMSAuth로 토큰 발급 - 예약 조회:
getAccommodationGuestReservations로 예약 확인 - 세션 토큰 발급:
getReservationGuestSessionToken - 체크인:
checkInReservationByGuestSession - 도어락 개방:
controlRoomDeviceByGuestSession
키오스크 체크인 프로세스
- 체크인 코드 입력: 고객이 키오스크에 코드 입력
- 예약 조회:
getReservationReadyToCheckIn - 자동 배정: 객실 미배정 시 자동 배정
- 체크인:
reservationCheckIn