예약 관리

예약 생성, 조회, 수정, 취소 프로세스를 안내합니다.

예약 관리#

ONDA API의 예약 프로세스와 상태 관리 개념을 안내합니다.

예약 프로세스 개요#

숙소 검색

가격 검색 API로 원하는 숙소와 패키지를 찾습니다.

예약 생성

고객 정보와 함께 예약을 생성합니다.

예약 확인

예약 ID와 확인 번호를 받고 상태를 확인합니다.

예약 관리

필요시 예약을 수정하거나 취소합니다.

예약 생성 프로세스#

기본 플로우#

검색: Rate Search로 원하는 객실/패키지의 최신 가격 확인
검증: 재고 확인 및 가격 일치 여부 확인
생성: 고객 정보와 함께 예약 생성 API 호출
확인: 예약 ID(res_xxx)와 확인 번호(ONDA123456) 수령

간단한 호출 예시#

curl -X POST "https://api.onda.me/v1/reservations" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "property_id": "prop_123456",
    "roomtype_id": "room_123",
    "rateplan_id": "plan_789",
    "check_in": "2026-03-15",
    "check_out": "2026-03-16",
    "adults": 2,
    "guest": {
      "first_name": "홍",
      "last_name": "길동",
      "email": "hong@example.com",
      "phone": "+82-10-1234-5678"
    }
  }'

필수 정보:

숙소/객실/패키지 ID
체크인/체크아웃 날짜
투숙 인원
고객 정보 (이름, 이메일, 전화번호)

응답:

예약 ID
확인 번호 (고객에게 제공)
예약 상태
가격 상세
취소 정책

상세한 파라미터는 API 레퍼런스를 참고하세요.

중요: 예약 생성 직전에 Rate Search로 최신 가격을 재확인하세요. 검색 시점과 예약 시점 사이에 가격이 변경되었을 수 있습니다.

예약 상태 라이프사이클#

상태 전이도#

상태 설명#

상태	의미	다음 가능 상태
`pending`	예약 대기 (결제 미완료)	`confirmed`, `cancelled`
`confirmed`	예약 확정	`checked_in`, `no_show`, `cancelled`
`checked_in`	체크인 완료	`checked_out`
`checked_out`	체크아웃 완료	(종료 상태)
`cancelled`	취소됨	(종료 상태)
`no_show`	노쇼	(종료 상태)

상태별 처리 가이드#

pending (결제 대기):

결제 기한 확인 필요
기한 내 미결제 시 자동 취소될 수 있음
고객에게 결제 독촉 알림 발송

confirmed (예약 확정):

정상적인 예약 상태
예약 확인서 발송 가능
수정/취소 가능 (정책에 따라)

checked_in (체크인 완료):

호텔에서 체크인 처리 완료
더 이상 취소 불가
노쇼로 처리되지 않음

checked_out (체크아웃 완료):

정상 이용 완료
리뷰 요청 가능

cancelled (취소):

고객 또는 호텔이 취소
환불 정책에 따라 환불 진행

no_show (노쇼):

고객이 체크인 시간까지 나타나지 않음
환불 불가 (대부분의 경우)

예약 조회#

조회 방법#

방법	사용 사례	API
예약 ID	시스템 내부 조회	`GET /reservations/{id}`
확인 번호	고객이 예약 조회	`GET /reservations?confirmation_number=ONDA123456`
날짜 범위	특정 기간 예약 목록	`GET /reservations?check_in_from=2026-03-01`
고객 이메일	고객별 예약 이력	`GET /reservations?guest_email=hong@example.com`

예약 수정#

수정 가능 항목#

항목	수정 가능 여부	조건
고객 정보	✅ 가능	언제든지
특별 요청	✅ 가능	체크인 전까지
도착 시간	✅ 가능	체크인 전까지
날짜 변경	⚠️ 조건부	재고 확인 필요, 가격 차액 발생 가능
객실/패키지 변경	⚠️ 조건부	취소 후 재예약 권장

날짜나 객실 변경은 재고 및 가격에 영향을 주므로, 기존 예약을 취소하고 새로 예약하는 것이 더 안전합니다.

취소 및 환불 정책#

취소 정책 유형#

정책 유형	무료 취소 기한	위약금
flexible	체크인 24시간 전	100% (기한 이후)
moderate	체크인 48시간 전	50% (기한 이후)
strict	체크인 7일 전	100% (기한 이후)
non_refundable	불가	100% (항상)

취소 프로세스#

취소 가능 여부 확인

취소 정책을 확인하여 환불 가능 여부와 금액을 계산합니다.

고객 확인

환불 금액과 위약금을 고객에게 안내하고 확인을 받습니다.

취소 API 호출

예약 취소 API를 호출하여 취소를 처리합니다.

환불 처리

환불 정책에 따라 환불이 진행됩니다 (보통 3-5영업일).

취소 시 고려사항#

무료 취소 기한: 정확한 시간(시/분/초)까지 확인
부분 환불: moderate 정책은 50% 환불
환불 방법: 원결제 수단으로 환불 (카드 취소, 계좌 이체 등)
환불 소요 시간: 일반적으로 3-5영업일

non_refundable (환불 불가) 정책은 어떠한 경우에도 환불이 불가능합니다. 예약 생성 시 고객에게 명확히 안내하세요.

예약 확인서#

바우처 생성#

예약 확인서(바우처)를 PDF 형식으로 생성할 수 있습니다.

용도:

고객에게 예약 증명 제공
호텔 체크인 시 제시
이메일 첨부

지원 형식: PDF, HTML 다국어: 한국어, 영어, 일본어, 중국어

복수 객실 예약#

하나의 예약에 여러 객실을 포함할 수 있습니다.

활용 사례:

가족 여행 (2개 객실)
단체 예약 (10개 객실)
다양한 객실 타입 조합

특징:

하나의 확인 번호로 관리
객실별로 다른 투숙객 정보 입력 가능
일괄 취소 또는 개별 취소 선택 가능

웹훅 연동#

예약 상태 변경 시 웹훅으로 실시간 알림을 받을 수 있습니다.

주요 예약 이벤트#

이벤트	발생 시점	권장 조치
`reservation.created`	예약 생성	고객에게 확인 이메일 발송
`reservation.confirmed`	결제 완료	확인서 발송
`reservation.modified`	예약 정보 수정	변경 내용 안내
`reservation.cancelled`	예약 취소	취소 확인 및 환불 안내
`reservation.checked_in`	체크인 완료	고객 서비스 시작
`reservation.checked_out`	체크아웃 완료	리뷰 요청
`reservation.no_show`	노쇼 발생	위약금 처리

웹훅 설정 방법은 웹훅 가이드를 참고하세요.

일반적인 에러 시나리오#

재고 부족#

원인: 검색 후 다른 채널에서 예약되어 재고 소진

해결: 다른 객실 타입 제안 또는 날짜 변경 제안

가격 변동#

원인: 검색 시점과 예약 시점 사이 가격 변경

해결: 최신 가격 재조회 후 고객 확인 받고 재시도

취소 불가#

원인: 무료 취소 기한 경과 또는 환불 불가 정책

해결: 취소 정책 안내 및 부분 환불 가능 여부 확인

중복 예약#

원인: 동일 조건의 예약이 이미 존재

해결: 기존 예약 확인 또는 중복 방지 로직 구현 (멱등성 키 사용)

자세한 에러 코드는 에러 처리 가이드를 참고하세요.

다음 단계#

웹훅 - 실시간 예약 상태 알림 받기
에러 처리 - 에러 코드 및 처리 방법
API 레퍼런스 - 전체 API 명세