예약 관리

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

ONDA Platform Engineering 관리

예약 관리

ONDA Channel API의 예약 프로세스와 상태 관리를 안내합니다. 예약 생성은 반드시 검색 → 가격 확인(price-check) → book_token 발급 → 예약 생성 순서를 따릅니다.

예약 프로세스 개요

예약 생성

요청

POST /bookings의 body는 flat 구조입니다 (중첩 rooms[]/booker 객체가 아닙니다).

숙소 ID, 체크인/체크아웃 날짜, 통화는 book_token에 서명된 값이 사용되므로 body로 보낼 필요가 없습니다.

응답 (201 Created)

예약 레코드는 data envelope 안에 camelCase 키로 반환됩니다. 금액 필드(totalAmount, netAmount, saleAmount)는 문자열로 직렬화됩니다.

{
  "data": {
    "id": "1f0e8400-e29b-41d4-a716-446655440000",
    "hubBookingNumber": "ONDA123456",
    "channelBookingNumber": "MY-ORDER-1234",
    "propertyId": "117417",
    "checkin": "2026-03-15",
    "checkout": "2026-03-16",
    "bookerName": "홍길동",
    "totalAmount": "154000",
    "netAmount": "154000",
    "currency": "KRW",
    "status": "confirmed",
    "cancellationPolicy": "flexible",
    "createdAt": "2026-03-01T09:00:00.000Z"
  },
  "meta": {
    "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "timestamp": "2026-03-01T09:00:00.000Z"
  }
}

운영(live) 환경에서는 예약 생성 시 입금가만큼 보증금 잔액이 홀드됩니다. 가용 잔액이 부족하면 402 INSUFFICIENT_BALANCE가 반환됩니다. Sandbox 환경에서는 실제 예약 없이 모의 응답(hubBookingNumber: "SANDBOX-...")이 반환됩니다.

예약 상태

상태 변경은 웹훅(reservation.created / reservation.modified / reservation.cancelled / reservation.no_show)으로 실시간 수신할 수 있습니다.

예약 조회

목록 조회

GET /bookings는 다음 필터와 페이지네이션을 지원합니다:

curl -X GET "https://api.tport.dev/channel/v1/bookings?status=confirmed&checkin_from=2026-03-01&checkin_to=2026-03-31" \
  -H "Authorization: Bearer {access_token}"

상세 조회

curl -X GET "https://api.tport.dev/channel/v1/bookings/{id}" \
  -H "Authorization: Bearer {access_token}"

존재하지 않는 ID는 404 BOOKING_NOT_FOUND, 다른 앱의 예약은 403 FORBIDDEN이 반환됩니다.

예약 수정

PATCH /bookings/{id}로 투숙객 정보만 수정할 수 있습니다:

• guest_first_name, guest_last_name, guest_phone, guest_country, special_requests

날짜·객실·인원 변경은 지원하지 않습니다. 변경이 필요하면 기존 예약을 취소하고 새로 예약하세요. 수정 불가 상태면 409 BOOKING_NOT_MODIFIABLE, 변경 내용이 없으면 400 NO_CHANGES가 반환됩니다.

취소 및 환불 정책

취소 정책 유형

기한 이전 취소는 모든 정책에서 전액 환불됩니다 (non_refundable 제외). 기한 계산은 체크인일 15:00 (KST) 기준입니다.

취소 전 수수료 확인

실제 취소 없이 현재 시점의 취소 수수료를 미리 확인할 수 있습니다:

curl -X GET "https://api.tport.dev/channel/v1/bookings/{id}/cancellation-fee" \
  -H "Authorization: Bearer {access_token}"

{
  "data": {
    "policy": "moderate",
    "deadline_passed": false,
    "refund_percent": 100,
    "refund_amount": "154000",
    "cancellation_fee": "0",
    "currency": "KRW"
  }
}

취소 정책과 무료 취소 기한은 GET /bookings/{id}/cancellation-policy로 조회합니다.

취소 실행

curl -X PUT "https://api.tport.dev/channel/v1/bookings/{id}/cancel" \
  -H "Authorization: Bearer {access_token}"

예약 확인서 (바우처)

GET /bookings/{id}/voucher는 아직 제공되지 않습니다 (501 NOT_IMPLEMENTED 반환). 바우처 생성 기능은 추후 제공될 예정이며, 그 전까지는 예약 상세 조회 응답(hubBookingNumber 등)으로 자체 확인서를 구성하세요.

일반적인 에러 시나리오

book_token 만료/무효 (422 BOOKING_TOKEN_INVALID)

원인: 토큰 만료, 위·변조, 또는 이미 사용된 토큰

해결: price-check를 다시 호출하여 새 book_token을 발급받아 재시도

가격 변동

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

해결: price-check 응답의 status가 price_changed면 새 가격(pricing)을 고객에게 확인받은 뒤, 함께 발급된 새 book_token으로 예약 (에러가 아니라 200 응답의 상태 필드입니다)

재고 소진

원인: price-check 시점에 해당 요금제가 매진됨

해결: price-check 응답의 status가 sold_out이면 다른 객실/날짜를 제안

잔액 부족 (402 INSUFFICIENT_BALANCE)

원인: 운영 환경에서 가용 잔액이 예약 입금가보다 적음

해결: 대시보드에서 보증금을 충전한 후 재시도

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

다음 단계

• 실시간 검색 - price_check_token → book_token 발급 흐름
• 웹훅 - 실시간 예약 상태 알림 받기
• 에러 처리 - 에러 코드 및 처리 방법
• OpenAPI 명세 - 전체 API 명세