개요
Bill 도메인은 숙박 시설에서 고객에게 발행되는 청구서(Bill)와 결제(Payment) 정보를 관리합니다. Folio와 연결되어 요금, 서비스 비용, 추가 비용 등을 청구하고, 결제 내역을 추적합니다.주요 기능
- 청구서 생성 및 관리: Folio에 청구서 추가
- 결제 처리: 청구서에 대한 결제 기록 관리
- 청구서 이전: 다른 Folio로 청구서 이전 (Transfer)
- 청구서 정산: 동일 Folio 내 청구서 간 정산 (Settlement)
- 청구서 취소: 청구서 및 결제 취소 처리
Queries
getAccommodationBills
숙박 시설의 모든 청구서 목록을 조회합니다.GraphQL Signature
파라미터
숙박 시설 ID
응답
청구서의 고유 식별자 (ULID 형식)
청구서 고유 코드 (자동 생성)
청구서가 속한 Folio ID
연결된 예약 ID (선택사항)
청구서 이름
총 청구 금액
남은 잔액 (미결제 금액)
청구서 상태
이전된 청구서인 경우 원본 Folio ID
청구서 생성자
예제
getBillPayments
특정 청구서에 대한 결제 내역을 조회합니다.GraphQL Signature
파라미터
결제 내역을 조회할 청구서 ID
응답
결제의 고유 식별자
청구서 ID
결제 수단 (예:
CARD, CASH, TRANSFER)결제 금액
결제 일시
결제 처리자
결제 취소 일시
결제 취소자
가상계좌 정보 (결제 수단이 가상계좌인 경우)
예제
Mutations
addBillToFolio
Folio에 새로운 청구서를 추가합니다.GraphQL Signature
파라미터
청구서를 추가할 Folio ID
청구서 이름
총 청구 금액
초기 잔액 (기본값: totalAmount)
연결할 예약 ID (선택사항)
청구서 생성과 동시에 추가할 결제 내역 목록:
paymentMethod: 결제 수단amount: 결제 금액paidAt: 결제 일시virtualAccounts: 가상계좌 정보 (선택사항)
동일 Folio 내 다른 청구서와의 정산 정보:
targetBillId: 정산 대상 청구서 IDsettledAmount: 정산 금액
응답
생성된 Bill 객체를 반환합니다.예제
청구서 생성 시
payments를 함께 전달하면 결제가 자동으로 처리되고 balanceAmount가 차감됩니다.updateBill
기존 청구서의 정보를 수정합니다.GraphQL Signature
파라미터
수정할 청구서 ID
변경할 청구서 이름
변경할 총 금액
변경할 잔액
응답
수정된 Bill 객체를 반환합니다.예제
cancelBill
청구서를 취소합니다. 취소된 청구서는 삭제되지 않고 취소 상태로 유지됩니다.GraphQL Signature
파라미터
취소할 청구서 ID
취소 시 추가로 수정할 필드 (선택사항)
응답
취소된 Bill 객체를 반환합니다.예제
deleteBill
청구서를 완전히 삭제합니다.GraphQL Signature
파라미터
삭제할 청구서 ID
응답
삭제 성공 여부 (true 반환)
예제
transferBills
청구서를 다른 Folio로 이전하거나 동일 Folio 내에서 다른 예약으로 이동합니다.GraphQL Signature
파라미터
이전할 청구서 목록:
id: 이전할 청구서 IDsplitAmount: 분할 금액 (전체 이전 시 청구서의 totalAmount)
대상 Folio ID
대상 예약 ID (동일 Folio 내 이전 시 필수)
응답
이전된 Bill 객체 목록을 반환합니다.동작 방식
- 동일 Folio 내 이전:
folioId가 원본 청구서의 Folio와 동일한 경우, 청구서의reservationId만 변경 - 다른 Folio로 이전: 새로운 청구서를 생성하고
transferOriginFolioId에 원본 Folio 기록
예제
동일 Folio 내 청구서 이전 시
reservationId를 필수로 지정해야 합니다.addPaymentToBill
청구서에 결제를 추가합니다.GraphQL Signature
파라미터
결제를 추가할 청구서 ID
결제 수단:
CARD: 카드CASH: 현금TRANSFER: 계좌이체VIRTUAL_ACCOUNT: 가상계좌- 기타 커스텀 결제 수단
결제 금액
결제 일시
가상계좌 정보 (결제 수단이
VIRTUAL_ACCOUNT인 경우):bankCode: 은행 코드accountNumber: 계좌번호accountHolder: 예금주명
응답
생성된 Payment 객체를 반환합니다.예제
결제 추가 시 청구서의
balanceAmount는 자동으로 차감되지 않습니다. 필요 시 updateBill로 수동 조정하세요.updatePayment
기존 결제 정보를 수정합니다.GraphQL Signature
파라미터
수정할 결제 ID
변경할 결제 수단
변경할 결제 금액
변경할 결제 일시
변경할 가상계좌 정보
응답
수정된 Payment 객체를 반환합니다.예제
cancelPayment
결제를 취소합니다. 취소된 결제는 삭제되지 않고 취소 상태로 유지됩니다.GraphQL Signature
파라미터
취소할 결제 ID
응답
취소된 Payment 객체를 반환합니다.예제
deletePayment
결제를 완전히 삭제합니다.GraphQL Signature
파라미터
삭제할 결제 ID
응답
삭제 성공 여부 (true 반환)
예제
데이터 모델
Bill
청구서 엔티티입니다. 주요 필드:billCode: 고유 청구서 코드folioId: 소속 Folio IDreservationId: 연결된 예약 ID (선택사항)totalAmount: 총 청구 금액balanceAmount: 남은 잔액transferOriginFolioId: 이전된 청구서인 경우 원본 Folio IDoriginRateSnapshot: 요금제 스냅샷 참조originInclusionSnapshot: 포함 항목 스냅샷 참조payments: 결제 목록settlementsMade: 이 청구서가 정산한 내역settlementsReceived: 이 청구서가 받은 정산 내역
Payment
결제 엔티티입니다. 주요 필드:billId: 소속 청구서 IDpaymentMethod: 결제 수단amount: 결제 금액paidAt: 결제 일시cancelledAt: 결제 취소 일시 (취소된 경우)cancelledBy: 결제 취소자virtualAccounts: 가상계좌 정보 (JSON)
BillSettlement
청구서 간 정산 정보입니다. 주요 필드:paymentBillId: 정산을 수행한 청구서 IDtargetBillId: 정산 대상 청구서 IDsettledAmount: 정산 금액
에러 처리
DATA_NOT_FOUND_ON_ID
지정한 ID의 청구서 또는 결제를 찾을 수 없습니다.
REQUIRED_PARAMETER
필수 파라미터가 누락되었습니다.
INVALID_PARAMETER
잘못된 파라미터가 전달되었습니다. 예를 들어:
- 다른 숙박 시설의 청구서를 이전하려는 경우
- 다른 Folio의 청구서와 정산하려는 경우
사용 흐름
- 청구서 생성:
addBillToFolio로 Folio에 청구서 추가 - 결제 추가:
addPaymentToBill로 결제 기록 - 청구서 정산: 동일 Folio 내 청구서 간 정산 (
settlements파라미터) - 청구서 이전:
transferBills로 다른 Folio로 이전 - 취소 처리:
cancelPayment또는cancelBill로 취소 - 삭제:
deletePayment또는deleteBill로 완전 삭제
관련 API
- Folio 관리 API - Folio 생성 및 관리
- 예약 관리 API - 예약과 청구서 연결
- 마일리지 API - 마일리지 결제 연동