예약 관리 (Reservation)

개요

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
    }
  }
}

파라미터

ULID!

required

조회할 숙박시설 ID

AccommodationReservationsFilter

필터 옵션:

keyword: 예약 검색 키워드 (예약ID, 고객명, 전화번호, 차량번호, 신분증번호)
dateFilterType: 날짜 필터 타입 (createdAt, inHouseDate, intendedUseStartAt, intendedUseExpireAt)
includeMultipleNights: 다박 예약 포함 여부
sortKey: 정렬 기준 (기본값: createdAt)
sortDirection: 정렬 방향 (asc, desc - 기본값: desc)

Int

한 번에 조회할 예약 수 (기본값: 20)

String

페이지네이션 커서

응답

Array<Edge>

예약 목록

node: 예약 상세 정보
cursor: 페이지네이션 커서

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
    }
  }
}

{
  "data": {
    "getAccommodationReservations": {
      "edges": [
        {
          "node": {
            "id": "01HQKS9V8X2N3P4Q5R6S7T8U9V",
            "status": "CHECKED_IN",
            "useStartAt": "2025-12-23T15:00:00Z",
            "primaryGuestProfile": {
              "name": "홍길동"
            }
          }
        }
      ],
      "pageInfo": {
        "hasNextPage": false,
        "endCursor": "01HQKS9V8X2N3P4Q5R6S7T8U9V"
      }
    }
  }
}

키워드 검색

keyword 필터는 다음 정보를 검색합니다:

예약 ID: ULID 형식의 예약 고유번호
고객명: 예약자 이름
전화번호: 연락처 정보
차량번호: 차량 등록번호
신분증번호: 여권번호 등 신분증 정보

includeMultipleNights와 dateFilterType은 함께 사용할 수 없습니다.

getAccommodationReservationsAggregate

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

GraphQL Signature

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

파라미터

ULID!

required

통계를 조회할 숙박시설 ID

AccommodationReservationsFilter

집계 필터 조건 (getAccommodationReservations와 동일)

응답

Int

총 예약 수

Int

총 성인 투숙객 수

Int

총 어린이 투숙객 수

Int

총 유아 투숙객 수

예제

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

{
  "data": {
    "getAccommodationReservationsAggregate": {
      "count": 42,
      "totalSleeps": 95,
      "totalChildSleeps": 12
    }
  }
}

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
    }
  }
}

파라미터

ULID!

required

조회할 예약 ID

권한

다음 중 하나의 권한이 필요합니다:

숙박시설 관리 권한
서드파티 읽기 권한 (ACC_RESERVATION_READ)
관리자 영구 토큰

응답

Reservation

예약 전체 정보

status: 예약 상태 (INQUIRY, TENTATIVE, DEFINITE, HOLDING, 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
    }
  }
}

{
  "data": {
    "getSingleReservation": {
      "id": "01HQKS9V8X2N3P4Q5R6S7T8U9V",
      "status": "CHECKED_IN",
      "useStartAt": "2025-12-23T15:00:00Z",
      "useExpireAt": "2025-12-24T11:00:00Z",
      "primaryGuestProfile": {
        "name": "홍길동"
      },
      "room": {
        "roomNumber": "201"
      }
    }
  }
}

getReservationReadyToCheckIn

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

GraphQL Signature

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

파라미터

ULID!

required

숙박시설 ID

String!

required

체크인 코드

체크인 시간 제한 없음

예약 설정에서 unlimitedCheckIn이 활성화된 경우:

숙박 이용 시 입실 시간을 제한하지 않아 언제든지 입실할 수 있습니다. (키오스크 이용 시 추가 요금 없이 입실 가능)

응답

Array<Reservation>

체크인 가능한 예약 목록

상태: CHECKED_IN, CHECKED_OUT 제외
기간: 조회일 기준 전후 3일 범위

예제

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

{
  "data": {
    "getReservationReadyToCheckIn": [
      {
        "id": "01HQKS9V8X2N3P4Q5R6S7T8U9V",
        "status": "DEFINITE",
        "roomId": "01HQKS9V8X2N3P4Q5R6S7T8U9W",
        "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
    }
  }
}

파라미터

ULID!

required

숙박시설 ID

String!

required

고객 이름

String!

required

고객 전화번호

String!

required

SMS 인증 토큰 (requestMileageSMSAuth → confirmMileageSMSAuth로 발급)

인증 흐름

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

응답

Array<Reservation>

고객의 예약 목록

기간: 최근 30일 ~ 향후 1년
상태: 삭제되지 않은 예약만

에러 처리

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

예제

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

{
  "data": {
    "getAccommodationGuestReservations": [
      {
        "id": "01HQKS9V8X2N3P4Q5R6S7T8U9V",
        "status": "DEFINITE",
        "useStartAt": "2025-12-25T15:00:00Z",
        "roomType": {
          "name": "디럭스룸"
        }
      }
    ]
  }
}

getLodgeReservationsInDate

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

GraphQL Signature

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

파라미터

ULID!

required

숙박시설 ID

DateTime!

required

조회 시작 날짜

DateTime!

required

조회 종료 날짜

응답

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
  }
}

파라미터

ULID!

required

숙박시설 ID

DateTime!

required

조회 시작 날짜

DateTime!

required

조회 종료 날짜

응답

Array<Reservation>

대실(rent) 타입 예약 목록

조건: useStartAt >= startDate AND useStartAt <= endDate

파라미터

ULID!

required

숙박시설 ID

[String!]!

required

검사할 OTA 예약번호 목록

응답

Array<String>

중복된 OTA 예약번호 목록

Mutation

createReservationMemo

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

GraphQL Signature

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

파라미터

ULID!

required

메모를 추가할 예약 ID

ReservationMemoType!

required

메모 타입:

MEMO: 관리자 메모
REQUEST: 고객 요청사항

String!

required

메모 내용

예제

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

{
  "data": {
    "createReservationMemo": {
      "id": "01HQKS9V8X2N3P4Q5R6S7T8U9X",
      "content": "체크인 시 웰컴 선물 제공"
    }
  }
}

updateReservationMemo

예약 메모를 수정합니다.

GraphQL Signature

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

파라미터

ULID!

required

수정할 메모 ID

ReservationMemoType

변경할 메모 타입

String

변경할 메모 내용

deleteReservationMemo

예약 메모를 삭제합니다.

GraphQL Signature

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

파라미터

ULID!

required

삭제할 메모 ID

응답

Boolean!

삭제 성공 여부

reservationCheckIn

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

GraphQL Signature

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

파라미터

ULID!

required

체크인할 예약 ID

String

체크아웃 제한 시간 (HH:mm 형식, 대실 무제한 체크인 설정 시 사용)

전제조건

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

무제한 체크인 (대실)

예약 설정에서 unlimitedRentCheckIn이 활성화된 경우:

현재 시각을 체크인 시간으로 설정
원래 예약 기간만큼 연장하여 체크아웃 시간 계산
useExpireAtLimit이 제공되면 해당 시간을 초과하지 않도록 제한

에러 처리

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

이미 체크인 완료된 예약입니다.

예제

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

{
  "data": {
    "reservationCheckIn": {
      "id": "01HQKS9V8X2N3P4Q5R6S7T8U9V",
      "status": "CHECKED_IN",
      "useStartAt": "2025-12-23T06:30:00Z",
      "useExpireAt": "2025-12-23T11:00:00Z"
    }
  }
}

reservationCheckOut

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

GraphQL Signature

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

파라미터

ULID!

required

체크아웃할 예약 ID

자동 처리

체크아웃 시 자동으로 다음 작업을 수행합니다:

객실 상태를 NOT_USING으로 변경
객실 청소 상태를 DIRTY로 변경

예제

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

{
  "data": {
    "reservationCheckOut": {
      "id": "01HQKS9V8X2N3P4Q5R6S7T8U9V",
      "status": "CHECKED_OUT"
    }
  }
}

roomCheckIn

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

GraphQL Signature

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

파라미터

ULID!

required

체크인할 객실 ID

처리 로직

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

에러 처리

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

roomCheckOut

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

GraphQL Signature

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

파라미터

ULID!

required

체크아웃할 객실 ID

처리 로직

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

assignRoomToReservation

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

GraphQL Signature

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

파라미터

ULID!

required

객실을 배정할 예약 ID

ULID!

required

배정할 객실 ID

ULID

객실 타입 ID (미제공 시 예약의 intendedRoomTypeId 사용)

String

객실 이름

Boolean

수동 배정 여부 (자동 시간 조정 활성화 시 사용)

객실 가용성 검사

배정 전 다음을 확인합니다:

해당 객실이 예약 기간 동안 사용 가능한지
다른 예약과 겹치지 않는지

자동 시간 조정

예약 설정에서 useManualAssignAutoAdjustment가 활성화되고 isManualAssign: true인 경우:

숙박: useStartAt을 현재 시각으로 조정
대실: useStartAt을 현재 시각으로, useExpireAt을 원래 기간만큼 연장

자동 처리

객실 배정 시 자동으로:

객실 상태를 USING으로 변경
감사 로그에 객실 상태 변경 기록

에러 처리

예약을 찾을 수 없습니다.

해당 기간에 객실을 사용할 수 없습니다.

예제

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

{
  "data": {
    "assignRoomToReservation": {
      "id": "01HQKS9V8X2N3P4Q5R6S7T8U9V",
      "roomId": "01HQKS9V8X2N3P4Q5R6S7T8U9W",
      "room": {
        "roomNumber": "201"
      }
    }
  }
}

cancelAssignReservation

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

GraphQL Signature

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

파라미터

ULID!

required

배정을 취소할 예약 ID

처리 로직

체크인 전 예약인 경우:

객실 상태를 NOT_USING으로 변경
예약의 roomId를 null로 설정

전제조건

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

에러 처리

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

changeReservationRoom

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

GraphQL Signature

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

파라미터

ULID!

required

객실을 변경할 예약 ID

ULID!

required

새로 배정할 객실 ID

ULID

객실 타입 ID (미제공 시 기존 타입 유지)

String

객실 이름

처리 로직

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

전제조건

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

에러 처리

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

modifyReservation

예약 정보를 수정합니다.

GraphQL Signature

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

파라미터

ULID!

required

수정할 예약 ID

DateTime

체크인 시간

DateTime

체크아웃 시간

Int

성인 투숙객 수

Int

어린이 투숙객 수

Int

유아 투숙객 수

String

관리자 메모 내용 (메모가 없으면 생성, 있으면 업데이트)

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
    }
  }
}

{
  "data": {
    "modifyReservation": {
      "id": "01HQKS9V8X2N3P4Q5R6S7T8U9V",
      "sleeps": 2,
      "childSleeps": 1,
      "memo": {
        "content": "조식 추가 요청"
      },
      "request": {
        "content": "높은 층 선호"
      }
    }
  }
}

deleteReservation

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

GraphQL Signature

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

파라미터

ULID!

required

삭제할 예약 ID

String

취소 사유

권한

다음 중 하나의 권한이 필요합니다:

숙박시설 관리 권한
서드파티 쓰기 권한 (ACC_RESERVATION_WRITE)

삭제 정보

삭제 시 다음 정보가 기록됩니다:

deletedAt: 삭제 시각
reason: “DELETED_BY_USER”
cancelledBy: 삭제 수행자 이름
cancelReason: 취소 사유

예제

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

{
  "data": {
    "deleteReservation": {
      "id": "01HQKS9V8X2N3P4Q5R6S7T8U9V",
      "deletedAt": "2025-12-23T12:34:56Z"
    }
  }
}

restoreReservation

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

GraphQL Signature

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

파라미터

ULID!

required

복구할 예약 ID

권한

다음 중 하나의 권한이 필요합니다:

숙박시설 관리 권한
서드파티 쓰기 권한 (ACC_RESERVATION_WRITE)

복구 처리

deletedAt을 null로 설정
예약 상태는 삭제 전 상태로 복구

setReservationSettings

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

GraphQL Signature

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

파라미터

ULID!

required

설정을 저장할 숙박시설 ID

[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
  }
}

{
  "data": {
    "setReservationSettings": [
      {
        "id": "01HQKS9V8X2N3P4Q5R6S7T8U9X",
        "key": "unlimitedCheckIn",
        "value": "true"
      },
      {
        "id": "01HQKS9V8X2N3P4Q5R6S7T8U9Y",
        "key": "useManualAssignAutoAdjustment",
        "value": "true"
      }
    ]
  }
}

setRoomSettings

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

GraphQL Signature

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

파라미터

ULID!

required

설정을 저장할 숙박시설 ID

[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
  }
}

{
  "data": {
    "setRoomSettings": [
      {
        "id": "01HQKS9V8X2N3P4Q5R6S7T8U9X",
        "key": "useAssignRoom",
        "value": "true"
      },
      {
        "id": "01HQKS9V8X2N3P4Q5R6S7T8U9Y",
        "key": "assignRoomBefore",
        "value": "2"
      }
    ]
  }
}

게스트 세션 API

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

getReservationGuestSessionToken

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

GraphQL Signature

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

파라미터

ULID!

required

예약 ID

String!

required

예약에 설정된 PIN 코드

응답

String!

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

예제

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

{
  "data": {
    "getReservationGuestSessionToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}

getSingleReservationByGuestSession

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

GraphQL Signature

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

파라미터

ULID!

required

조회할 예약 ID

String!

required

게스트 세션 토큰

checkInReservationByGuestSession

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

GraphQL Signature

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

파라미터

ULID!

required

체크인할 예약 ID

String!

required

게스트 세션 토큰

전제조건

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

checkOutReservationByGuestSession

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

GraphQL Signature

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

파라미터

ULID!

required

체크아웃할 예약 ID

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
  )
}

파라미터

ULID!

required

예약 ID

String!

required

게스트 세션 토큰

String!

required

디바이스 타입:

"doorlock": 도어락 제어

JSON

디바이스별 추가 데이터

전제조건

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

도어락 제어

deviceType: "doorlock"인 경우:

예약 데이터의 keyId를 사용하여 스마트 도어락 개방
SmartAccess 어댑터를 통해 실제 도어락 제어

예제

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

{
  "data": {
    "controlRoomDeviceByGuestSession": true
  }
}

예약 상태

예약은 다음과 같은 상태를 가집니다:

상태	설명
`INQUIRY`	문의
`TENTATIVE`	임시 예약
`DEFINITE`	확정됨
`HOLDING`	보류 중
`CHECKED_IN`	체크인 완료
`CHECKED_OUT`	체크아웃 완료

상태 레벨: INQUIRY < TENTATIVE < DEFINITE < HOLDING < CHECKED_IN < CHECKED_OUT

예약 타입

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

Intended Fields (계획 필드)

예약 생성 시 원래 의도했던 정보를 저장하는 필드입니다. 실제 체크인/체크아웃 시간이 변경되더라도 원래 계획을 추적할 수 있습니다.

필드	타입	설명
`intendedType`	`ReservationType!`	계획된 예약 타입 (lodge/rent)
`intendedUseStartAt`	`Date`	계획된 체크인 날짜/시간
`intendedUseExpireAt`	`Date`	계획된 체크아웃 날짜/시간
`intendedRoomTypeId`	`ID`	계획된 객실 타입 ID
`intendedRoomType`	`RoomType`	계획된 객실 타입 (resolver)

사용 목적

예약 변경 전후 비교 분석
날짜 필터링 시 계획 기준 조회 (intendedUseStartAt, intendedUseExpireAt)
리포팅 및 통계 분석

날짜 필터 타입 (DateFilterType)

예약 목록 조회 시 날짜 필터링에 사용됩니다:

값	설명
`createdAt`	예약 생성 날짜 기준
`inHouseDate`	실제 체류 날짜 기준
`intendedUseStartAt`	계획된 체크인 날짜 기준
`intendedUseExpireAt`	계획된 체크아웃 날짜 기준

사용 흐름

일반 예약 프로세스

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

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

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

키오스크 체크인 프로세스

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

​개요

​Query

​getAccommodationReservations

​GraphQL Signature

​파라미터

​응답

​예제

​키워드 검색

​getAccommodationReservationsAggregate

​GraphQL Signature

​파라미터

​응답

​예제

​getSingleReservation

​GraphQL Signature

​파라미터

​권한

​응답

​예제

​getReservationReadyToCheckIn

​GraphQL Signature

​파라미터

​체크인 시간 제한 없음

​응답

​예제

​getAccommodationGuestReservations

​GraphQL Signature

​파라미터

​인증 흐름

​응답

​에러 처리

​예제

​getLodgeReservationsInDate

​GraphQL Signature

​파라미터

​응답

​getRentReservationsInDate

​GraphQL Signature

​파라미터

​응답

​파라미터

​응답

​Mutation

​createReservationMemo

​GraphQL Signature

​파라미터

​예제

​updateReservationMemo

​GraphQL Signature

​파라미터

​deleteReservationMemo

​GraphQL Signature

​파라미터

​응답

​reservationCheckIn

​GraphQL Signature

​파라미터

​전제조건

​무제한 체크인 (대실)

​에러 처리

​예제

​reservationCheckOut

​GraphQL Signature

​파라미터

​자동 처리

​예제

​roomCheckIn

​GraphQL Signature

​파라미터

​처리 로직

​에러 처리

​roomCheckOut

​GraphQL Signature

​파라미터

​처리 로직

​assignRoomToReservation

​GraphQL Signature

​파라미터

​객실 가용성 검사

​자동 시간 조정

개요

Query

getAccommodationReservations

GraphQL Signature

파라미터

응답

예제

키워드 검색

getAccommodationReservationsAggregate

GraphQL Signature

파라미터

응답

예제

getSingleReservation

GraphQL Signature

파라미터

권한

응답

예제

getReservationReadyToCheckIn

GraphQL Signature

파라미터

체크인 시간 제한 없음

응답

예제

getAccommodationGuestReservations

GraphQL Signature

파라미터

인증 흐름

응답

에러 처리

예제

getLodgeReservationsInDate

GraphQL Signature

파라미터

응답

getRentReservationsInDate

GraphQL Signature

파라미터

응답

파라미터

응답

Mutation

createReservationMemo

GraphQL Signature

파라미터

예제

updateReservationMemo

GraphQL Signature

파라미터

deleteReservationMemo

GraphQL Signature

파라미터

응답

reservationCheckIn

GraphQL Signature

파라미터

전제조건

무제한 체크인 (대실)

에러 처리

예제

reservationCheckOut

GraphQL Signature

파라미터

자동 처리

예제

roomCheckIn

GraphQL Signature

파라미터

처리 로직

에러 처리

roomCheckOut

GraphQL Signature

파라미터

처리 로직

assignRoomToReservation

GraphQL Signature

파라미터

객실 가용성 검사

자동 시간 조정