Skip to main content

개요

Core 서비스의 예약 도메인은 숙박시설의 예약 전체 생명주기를 관리합니다. 예약 조회, 체크인/체크아웃, 객실 배정, 설정 관리 등의 기능을 제공합니다.

Query

getAccommodationReservations

숙박시설의 예약 목록을 페이지네이션하여 조회합니다.

GraphQL Signature

query GetAccommodationReservations(
  $accommodationId: ULID!
  $filter: AccommodationReservationsFilter
  $first: Int
  $after: String
) {
  getAccommodationReservations(
    accommodationId: $accommodationId
    filter: $filter
    first: $first
    after: $after
  ) {
    edges {
      node {
        id
        status
        useStartAt
        useExpireAt
        roomType {
          id
          name
        }
        room {
          id
          roomNumber
        }
        primaryGuestProfile {
          name
          contacts {
            contactType
            contactValue
          }
        }
      }
      cursor
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

파라미터

accommodationId
ULID!
required
조회할 숙박시설 ID
filter
AccommodationReservationsFilter
필터 옵션:
  • keyword: 예약 검색 키워드 (예약ID, 고객명, 전화번호, 차량번호, 신분증번호)
  • dateFilterType: 날짜 필터 타입 (useStartAt, useExpireAt, createdAt)
  • includeMultipleNights: 다박 예약 포함 여부
  • sortKey: 정렬 기준 (기본값: createdAt)
  • sortDirection: 정렬 방향 (asc, desc - 기본값: desc)
first
Int
한 번에 조회할 예약 수 (기본값: 20)
after
String
페이지네이션 커서

응답

edges
Array<Edge>
예약 목록
  • node: 예약 상세 정보
  • cursor: 페이지네이션 커서
pageInfo
PageInfo
페이지네이션 정보
  • hasNextPage: 다음 페이지 존재 여부
  • endCursor: 마지막 커서 값

예제

query {
  getAccommodationReservations(
    accommodationId: "01HQKS9V8X2N3P4Q5R6S7T8U9V"
    filter: {
      keyword: "홍길동"
      sortKey: "useStartAt"
      sortDirection: "desc"
    }
    first: 10
  ) {
    edges {
      node {
        id
        status
        useStartAt
        primaryGuestProfile {
          name
        }
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

키워드 검색

keyword 필터는 다음 정보를 검색합니다:
  • 예약 ID: ULID 형식의 예약 고유번호
  • 고객명: 예약자 이름
  • 전화번호: 연락처 정보
  • 차량번호: 차량 등록번호
  • 신분증번호: 여권번호 등 신분증 정보
includeMultipleNightsdateFilterType은 함께 사용할 수 없습니다.

getAccommodationReservationsAggregate

예약 통계 정보를 조회합니다.

GraphQL Signature

query GetAccommodationReservationsAggregate(
  $accommodationId: ULID!
  $filter: AccommodationReservationsFilter
) {
  getAccommodationReservationsAggregate(
    accommodationId: $accommodationId
    filter: $filter
  ) {
    count
    totalSleeps
    totalChildSleeps
    totalInfantSleeps
  }
}

파라미터

accommodationId
ULID!
required
통계를 조회할 숙박시설 ID
filter
AccommodationReservationsFilter
집계 필터 조건 (getAccommodationReservations와 동일)

응답

count
Int
총 예약 수
totalSleeps
Int
총 성인 투숙객 수
totalChildSleeps
Int
총 어린이 투숙객 수
totalInfantSleeps
Int
총 유아 투숙객 수

예제

query {
  getAccommodationReservationsAggregate(
    accommodationId: "01HQKS9V8X2N3P4Q5R6S7T8U9V"
    filter: {
      dateFilterType: "useStartAt"
      includeMultipleNights: false
    }
  ) {
    count
    totalSleeps
    totalChildSleeps
  }
}

getSingleReservation

특정 예약의 상세 정보를 조회합니다.

GraphQL Signature

query GetSingleReservation($reservationId: ULID!) {
  getSingleReservation(reservationId: $reservationId) {
    id
    status
    type
    useStartAt
    useExpireAt
    sleeps
    childSleeps
    infantSleeps
    checkInCode
    memo {
      content
    }
    request {
      content
    }
    roomType {
      id
      name
    }
    room {
      id
      roomNumber
    }
    primaryGuestProfile {
      name
      contacts {
        contactType
        contactValue
      }
    }
    guestProfiles {
      name
    }
    folio {
      id
      totalPrice
    }
    bills {
      id
      amount
    }
  }
}

파라미터

reservationId
ULID!
required
조회할 예약 ID

권한

다음 중 하나의 권한이 필요합니다:
  • 숙박시설 관리 권한
  • 서드파티 읽기 권한 (ACC_RESERVATION_READ)
  • 관리자 영구 토큰

응답

Reservation
Reservation
예약 전체 정보
  • status: 예약 상태 (RESERVED, CONFIRMED, CHECKED_IN, CHECKED_OUT)
  • type: 예약 타입 (lodge: 숙박, rent: 대실)
  • sleeps/childSleeps/infantSleeps: 투숙 인원
  • checkInCode: 체크인 코드
  • memo: 관리자 메모
  • request: 고객 요청사항

예제

query {
  getSingleReservation(
    reservationId: "01HQKS9V8X2N3P4Q5R6S7T8U9V"
  ) {
    id
    status
    useStartAt
    useExpireAt
    primaryGuestProfile {
      name
    }
    room {
      roomNumber
    }
  }
}

getReservationReadyToCheckIn

체크인 코드로 체크인 가능한 예약을 조회합니다.

GraphQL Signature

query GetReservationReadyToCheckIn(
  $accommodationId: ULID!
  $checkInCode: String!
) {
  getReservationReadyToCheckIn(
    accommodationId: $accommodationId
    checkInCode: $checkInCode
  ) {
    id
    status
    useStartAt
    useExpireAt
    roomId
    primaryGuestProfile {
      name
    }
  }
}

파라미터

accommodationId
ULID!
required
숙박시설 ID
checkInCode
String!
required
체크인 코드

자동 배정

예약 설정에서 unlimitedCheckIn이 활성화된 경우:
  • 객실이 미배정된 예약이 1건만 조회되면 자동으로 객실을 배정합니다
  • 배정 후 최신 정보를 반환합니다

응답

reservations
Array<Reservation>
체크인 가능한 예약 목록
  • 상태: CHECKED_IN, CHECKED_OUT 제외
  • 기간: 조회일 기준 전후 3일 범위

예제

query {
  getReservationReadyToCheckIn(
    accommodationId: "01HQKS9V8X2N3P4Q5R6S7T8U9V"
    checkInCode: "1234"
  ) {
    id
    status
    roomId
    primaryGuestProfile {
      name
    }
  }
}

getAccommodationGuestReservations

고객이 자신의 예약을 조회합니다 (SMS 인증 필요).

GraphQL Signature

query GetAccommodationGuestReservations(
  $accommodationId: ULID!
  $guestName: String!
  $phone: String!
  $authToken: String!
) {
  getAccommodationGuestReservations(
    accommodationId: $accommodationId
    guestName: $guestName
    phone: $phone
    authToken: $authToken
  ) {
    id
    status
    useStartAt
    useExpireAt
    roomType {
      name
    }
  }
}

파라미터

accommodationId
ULID!
required
숙박시설 ID
guestName
String!
required
고객 이름
phone
String!
required
고객 전화번호
authToken
String!
required
SMS 인증 토큰 (requestMileageSMSAuthconfirmMileageSMSAuth로 발급)

인증 흐름

  1. requestMileageSMSAuth(phone, type: "reservation")로 SMS 발송
  2. confirmMileageSMSAuth(phone, number)로 인증 토큰 발급
  3. 발급받은 토큰으로 예약 조회

응답

reservations
Array<Reservation>
고객의 예약 목록
  • 기간: 최근 30일 ~ 향후 1년
  • 상태: 삭제되지 않은 예약만

에러 처리

AUTH_NUMBER_NOT_MATCH
인증 토큰이 유효하지 않거나 만료되었습니다.

예제

query {
  getAccommodationGuestReservations(
    accommodationId: "01HQKS9V8X2N3P4Q5R6S7T8U9V"
    guestName: "홍길동"
    phone: "01012345678"
    authToken: "01HQKS9V8X2N3P4Q5R6S7T8U9V"
  ) {
    id
    status
    useStartAt
    roomType {
      name
    }
  }
}

getLodgeReservationsInDate

특정 기간의 숙박 예약을 조회합니다.

GraphQL Signature

query GetLodgeReservationsInDate(
  $accommodationId: ULID!
  $startDate: DateTime!
  $endDate: DateTime!
) {
  getLodgeReservationsInDate(
    accommodationId: $accommodationId
    startDate: $startDate
    endDate: $endDate
  ) {
    id
    useStartAt
    useExpireAt
    type
  }
}

파라미터

accommodationId
ULID!
required
숙박시설 ID
startDate
DateTime!
required
조회 시작 날짜
endDate
DateTime!
required
조회 종료 날짜

응답

reservations
Array<Reservation>
숙박(lodge) 타입 예약 목록
  • 조건: useStartAt <= endDate AND useExpireAt >= startDate

getRentReservationsInDate

특정 기간의 대실 예약을 조회합니다.

GraphQL Signature

query GetRentReservationsInDate(
  $accommodationId: ULID!
  $startDate: DateTime!
  $endDate: DateTime!
) {
  getRentReservationsInDate(
    accommodationId: $accommodationId
    startDate: $startDate
    endDate: $endDate
  ) {
    id
    useStartAt
    useExpireAt
    type
  }
}

파라미터

accommodationId
ULID!
required
숙박시설 ID
startDate
DateTime!
required
조회 시작 날짜
endDate
DateTime!
required
조회 종료 날짜

응답

reservations
Array<Reservation>
대실(rent) 타입 예약 목록
  • 조건: useStartAt >= startDate AND useStartAt <= endDate

checkOtaNumberDuplications

OTA 예약번호 중복 검사를 수행합니다.

GraphQL Signature

query CheckOtaNumberDuplications(
  $accommodationId: ULID!
  $otaCodes: [String!]!
) {
  checkOtaNumberDuplications(
    accommodationId: $accommodationId
    otaCodes: $otaCodes
  )
}

파라미터

accommodationId
ULID!
required
숙박시설 ID
otaCodes
[String!]!
required
검사할 OTA 예약번호 목록

응답

duplicates
Array<String>
중복된 OTA 예약번호 목록

Mutation

createReservationMemo

예약에 메모 또는 요청사항을 추가합니다.

GraphQL Signature

mutation CreateReservationMemo($input: CreateReservationMemoInput!) {
  createReservationMemo(input: $input) {
    id
    reservationId
    type
    content
  }
}

파라미터

input.reservationId
ULID!
required
메모를 추가할 예약 ID
input.type
ReservationMemoType!
required
메모 타입:
  • MEMO: 관리자 메모
  • REQUEST: 고객 요청사항
input.content
String!
required
메모 내용

예제

mutation {
  createReservationMemo(input: {
    reservationId: "01HQKS9V8X2N3P4Q5R6S7T8U9V"
    type: MEMO
    content: "체크인 시 웰컴 선물 제공"
  }) {
    id
    content
  }
}

updateReservationMemo

예약 메모를 수정합니다.

GraphQL Signature

mutation UpdateReservationMemo($input: UpdateReservationMemoInput!) {
  updateReservationMemo(input: $input) {
    id
    type
    content
  }
}

파라미터

input.id
ULID!
required
수정할 메모 ID
input.type
ReservationMemoType
변경할 메모 타입
input.content
String
변경할 메모 내용

deleteReservationMemo

예약 메모를 삭제합니다.

GraphQL Signature

mutation DeleteReservationMemo($id: ULID!) {
  deleteReservationMemo(id: $id)
}

파라미터

id
ULID!
required
삭제할 메모 ID

응답

success
Boolean!
삭제 성공 여부

reservationCheckIn

예약을 체크인 상태로 변경합니다.

GraphQL Signature

mutation ReservationCheckIn(
  $reservationId: ULID!
  $useExpireAtLimit: String
) {
  reservationCheckIn(
    reservationId: $reservationId
    useExpireAtLimit: $useExpireAtLimit
  ) {
    id
    status
    useStartAt
    useExpireAt
  }
}

파라미터

reservationId
ULID!
required
체크인할 예약 ID
useExpireAtLimit
String
체크아웃 제한 시간 (HH:mm 형식, 대실 무제한 체크인 설정 시 사용)

전제조건

  • 예약에 객실이 배정되어 있어야 함 (roomId != null)
  • 이미 체크인 이상 상태가 아니어야 함

무제한 체크인 (대실)

예약 설정에서 unlimitedRentCheckIn이 활성화된 경우:
  • 현재 시각을 체크인 시간으로 설정
  • 원래 예약 기간만큼 연장하여 체크아웃 시간 계산
  • useExpireAtLimit이 제공되면 해당 시간을 초과하지 않도록 제한

에러 처리

ROOM_UNASSIGNED
객실이 배정되지 않은 예약입니다.
ALREADY_CHECKED_IN
이미 체크인 완료된 예약입니다.

예제

mutation {
  reservationCheckIn(
    reservationId: "01HQKS9V8X2N3P4Q5R6S7T8U9V"
    useExpireAtLimit: "20:00"
  ) {
    id
    status
    useStartAt
    useExpireAt
  }
}

reservationCheckOut

예약을 체크아웃 상태로 변경합니다.

GraphQL Signature

mutation ReservationCheckOut($reservationId: ULID!) {
  reservationCheckOut(reservationId: $reservationId) {
    id
    status
  }
}

파라미터

reservationId
ULID!
required
체크아웃할 예약 ID

자동 처리

체크아웃 시 자동으로 다음 작업을 수행합니다:
  • 객실 상태를 NOT_USING으로 변경
  • 객실 청소 상태를 DIRTY로 변경

예제

mutation {
  reservationCheckOut(
    reservationId: "01HQKS9V8X2N3P4Q5R6S7T8U9V"
  ) {
    id
    status
  }
}

roomCheckIn

객실 번호로 해당 객실의 예약을 체크인합니다.

GraphQL Signature

mutation RoomCheckIn($roomId: ULID!) {
  roomCheckIn(roomId: $roomId) {
    id
    status
  }
}

파라미터

roomId
ULID!
required
체크인할 객실 ID

처리 로직

  • 해당 객실의 현재 또는 예정된 예약 중 가장 빠른 예약을 체크인
  • 조회 조건: useExpireAt >= 현재시각
  • 이미 체크인된 예약은 제외

에러 처리

ALREADY_CHECKED_IN
해당 예약이 이미 체크인 상태입니다.

roomCheckOut

객실 번호로 해당 객실의 예약을 체크아웃합니다.

GraphQL Signature

mutation RoomCheckOut($roomId: ULID!) {
  roomCheckOut(roomId: $roomId) {
    id
    status
    useExpireAt
  }
}

파라미터

roomId
ULID!
required
체크아웃할 객실 ID

처리 로직

  • 해당 객실의 현재 사용 중인 예약을 체크아웃
  • 조회 조건: useStartAt <= 현재시각 AND useExpireAt >= 현재시각
  • useExpireAt을 현재 시각으로 업데이트

assignRoomToReservation

예약에 객실을 배정합니다.

GraphQL Signature

mutation AssignRoomToReservation($input: AssignRoomInput!) {
  assignRoomToReservation(input: $input) {
    id
    roomId
    roomTypeId
    room {
      id
      roomNumber
    }
  }
}

파라미터

input.reservationId
ULID!
required
객실을 배정할 예약 ID
input.roomId
ULID!
required
배정할 객실 ID
input.roomTypeId
ULID
객실 타입 ID (미제공 시 예약의 intendedRoomTypeId 사용)
input.roomName
String
객실 이름
input.isManualAssign
Boolean
수동 배정 여부 (자동 시간 조정 활성화 시 사용)

객실 가용성 검사

배정 전 다음을 확인합니다:
  • 해당 객실이 예약 기간 동안 사용 가능한지
  • 다른 예약과 겹치지 않는지

자동 시간 조정

예약 설정에서 useManualAssignAutoAdjustment가 활성화되고 isManualAssign: true인 경우:
  • 숙박: useStartAt을 현재 시각으로 조정
  • 대실: useStartAt을 현재 시각으로, useExpireAt을 원래 기간만큼 연장

자동 처리

객실 배정 시 자동으로:
  • 객실 상태를 USING으로 변경
  • 감사 로그에 객실 상태 변경 기록

에러 처리

RESERVATION_NOT_FOUND
예약을 찾을 수 없습니다.
ROOM_NOT_AVAILABLE
해당 기간에 객실을 사용할 수 없습니다.

예제

mutation {
  assignRoomToReservation(input: {
    reservationId: "01HQKS9V8X2N3P4Q5R6S7T8U9V"
    roomId: "01HQKS9V8X2N3P4Q5R6S7T8U9W"
    isManualAssign: true
  }) {
    id
    roomId
    room {
      roomNumber
    }
  }
}

cancelAssignReservation

예약의 객실 배정을 취소합니다.

GraphQL Signature

mutation CancelAssignReservation($reservationId: ULID!) {
  cancelAssignReservation(reservationId: $reservationId) {
    id
    roomId
  }
}

파라미터

reservationId
ULID!
required
배정을 취소할 예약 ID

처리 로직

체크인 전 예약인 경우:
  • 객실 상태를 NOT_USING으로 변경
  • 예약의 roomIdnull로 설정

전제조건

  • 예약에 객실이 배정되어 있어야 함
  • 체크인 상태가 아니어야 함

에러 처리

ROOM_UNASSIGNED
객실이 배정되지 않은 예약입니다.

changeReservationRoom

예약의 배정 객실을 변경합니다.

GraphQL Signature

mutation ChangeReservationRoom($input: ChangeReservationRoomInput!) {
  changeReservationRoom(input: $input) {
    id
    roomId
    room {
      id
      roomNumber
    }
  }
}

파라미터

input.reservationId
ULID!
required
객실을 변경할 예약 ID
input.roomId
ULID!
required
새로 배정할 객실 ID
input.roomTypeId
ULID
객실 타입 ID (미제공 시 기존 타입 유지)
input.roomName
String
객실 이름

처리 로직

  1. 새 객실 상태를 USING으로 변경
  2. 예약의 객실 정보 업데이트 (isReAssign: true)
  3. 감사 로그에 객실 변경 기록

전제조건

  • 예약에 기존 객실이 배정되어 있어야 함

에러 처리

ROOM_UNASSIGNED
객실이 배정되지 않은 예약입니다. assignRoomToReservation을 사용하세요.

modifyReservation

예약 정보를 수정합니다.

GraphQL Signature

mutation ModifyReservation($input: ModifyReservationInput!) {
  modifyReservation(input: $input) {
    id
    status
    useStartAt
    useExpireAt
    sleeps
    childSleeps
    infantSleeps
    memo {
      content
    }
    request {
      content
    }
  }
}

파라미터

input.id
ULID!
required
수정할 예약 ID
input.useStartAt
DateTime
체크인 시간
input.useExpireAt
DateTime
체크아웃 시간
input.sleeps
Int
성인 투숙객 수
input.childSleeps
Int
어린이 투숙객 수
input.infantSleeps
Int
유아 투숙객 수
input.memoContent
String
관리자 메모 내용 (메모가 없으면 생성, 있으면 업데이트)
input.requestContent
String
고객 요청사항 내용 (요청사항이 없으면 생성, 있으면 업데이트)

권한

다음 중 하나의 권한이 필요합니다:
  • 숙박시설 관리 권한
  • 서드파티 쓰기 권한 (ACC_RESERVATION_WRITE)

메모 처리

  • memoContent: MEMO 타입 메모를 생성/수정
  • requestContent: REQUEST 타입 메모를 생성/수정
  • 각 메모는 예약당 1개씩만 존재

키오스크 수정

키오스크를 통한 수정인 경우 (context.user.kioskId 존재):
  • 스케줄 재조정 방지 (preventReschedule: true)

예제

mutation {
  modifyReservation(input: {
    id: "01HQKS9V8X2N3P4Q5R6S7T8U9V"
    sleeps: 2
    childSleeps: 1
    memoContent: "조식 추가 요청"
    requestContent: "높은 층 선호"
  }) {
    id
    sleeps
    childSleeps
    memo {
      content
    }
    request {
      content
    }
  }
}

deleteReservation

예약을 삭제(취소)합니다.

GraphQL Signature

mutation DeleteReservation($id: ULID!, $cancelReason: String) {
  deleteReservation(id: $id, cancelReason: $cancelReason) {
    id
    deletedAt
  }
}

파라미터

id
ULID!
required
삭제할 예약 ID
cancelReason
String
취소 사유

권한

다음 중 하나의 권한이 필요합니다:
  • 숙박시설 관리 권한
  • 서드파티 쓰기 권한 (ACC_RESERVATION_WRITE)

삭제 정보

삭제 시 다음 정보가 기록됩니다:
  • deletedAt: 삭제 시각
  • reason: “DELETED_BY_USER”
  • cancelledBy: 삭제 수행자 이름
  • cancelReason: 취소 사유

예제

mutation {
  deleteReservation(
    id: "01HQKS9V8X2N3P4Q5R6S7T8U9V"
    cancelReason: "고객 일정 변경"
  ) {
    id
    deletedAt
  }
}

restoreReservation

삭제된 예약을 복구합니다.

GraphQL Signature

mutation RestoreReservation($id: ULID!) {
  restoreReservation(id: $id) {
    id
    deletedAt
  }
}

파라미터

id
ULID!
required
복구할 예약 ID

권한

다음 중 하나의 권한이 필요합니다:
  • 숙박시설 관리 권한
  • 서드파티 쓰기 권한 (ACC_RESERVATION_WRITE)

복구 처리

  • deletedAtnull로 설정
  • 예약 상태는 삭제 전 상태로 복구

setReservationSettings

예약 관련 설정을 저장합니다.

GraphQL Signature

mutation SetReservationSettings(
  $accommodationId: ULID!
  $inputs: [SettingInput!]!
) {
  setReservationSettings(
    accommodationId: $accommodationId
    inputs: $inputs
  ) {
    id
    key
    value
  }
}

파라미터

accommodationId
ULID!
required
설정을 저장할 숙박시설 ID
inputs
[SettingInput!]!
required
설정 목록 (key-value 쌍)

주요 설정

  • unlimitedCheckIn: 무제한 체크인 활성화
  • unlimitedRentCheckIn: 대실 무제한 체크인 활성화
  • unlimitedRentCheckInDays: 무제한 체크인 가능 요일 (0=일요일)
  • useManualAssignAutoAdjustment: 수동 배정 시 자동 시간 조정
  • useAutoStopSale: 자동 판매 중지 활성화
  • autoStopSaleUntil: 자동 판매 중지 종료 시각

자동 판매 중지

useAutoStopSale 또는 autoStopSaleUntil 변경 시:
  • 감사 로그에 해당 필드를 강조 표시 (highlightFields)

캐시 관리

설정 변경 시 자동으로 캐시를 무효화합니다 (reservationSettingCache.flush)

예제

mutation {
  setReservationSettings(
    accommodationId: "01HQKS9V8X2N3P4Q5R6S7T8U9V"
    inputs: [
      { key: "unlimitedCheckIn", value: "true" }
      { key: "useManualAssignAutoAdjustment", value: "true" }
    ]
  ) {
    id
    key
    value
  }
}

setRoomSettings

객실 관련 설정을 저장합니다.

GraphQL Signature

mutation SetRoomSettings(
  $accommodationId: ULID!
  $inputs: [SettingInput!]!
) {
  setRoomSettings(
    accommodationId: $accommodationId
    inputs: $inputs
  ) {
    id
    key
    value
  }
}

파라미터

accommodationId
ULID!
required
설정을 저장할 숙박시설 ID
inputs
[SettingInput!]!
required
설정 목록 (key-value 쌍)

주요 설정

  • useAssignRoom: 자동 객실 배정 활성화
  • assignRoomBefore: 체크인 몇 시간 전에 자동 배정할지 (시간 단위)
  • roomAssignOrderBy: 객실 배정 순서 기준

자동 배정 옵션 변경

assignRoomBefore 또는 useAssignRoom 변경 시:
  • 이벤트 스토어에 ASSIGN_ROOM_OPTION_CHANGED 이벤트 저장

캐시 관리

설정 변경 시 자동으로 캐시를 무효화합니다 (roomSettingCache.flush)

예제

mutation {
  setRoomSettings(
    accommodationId: "01HQKS9V8X2N3P4Q5R6S7T8U9V"
    inputs: [
      { key: "useAssignRoom", value: "true" }
      { key: "assignRoomBefore", value: "2" }
    ]
  ) {
    id
    key
    value
  }
}

게스트 세션 API

게스트 세션 토큰을 통해 고객이 직접 예약을 관리할 수 있습니다.

getReservationGuestSessionToken

PIN 코드 검증 후 게스트 세션 토큰을 발급합니다.

GraphQL Signature

mutation GetReservationGuestSessionToken(
  $reservationId: ULID!
  $pinCode: String!
) {
  getReservationGuestSessionToken(
    reservationId: $reservationId
    pinCode: $pinCode
  )
}

파라미터

reservationId
ULID!
required
예약 ID
pinCode
String!
required
예약에 설정된 PIN 코드

응답

sessionToken
String!
게스트 세션 토큰 (이후 게스트 전용 API 호출 시 사용)

예제

mutation {
  getReservationGuestSessionToken(
    reservationId: "01HQKS9V8X2N3P4Q5R6S7T8U9V"
    pinCode: "1234"
  )
}

getSingleReservationByGuestSession

게스트 세션으로 예약 정보를 조회합니다.

GraphQL Signature

query GetSingleReservationByGuestSession(
  $reservationId: ULID!
  $sessionToken: String!
) {
  getSingleReservationByGuestSession(
    reservationId: $reservationId
    sessionToken: $sessionToken
  ) {
    id
    status
    useStartAt
    useExpireAt
    room {
      roomNumber
    }
  }
}

파라미터

reservationId
ULID!
required
조회할 예약 ID
sessionToken
String!
required
게스트 세션 토큰

checkInReservationByGuestSession

게스트가 직접 체크인합니다.

GraphQL Signature

mutation CheckInReservationByGuestSession(
  $reservationId: ULID!
  $sessionToken: String!
) {
  checkInReservationByGuestSession(
    reservationId: $reservationId
    sessionToken: $sessionToken
  ) {
    id
    status
  }
}

파라미터

reservationId
ULID!
required
체크인할 예약 ID
sessionToken
String!
required
게스트 세션 토큰

전제조건

  • 객실이 배정되어 있어야 함
  • 체크인 또는 체크아웃 상태가 아니어야 함

checkOutReservationByGuestSession

게스트가 직접 체크아웃합니다.

GraphQL Signature

mutation CheckOutReservationByGuestSession(
  $reservationId: ULID!
  $sessionToken: String!
) {
  checkOutReservationByGuestSession(
    reservationId: $reservationId
    sessionToken: $sessionToken
  ) {
    id
    status
  }
}

파라미터

reservationId
ULID!
required
체크아웃할 예약 ID
sessionToken
String!
required
게스트 세션 토큰

자동 처리

체크아웃 시 자동으로:
  • 객실 상태를 USING으로 변경 (체크아웃 직후 상태)
  • 객실 청소 상태를 DIRTY로 변경

controlRoomDeviceByGuestSession

게스트가 객실 디바이스를 제어합니다.

GraphQL Signature

mutation ControlRoomDeviceByGuestSession(
  $reservationId: ULID!
  $sessionToken: String!
  $deviceType: String!
  $data: JSON
) {
  controlRoomDeviceByGuestSession(
    reservationId: $reservationId
    sessionToken: $sessionToken
    deviceType: $deviceType
    data: $data
  )
}

파라미터

reservationId
ULID!
required
예약 ID
sessionToken
String!
required
게스트 세션 토큰
deviceType
String!
required
디바이스 타입:
  • "doorlock": 도어락 제어
data
JSON
디바이스별 추가 데이터

전제조건

  • 세션 토큰이 유효해야 함 (requireActive: true)
  • 예약에 객실이 배정되어 있어야 함

도어락 제어

deviceType: "doorlock"인 경우:
  • 예약 데이터의 keyId를 사용하여 스마트 도어락 개방
  • SmartAccess 어댑터를 통해 실제 도어락 제어

예제

mutation {
  controlRoomDeviceByGuestSession(
    reservationId: "01HQKS9V8X2N3P4Q5R6S7T8U9V"
    sessionToken: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
    deviceType: "doorlock"
  )
}

예약 상태

예약은 다음과 같은 상태를 가집니다:
상태설명
RESERVED예약됨
CONFIRMED확정됨
CHECKED_IN체크인 완료
CHECKED_OUT체크아웃 완료
상태 레벨: RESERVED < CONFIRMED < CHECKED_IN < CHECKED_OUT

예약 타입

타입설명
lodge숙박 예약 (1박 이상)
rent대실 예약 (시간 단위)

사용 흐름

일반 예약 프로세스

  1. 예약 생성: 외부 시스템에서 예약 데이터 전송
  2. 객실 배정: assignRoomToReservation으로 객실 배정
  3. 체크인: reservationCheckIn 또는 roomCheckIn
  4. 체크아웃: reservationCheckOut 또는 roomCheckOut

무인 체크인 프로세스 (게스트)

  1. 인증번호 요청: requestMileageSMSAuth(type: "reservation")
  2. 인증 확인: confirmMileageSMSAuth로 토큰 발급
  3. 예약 조회: getAccommodationGuestReservations로 예약 확인
  4. 세션 토큰 발급: getReservationGuestSessionToken
  5. 체크인: checkInReservationByGuestSession
  6. 도어락 개방: controlRoomDeviceByGuestSession

키오스크 체크인 프로세스

  1. 체크인 코드 입력: 고객이 키오스크에 코드 입력
  2. 예약 조회: getReservationReadyToCheckIn
  3. 자동 배정: 객실 미배정 시 자동 배정
  4. 체크인: reservationCheckIn

관련 API