청구서 관리 (Bill)

개요

Bill 도메인은 숙박 시설에서 고객에게 발행되는 청구서(Bill)와 결제(Payment) 정보를 관리합니다. Folio와 연결되어 요금, 서비스 비용, 추가 비용 등을 청구하고, 결제 내역을 추적합니다.

주요 기능

청구서 생성 및 관리: Folio에 청구서 추가
결제 처리: 청구서에 대한 결제 기록 관리
청구서 이전: 다른 Folio로 청구서 이전 (Transfer)
청구서 정산: 동일 Folio 내 청구서 간 정산 (Settlement)
청구서 취소: 청구서 및 결제 취소 처리

Queries

getAccommodationBills

숙박 시설의 모든 청구서 목록을 조회합니다.

GraphQL Signature

query GetAccommodationBills($accommodationId: ID!) {
  getAccommodationBills(accommodationId: $accommodationId) {
    id
    billCode
    folioId
    reservationId
    billName
    totalAmount
    balanceAmount
    status
    transferOriginFolioId
    createdAt
    createdBy
  }
}

파라미터

ID!

required

숙박 시설 ID

응답

ID!

청구서의 고유 식별자 (ULID 형식)

String!

청구서 고유 코드 (자동 생성)

ID!

청구서가 속한 Folio ID

연결된 예약 ID (선택사항)

String!

청구서 이름

Decimal!

총 청구 금액

Decimal!

남은 잔액 (미결제 금액)

String

청구서 상태

이전된 청구서인 경우 원본 Folio ID

String!

청구서 생성자

예제

query {
  getAccommodationBills(accommodationId: "01HQKS9V8X2N3P4Q5R6S7T8U9V") {
    id
    billCode
    billName
    totalAmount
    balanceAmount
    status
  }
}

{
  "data": {
    "getAccommodationBills": [
      {
        "id": "01HQKS9V8X2N3P4Q5R6S7T8U9X",
        "billCode": "B-ABC123",
        "billName": "객실 요금",
        "totalAmount": 150000,
        "balanceAmount": 0,
        "status": "PAID"
      },
      {
        "id": "01HQKS9V8X2N3P4Q5R6S7T8U9Y",
        "billCode": "B-DEF456",
        "billName": "조식 서비스",
        "totalAmount": 30000,
        "balanceAmount": 30000,
        "status": "PENDING"
      }
    ]
  }
}

getBillPayments

특정 청구서에 대한 결제 내역을 조회합니다.

GraphQL Signature

query GetBillPayments($billId: ID!) {
  getBillPayments(billId: $billId) {
    id
    billId
    paymentMethod
    amount
    paidAt
    createdBy
    cancelledAt
    cancelledBy
    virtualAccounts {
      bankCode
      accountNumber
      accountHolder
    }
  }
}

파라미터

ID!

required

결제 내역을 조회할 청구서 ID

응답

ID!

결제의 고유 식별자

ID!

청구서 ID

String!

결제 수단 (예: CARD, CASH, TRANSFER)

Decimal!

결제 금액

DateTime!

결제 일시

String!

결제 처리자

DateTime

결제 취소 일시

String

결제 취소자

VirtualAccountInfo

가상계좌 정보 (결제 수단이 가상계좌인 경우)

예제

query {
  getBillPayments(billId: "01HQKS9V8X2N3P4Q5R6S7T8U9X") {
    id
    paymentMethod
    amount
    paidAt
    createdBy
  }
}

{
  "data": {
    "getBillPayments": [
      {
        "id": "01HQKS9V8X2N3P4Q5R6S7T8U9Z",
        "paymentMethod": "CARD",
        "amount": 150000,
        "paidAt": "2025-12-23T14:30:00Z",
        "createdBy": "김직원"
      }
    ]
  }
}

Mutations

addBillToFolio

Folio에 새로운 청구서를 추가합니다.

GraphQL Signature

mutation AddBillToFolio($input: AddBillInput!) {
  addBillToFolio(input: $input) {
    id
    billCode
    folioId
    billName
    totalAmount
    balanceAmount
    createdAt
    createdBy
  }
}

파라미터

ID!

required

청구서를 추가할 Folio ID

String!

required

청구서 이름

Decimal!

required

총 청구 금액

Decimal

초기 잔액 (기본값: totalAmount)

연결할 예약 ID (선택사항)

[PaymentInput!]

청구서 생성과 동시에 추가할 결제 내역 목록:

paymentMethod: 결제 수단
amount: 결제 금액
paidAt: 결제 일시
virtualAccounts: 가상계좌 정보 (선택사항)

[SettlementInput!]

동일 Folio 내 다른 청구서와의 정산 정보:

targetBillId: 정산 대상 청구서 ID
settledAmount: 정산 금액

응답

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

예제

mutation {
  addBillToFolio(
    input: {
      folioId: "01HQKS9V8X2N3P4Q5R6S7T8U9V"
      billName: "스파 이용료"
      totalAmount: 80000
      balanceAmount: 80000
      payments: [
        {
          paymentMethod: "CARD"
          amount: 80000
          paidAt: "2025-12-23T15:00:00Z"
        }
      ]
    }
  ) {
    id
    billCode
    billName
    totalAmount
    balanceAmount
  }
}

{
  "data": {
    "addBillToFolio": {
      "id": "01HQKS9V8X2N3P4Q5R6S7T8U9A",
      "billCode": "B-GHI789",
      "billName": "스파 이용료",
      "totalAmount": 80000,
      "balanceAmount": 0
    }
  }
}

청구서 생성 시 payments를 함께 전달하면 결제가 자동으로 처리되고 balanceAmount가 차감됩니다.

updateBill

기존 청구서의 정보를 수정합니다.

GraphQL Signature

mutation UpdateBill($input: UpdateBillInput!) {
  updateBill(input: $input) {
    id
    billCode
    billName
    totalAmount
    balanceAmount
    updatedAt
  }
}

파라미터

ID!

required

수정할 청구서 ID

String

변경할 청구서 이름

Decimal

변경할 총 금액

Decimal

변경할 잔액

응답

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

예제

mutation {
  updateBill(
    input: {
      id: "01HQKS9V8X2N3P4Q5R6S7T8U9A"
      billName: "스파 이용료 (할인 적용)"
      totalAmount: 70000
      balanceAmount: 0
    }
  ) {
    id
    billCode
    billName
    totalAmount
    balanceAmount
  }
}

{
  "data": {
    "updateBill": {
      "id": "01HQKS9V8X2N3P4Q5R6S7T8U9A",
      "billCode": "B-GHI789",
      "billName": "스파 이용료 (할인 적용)",
      "totalAmount": 70000,
      "balanceAmount": 0
    }
  }
}

cancelBill

청구서를 취소합니다. 취소된 청구서는 삭제되지 않고 취소 상태로 유지됩니다.

GraphQL Signature

mutation CancelBill($id: ID!, $update: UpdateBillInput) {
  cancelBill(id: $id, update: $update) {
    id
    billCode
    status
    cancelledAt
  }
}

파라미터

ID!

required

취소할 청구서 ID

UpdateBillInput

취소 시 추가로 수정할 필드 (선택사항)

응답

취소된 Bill 객체를 반환합니다.

예제

mutation {
  cancelBill(id: "01HQKS9V8X2N3P4Q5R6S7T8U9A") {
    id
    billCode
    status
  }
}

{
  "data": {
    "cancelBill": {
      "id": "01HQKS9V8X2N3P4Q5R6S7T8U9A",
      "billCode": "B-GHI789",
      "status": "CANCELLED"
    }
  }
}

deleteBill

청구서를 완전히 삭제합니다.

GraphQL Signature

mutation DeleteBill($id: ID!) {
  deleteBill(id: $id)
}

파라미터

ID!

required

삭제할 청구서 ID

응답

Boolean!

삭제 성공 여부 (true 반환)

예제

mutation {
  deleteBill(id: "01HQKS9V8X2N3P4Q5R6S7T8U9A")
}

{
  "data": {
    "deleteBill": true
  }
}

청구서 삭제 시 연결된 결제(Payment) 정보도 함께 삭제됩니다. 청구서를 보존해야 한다면 cancelBill을 사용하세요.

transferBills

청구서를 다른 Folio로 이전하거나 동일 Folio 내에서 다른 예약으로 이동합니다.

GraphQL Signature

mutation TransferBills(
  $inputs: [TransferBillInput!]!
  $folioId: ID!
  $reservationId: ID
) {
  transferBills(
    inputs: $inputs
    folioId: $folioId
    reservationId: $reservationId
  ) {
    id
    billCode
    folioId
    reservationId
    totalAmount
    transferOriginFolioId
  }
}

파라미터

[TransferBillInput!]!

required

이전할 청구서 목록:

id: 이전할 청구서 ID
splitAmount: 분할 금액 (전체 이전 시 청구서의 totalAmount)

ID!

required

대상 Folio ID

대상 예약 ID (동일 Folio 내 이전 시 필수)

응답

이전된 Bill 객체 목록을 반환합니다.

동작 방식

동일 Folio 내 이전: folioId가 원본 청구서의 Folio와 동일한 경우, 청구서의 reservationId만 변경
다른 Folio로 이전: 새로운 청구서를 생성하고 transferOriginFolioId에 원본 Folio 기록

예제

mutation {
  transferBills(
    inputs: [
      {
        id: "01HQKS9V8X2N3P4Q5R6S7T8U9X"
        splitAmount: 150000
      }
    ]
    folioId: "01HQKS9V8X2N3P4Q5R6S7T8U9W"
  ) {
    id
    billCode
    folioId
    totalAmount
    transferOriginFolioId
  }
}

{
  "data": {
    "transferBills": [
      {
        "id": "01HQKS9V8X2N3P4Q5R6S7T8U9B",
        "billCode": "B-JKL012",
        "folioId": "01HQKS9V8X2N3P4Q5R6S7T8U9W",
        "totalAmount": 150000,
        "transferOriginFolioId": "01HQKS9V8X2N3P4Q5R6S7T8U9V"
      }
    ]
  }
}

동일 Folio 내 청구서 이전 시 reservationId를 필수로 지정해야 합니다.

addPaymentToBill

청구서에 결제를 추가합니다.

GraphQL Signature

mutation AddPaymentToBill($input: AddPaymentInput!) {
  addPaymentToBill(input: $input) {
    id
    billId
    paymentMethod
    amount
    paidAt
    createdBy
    virtualAccounts {
      bankCode
      accountNumber
      accountHolder
    }
  }
}

파라미터

ID!

required

결제를 추가할 청구서 ID

String!

required

결제 수단:

CARD: 카드
CASH: 현금
TRANSFER: 계좌이체
VIRTUAL_ACCOUNT: 가상계좌
기타 커스텀 결제 수단

Decimal!

required

결제 금액

DateTime!

required

결제 일시

VirtualAccountInput

가상계좌 정보 (결제 수단이 VIRTUAL_ACCOUNT인 경우):

bankCode: 은행 코드
accountNumber: 계좌번호
accountHolder: 예금주명

응답

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

예제

mutation {
  addPaymentToBill(
    input: {
      billId: "01HQKS9V8X2N3P4Q5R6S7T8U9X"
      paymentMethod: "CARD"
      amount: 150000
      paidAt: "2025-12-23T16:00:00Z"
    }
  ) {
    id
    paymentMethod
    amount
    paidAt
    createdBy
  }
}

{
  "data": {
    "addPaymentToBill": {
      "id": "01HQKS9V8X2N3P4Q5R6S7T8U9C",
      "paymentMethod": "CARD",
      "amount": 150000,
      "paidAt": "2025-12-23T16:00:00Z",
      "createdBy": "김직원"
    }
  }
}

결제 추가 시 청구서의 balanceAmount는 자동으로 차감되지 않습니다. 필요 시 updateBill로 수동 조정하세요.

updatePayment

기존 결제 정보를 수정합니다.

GraphQL Signature

mutation UpdatePayment($input: UpdatePaymentInput!) {
  updatePayment(input: $input) {
    id
    paymentMethod
    amount
    paidAt
    updatedAt
  }
}

파라미터

ID!

required

수정할 결제 ID

String

변경할 결제 수단

Decimal

변경할 결제 금액

DateTime

변경할 결제 일시

VirtualAccountInput

변경할 가상계좌 정보

응답

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

예제

mutation {
  updatePayment(
    input: {
      id: "01HQKS9V8X2N3P4Q5R6S7T8U9C"
      amount: 140000
    }
  ) {
    id
    paymentMethod
    amount
  }
}

{
  "data": {
    "updatePayment": {
      "id": "01HQKS9V8X2N3P4Q5R6S7T8U9C",
      "paymentMethod": "CARD",
      "amount": 140000
    }
  }
}

cancelPayment

결제를 취소합니다. 취소된 결제는 삭제되지 않고 취소 상태로 유지됩니다.

GraphQL Signature

mutation CancelPayment($id: ID!) {
  cancelPayment(id: $id) {
    id
    paymentMethod
    amount
    cancelledAt
    cancelledBy
  }
}

파라미터

ID!

required

취소할 결제 ID

응답

취소된 Payment 객체를 반환합니다.

예제

mutation {
  cancelPayment(id: "01HQKS9V8X2N3P4Q5R6S7T8U9C") {
    id
    paymentMethod
    amount
    cancelledAt
    cancelledBy
  }
}

{
  "data": {
    "cancelPayment": {
      "id": "01HQKS9V8X2N3P4Q5R6S7T8U9C",
      "paymentMethod": "CARD",
      "amount": 150000,
      "cancelledAt": "2025-12-23T17:00:00Z",
      "cancelledBy": "김직원"
    }
  }
}

deletePayment

결제를 완전히 삭제합니다.

GraphQL Signature

mutation DeletePayment($id: ID!) {
  deletePayment(id: $id)
}

파라미터

ID!

required

삭제할 결제 ID

응답

Boolean!

삭제 성공 여부 (true 반환)

예제

mutation {
  deletePayment(id: "01HQKS9V8X2N3P4Q5R6S7T8U9C")
}

{
  "data": {
    "deletePayment": true
  }
}

결제 삭제 시 청구서의 잔액은 자동으로 조정되지 않습니다. 필요 시 updateBill로 수동 조정하세요.

데이터 모델

Bill

청구서 엔티티입니다. 주요 필드:

billCode: 고유 청구서 코드
folioId: 소속 Folio ID
reservationId: 연결된 예약 ID (선택사항)
totalAmount: 총 청구 금액
balanceAmount: 남은 잔액
transferOriginFolioId: 이전된 청구서인 경우 원본 Folio ID
originRateSnapshot: 요금제 스냅샷 참조
originInclusionSnapshot: 포함 항목 스냅샷 참조
payments: 결제 목록
settlementsMade: 이 청구서가 정산한 내역
settlementsReceived: 이 청구서가 받은 정산 내역

Payment

결제 엔티티입니다. 주요 필드:

billId: 소속 청구서 ID
paymentMethod: 결제 수단
amount: 결제 금액
paidAt: 결제 일시
cancelledAt: 결제 취소 일시 (취소된 경우)
cancelledBy: 결제 취소자
virtualAccounts: 가상계좌 정보 (JSON)

BillSettlement

청구서 간 정산 정보입니다. 주요 필드:

paymentBillId: 정산을 수행한 청구서 ID
targetBillId: 정산 대상 청구서 ID
settledAmount: 정산 금액

에러 처리

지정한 ID의 청구서 또는 결제를 찾을 수 없습니다.

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

잘못된 파라미터가 전달되었습니다. 예를 들어:

다른 숙박 시설의 청구서를 이전하려는 경우
다른 Folio의 청구서와 정산하려는 경우

사용 흐름

청구서 생성: addBillToFolio로 Folio에 청구서 추가
결제 추가: addPaymentToBill로 결제 기록
청구서 정산: 동일 Folio 내 청구서 간 정산 (settlements 파라미터)
청구서 이전: transferBills로 다른 Folio로 이전
취소 처리: cancelPayment 또는 cancelBill로 취소
삭제: deletePayment 또는 deleteBill로 완전 삭제

​개요

​주요 기능

​Queries

​getAccommodationBills

​GraphQL Signature

​파라미터

​응답

​예제

​getBillPayments

​GraphQL Signature

​파라미터

​응답

​예제

​Mutations

​addBillToFolio

​GraphQL Signature

​파라미터

​응답

​예제

​updateBill

​GraphQL Signature

​파라미터

​응답

​예제

​cancelBill

​GraphQL Signature

​파라미터

​응답

​예제

​deleteBill

​GraphQL Signature

​파라미터

​응답

​예제

​transferBills

​GraphQL Signature

​파라미터

​응답

​동작 방식

​예제

​addPaymentToBill

​GraphQL Signature

​파라미터

​응답

​예제

​updatePayment

​GraphQL Signature

​파라미터

​응답

​예제

​cancelPayment

​GraphQL Signature

​파라미터

​응답

​예제

​deletePayment

​GraphQL Signature

​파라미터

​응답

​예제

​데이터 모델

​Bill

​Payment

​BillSettlement

​에러 처리

​사용 흐름

​관련 API

개요

주요 기능

Queries

getAccommodationBills

GraphQL Signature

파라미터

응답

예제

getBillPayments

GraphQL Signature

파라미터

응답

예제

Mutations

addBillToFolio

GraphQL Signature

파라미터

응답

예제

updateBill

GraphQL Signature

파라미터

응답

예제

cancelBill

GraphQL Signature

파라미터

응답

예제

deleteBill

GraphQL Signature

파라미터

응답

예제

transferBills

GraphQL Signature

파라미터

응답

동작 방식

예제

addPaymentToBill

GraphQL Signature

파라미터

응답

예제

updatePayment

GraphQL Signature

파라미터

응답

예제

cancelPayment

GraphQL Signature

파라미터

응답

예제

deletePayment

GraphQL Signature

파라미터

응답

예제

데이터 모델

Bill

Payment

BillSettlement

에러 처리

사용 흐름

관련 API