Folio 관리 - ./docs

개요

Folio 도메인은 숙박 시설에서 고객의 계정 및 그룹 단위 청구를 관리하는 시스템입니다. Folio는 예약(Reservation)과 비즈니스 블록(BusinessBlock)을 묶어 통합 청구를 제공하며, 요금제(RatePlan) 및 포함 항목(Inclusion) 스냅샷을 관리합니다.

주요 기능

Folio 생성 및 관리: 고객 계정 또는 그룹 단위 Folio 생성
예약 연결: 기존 Folio에 예약 추가
비즈니스 블록 연결: 기존 Folio에 비즈니스 블록 추가
요금 스냅샷 관리: 적용된 요금제 및 포함 항목 추적
청구서 연동: Folio 내 모든 청구서(Bill) 통합 관리

Queries

getFolio

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

GraphQL Signature

query GetFolio($id: ID!) {
  getFolio(id: $id) {
    id
    folioCode
    name
    status
    accommodationId
    accountProfileId
    groupProfileId
    accountProfile {
      id
      name
    }
    groupProfile {
      id
      name
    }
    bills {
      id
      billCode
      totalAmount
      balanceAmount
    }
    appliedFolioRates {
      id
      totalAmount
      balanceAmount
    }
    appliedFolioInclusions {
      id
      totalAmount
      balanceAmount
    }
    reservations {
      id
      reservationCode
    }
    businessBlocks {
      id
      blockCode
    }
    createdAt
    updatedAt
  }
}

파라미터

ID!

required

조회할 Folio의 고유 식별자

응답

ID!

Folio의 고유 식별자 (ULID 형식)

String!

Folio의 고유 코드 (자동 생성)

String

Folio 이름 (선택사항)

FolioStatus!

Folio 상태:

ACTIVE: 활성
CLOSED: 종료

ID!

숙박 시설 ID

Profile

계정 프로필 정보

Profile

그룹 프로필 정보

[Bill!]!

Folio에 속한 청구서 목록

[FolioRateSnapshot!]!

적용된 요금제 스냅샷 목록

[FolioInclusionSnapshot!]!

적용된 포함 항목 스냅샷 목록

[Reservation!]!

연결된 예약 목록

[BusinessBlock!]!

연결된 비즈니스 블록 목록

[TransferredRate!]!

다른 Folio로 이전된 요금 스냅샷

[TransferredInclusion!]!

다른 Folio로 이전된 포함 항목 스냅샷

예제

query {
  getFolio(id: "01HQKS9V8X2N3P4Q5R6S7T8U9V") {
    id
    folioCode
    name
    status
    accountProfile {
      name
    }
    bills {
      billCode
      totalAmount
    }
  }
}

{
  "data": {
    "getFolio": {
      "id": "01HQKS9V8X2N3P4Q5R6S7T8U9V",
      "folioCode": "F-ABC123",
      "name": "김철수 님 단체 예약",
      "status": "ACTIVE",
      "accountProfile": {
        "name": "김철수"
      },
      "bills": [
        {
          "billCode": "B-XYZ789",
          "totalAmount": 150000
        }
      ]
    }
  }
}

getFolios

숙박 시설의 Folio 목록을 필터링하여 조회합니다.

GraphQL Signature

query GetFolios(
  $accommodationId: ID!
  $filter: FolioFilterInput
  $orders: [OrderInput!]
  $first: Int
  $after: String
) {
  getFolios(
    accommodationId: $accommodationId
    filter: $filter
    orders: $orders
    first: $first
    after: $after
  ) {
    edges {
      node {
        id
        folioCode
        name
        status
        createdAt
      }
      cursor
    }
    pageInfo {
      hasNextPage
      endCursor
    }
    totalCount
  }
}

파라미터

ID!

required

숙박 시설 ID

FolioFilterInput

필터 조건:

name: Folio 이름 검색 (부분 일치)
startDate: 생성일 시작 범위
endDate: 생성일 종료 범위
status: Folio 상태 필터
accountProfileIds: 계정 프로필 ID 목록
groupProfileIds: 그룹 프로필 ID 목록

[OrderInput!]

정렬 조건 (예: [{ field: "createdAt", direction: DESC }])

Int

페이지당 항목 수 (기본값: 10)

String

페이지네이션 커서

응답

페이지네이션된 Folio 목록을 반환합니다 (Relay-style Cursor Connection).

예제

query {
  getFolios(
    accommodationId: "01HQKS9V8X2N3P4Q5R6S7T8U9V"
    filter: {
      status: ACTIVE
      startDate: "2025-01-01T00:00:00Z"
    }
    orders: [{ field: "createdAt", direction: DESC }]
    first: 20
  ) {
    edges {
      node {
        id
        folioCode
        name
        status
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
    totalCount
  }
}

{
  "data": {
    "getFolios": {
      "edges": [
        {
          "node": {
            "id": "01HQKS9V8X2N3P4Q5R6S7T8U9V",
            "folioCode": "F-ABC123",
            "name": "김철수 님 단체 예약",
            "status": "ACTIVE"
          }
        }
      ],
      "pageInfo": {
        "hasNextPage": false,
        "endCursor": "YXJyYXljb25uZWN0aW9uOjE5"
      },
      "totalCount": 1
    }
  }
}

Mutations

createFolio

새로운 Folio를 생성합니다. Folio는 독립적으로 생성되며, 예약 및 비즈니스 블록은 별도로 추가해야 합니다.

GraphQL Signature

mutation CreateFolio($input: CreateFolioInput!) {
  createFolio(input: $input) {
    id
    folioCode
    name
    status
    accommodationId
    accountProfileId
    groupProfileId
    createdAt
  }
}

파라미터

ID!

required

숙박 시설 ID

계정 프로필 ID (선택사항)

그룹 프로필 ID (선택사항)

String

Folio 이름 (선택사항)

[FolioRatePlanInput!]

적용할 요금제 목록:

ratePlanId: 요금제 ID
rateId: 요금 ID
quantity: 수량
startDate: 시작일
endDate: 종료일

[FolioInclusionInput!]

적용할 포함 항목 목록:

inclusionId: 포함 항목 ID
quantity: 수량
usageDate: 사용 날짜

응답

생성된 Folio 객체를 반환합니다.

예제

mutation {
  createFolio(
    input: {
      accommodationId: "01HQKS9V8X2N3P4Q5R6S7T8U9V"
      name: "김철수 님 단체 예약"
      accountProfileId: "01HQKS9V8X2N3P4Q5R6S7T8U9W"
      folioRatePlans: [
        {
          ratePlanId: "01HQKS9V8X2N3P4Q5R6S7T8U9X"
          rateId: "01HQKS9V8X2N3P4Q5R6S7T8U9Y"
          quantity: 2
          startDate: "2025-12-23"
          endDate: "2025-12-25"
        }
      ]
    }
  ) {
    id
    folioCode
    name
    status
  }
}

{
  "data": {
    "createFolio": {
      "id": "01HQKS9V8X2N3P4Q5R6S7T8U9Z",
      "folioCode": "F-DEF456",
      "name": "김철수 님 단체 예약",
      "status": "ACTIVE"
    }
  }
}

Folio 생성 시 요금제와 포함 항목을 지정하면 자동으로 청구서(Bill)가 생성됩니다.

updateFolio

기존 Folio의 정보를 수정합니다.

GraphQL Signature

mutation UpdateFolio($input: UpdateFolioInput!) {
  updateFolio(input: $input) {
    id
    folioCode
    name
    status
    updatedAt
  }
}

파라미터

ID!

required

수정할 Folio의 ID

String

변경할 Folio 이름

FolioStatus

변경할 Folio 상태 (ACTIVE | CLOSED)

변경할 계정 프로필 ID

변경할 그룹 프로필 ID

응답

수정된 Folio 객체를 반환합니다.

예제

mutation {
  updateFolio(
    input: {
      id: "01HQKS9V8X2N3P4Q5R6S7T8U9Z"
      name: "김철수 님 VIP 단체 예약"
      status: CLOSED
    }
  ) {
    id
    folioCode
    name
    status
  }
}

{
  "data": {
    "updateFolio": {
      "id": "01HQKS9V8X2N3P4Q5R6S7T8U9Z",
      "folioCode": "F-DEF456",
      "name": "김철수 님 VIP 단체 예약",
      "status": "CLOSED"
    }
  }
}

deleteFolio

Folio를 삭제합니다.

GraphQL Signature

mutation DeleteFolio($id: ID!) {
  deleteFolio(id: $id)
}

파라미터

ID!

required

삭제할 Folio의 ID

응답

Boolean!

삭제 성공 여부 (true 반환)

예제

mutation {
  deleteFolio(id: "01HQKS9V8X2N3P4Q5R6S7T8U9Z")
}

{
  "data": {
    "deleteFolio": true
  }
}

Folio 삭제 시 연결된 예약, 청구서, 결제 정보도 함께 영향을 받을 수 있습니다. 삭제 전 데이터를 확인하세요.

addReservationToFolio

기존 Folio에 새로운 예약을 추가합니다.

GraphQL Signature

mutation AddReservationToFolio($input: AddReservationToFolioInput!) {
  addReservationToFolio(input: $input) {
    id
    reservationCode
    folioId
    checkInDate
    checkOutDate
    status
  }
}

파라미터

ID!

required

예약을 추가할 Folio ID

연결할 비즈니스 블록 ID (선택사항)

[ID!]

예약에 연결할 프로필 ID 목록

Date!

required

체크인 날짜

Date!

required

체크아웃 날짜

ID!

required

객실 타입 ID

[RatePlanInput!]

적용할 요금제 목록

[InclusionInput!]

적용할 포함 항목 목록

Boolean

즉시 체크인 처리 여부 (기본값: false)

Boolean

예약 확인 SMS 발송 여부 (기본값: false)

응답

생성된 Reservation 객체를 반환합니다.

예제

mutation {
  addReservationToFolio(
    input: {
      folioId: "01HQKS9V8X2N3P4Q5R6S7T8U9Z"
      checkInDate: "2025-12-23"
      checkOutDate: "2025-12-25"
      roomTypeId: "01HQKS9V8X2N3P4Q5R6S7T8U9A"
      profileIds: ["01HQKS9V8X2N3P4Q5R6S7T8U9B"]
      needCheckIn: false
      sendSMS: true
    }
  ) {
    id
    reservationCode
    folioId
    checkInDate
    checkOutDate
    status
  }
}

{
  "data": {
    "addReservationToFolio": {
      "id": "01HQKS9V8X2N3P4Q5R6S7T8U9C",
      "reservationCode": "R-GHI789",
      "folioId": "01HQKS9V8X2N3P4Q5R6S7T8U9Z",
      "checkInDate": "2025-12-23",
      "checkOutDate": "2025-12-25",
      "status": "CONFIRMED"
    }
  }
}

needCheckIn을 true로 설정하면 예약 생성과 동시에 체크인 처리됩니다.

addBusinessBlockToFolio

기존 Folio에 새로운 비즈니스 블록을 추가합니다.

GraphQL Signature

mutation AddBusinessBlockToFolio($input: AddBusinessBlockToFolioInput!) {
  addBusinessBlockToFolio(input: $input) {
    id
    blockCode
    folioId
    blockName
    startDate
    endDate
    status
  }
}

파라미터

ID!

required

비즈니스 블록을 추가할 Folio ID

String!

required

블록 이름

Date!

required

블록 시작 날짜

Date!

required

블록 종료 날짜

ID!

required

객실 타입 ID

Int!

required

예약할 객실 수

응답

생성된 BusinessBlock 객체를 반환합니다.

예제

mutation {
  addBusinessBlockToFolio(
    input: {
      folioId: "01HQKS9V8X2N3P4Q5R6S7T8U9Z"
      blockName: "연말 세미나 블록"
      startDate: "2025-12-23"
      endDate: "2025-12-25"
      roomTypeId: "01HQKS9V8X2N3P4Q5R6S7T8U9A"
      roomCount: 10
    }
  ) {
    id
    blockCode
    folioId
    blockName
    startDate
    endDate
    status
  }
}

{
  "data": {
    "addBusinessBlockToFolio": {
      "id": "01HQKS9V8X2N3P4Q5R6S7T8U9D",
      "blockCode": "BB-JKL012",
      "folioId": "01HQKS9V8X2N3P4Q5R6S7T8U9Z",
      "blockName": "연말 세미나 블록",
      "startDate": "2025-12-23",
      "endDate": "2025-12-25",
      "status": "ACTIVE"
    }
  }
}

데이터 모델

FolioStatus

Folio의 상태를 나타냅니다.

ACTIVE: 활성 상태 (청구 및 예약 가능)
CLOSED: 종료 상태 (정산 완료)

FolioRateSnapshot

Folio에 적용된 요금제의 스냅샷입니다. 요금제 변경 시에도 기존 스냅샷은 유지됩니다. 주요 필드:

appliedRatePlan: 적용된 요금제 정보 (히스토리)
appliedRate: 적용된 요금 정보 (히스토리)
totalAmount: 총 요금
balanceAmount: 잔액
businessBlock: 연결된 비즈니스 블록

FolioInclusionSnapshot

Folio에 적용된 포함 항목의 스냅샷입니다. 주요 필드:

appliedInclusion: 적용된 포함 항목 정보 (히스토리)
totalAmount: 총 금액
balanceAmount: 잔액

에러 처리

지정한 ID의 Folio를 찾을 수 없습니다.

비즈니스 블록이 지정한 Folio에 속하지 않습니다.

필수 파라미터가 누락되었습니다.

잘못된 파라미터가 전달되었습니다.

사용 흐름

Folio 생성: createFolio로 계정 또는 그룹 단위 Folio 생성
예약 추가: addReservationToFolio로 Folio에 예약 연결
비즈니스 블록 추가: addBusinessBlockToFolio로 단체 블록 연결
청구서 확인: Folio에 자동 생성된 청구서 조회
Folio 종료: 정산 완료 후 updateFolio로 상태를 CLOSED로 변경

​개요

​주요 기능

​Queries

​getFolio

​GraphQL Signature

​파라미터

​응답

​예제

​getFolios

​GraphQL Signature

​파라미터

​응답

​예제

​Mutations

​createFolio

​GraphQL Signature

​파라미터

​응답

​예제

​updateFolio

​GraphQL Signature

​파라미터

​응답

​예제

​deleteFolio

​GraphQL Signature

​파라미터

​응답

​예제

​addReservationToFolio

​GraphQL Signature

​파라미터

​응답

​예제

​addBusinessBlockToFolio

​GraphQL Signature

​파라미터

​응답

​예제

​데이터 모델

​FolioStatus

​FolioRateSnapshot

​FolioInclusionSnapshot

​에러 처리

​사용 흐름

​관련 API

개요

주요 기능

Queries

getFolio

GraphQL Signature

파라미터

응답

예제

getFolios

GraphQL Signature

파라미터

응답

예제

Mutations

createFolio

GraphQL Signature

파라미터

응답

예제

updateFolio

GraphQL Signature

파라미터

응답

예제

deleteFolio

GraphQL Signature

파라미터

응답

예제

addReservationToFolio

GraphQL Signature

파라미터

응답

예제

addBusinessBlockToFolio

GraphQL Signature

파라미터

응답

예제

데이터 모델

FolioStatus

FolioRateSnapshot

FolioInclusionSnapshot

에러 처리

사용 흐름

관련 API