실시간 검색
재고와 가격을 실시간으로 검색하고 book_token을 발급받는 방법을 안내합니다.
ONDA Platform Engineering 관리
실시간 검색
ONDA 검색 API의 구조와 실시간 재고/가격 조회, 그리고 예약에 필요한 book_token 발급 흐름을 안내합니다.
검색 → 예약 흐름 개요
ONDA 검색은 토큰 기반 2단계 흐름을 사용합니다. 예약에 필요한 book_token은 반드시 이 흐름을 거쳐 발급됩니다:
| 단계 | API | 결과 |
|---|---|---|
| 1단계 | GET /search/availability/{propertyId} | 객실·요금 목록 + price_check_token |
| 2단계 | GET /search/price-check?token={price_check_token} | 실시간 가격 재확인 + book_token |
| 예약 | POST /bookings | book_token으로 예약 생성 |
가용성 검색 (멀티 숙소)
GET /search/availability로 날짜/인원 조건에 맞는 숙소 목록을 조회합니다.
단일 숙소 검색
사용자가 선택한 숙소를 GET /search/availability/{propertyId}로 조회합니다. 응답에 price_check_token이 포함됩니다.
가격 확인 (price-check)
예약 직전 GET /search/price-check?token=...으로 최신 가격을 재확인합니다. 응답의 status(matched/price_changed/sold_out)를 확인하고 book_token을 받습니다.
예약 생성
발급받은 book_token으로 예약을 생성합니다.
실시간 검색의 특징
재고와 가격은 캐싱이 불가능합니다:
- 재고 변동: 다른 채널에서 예약이 발생하면 즉시 재고가 감소합니다
- 동적 가격: 수요/공급에 따라 가격이 실시간으로 변동할 수 있습니다
- 정합성 보장: 청구 금액은 price-check가 발급한
book_token에 서명된 서버 가격으로 강제됩니다
중요: 검색 결과를 5분 이상 캐싱하지 마세요. 예약 직전에는 항상 price-check로 최신 가격을 재확인해야 합니다.
Availability Search (멀티 숙소)
목적: 빈방이 있는 숙소를 빠르게 필터링하여 목록 표시
Availability Search
주요 파라미터:
| 파라미터 | 필수 | 설명 |
|---|---|---|
checkin / checkout | ✅ | 체크인/체크아웃 날짜 (YYYY-MM-DD) |
adults | 성인 수 (occupancy와 함께 사용 불가) | |
occupancy | 객실별 인원 (adults와 함께 사용 불가) | |
children / rooms | 소아 수 / 객실 수 | |
currency | 통화 코드 (기본 KRW) | |
property_id / city | 숙소 ID / 도시 필터 | |
star_rating_min / price_min / price_max | 성급·가격 필터 | |
sort_by | price_asc, price_desc, star_rating | |
page / per_page | 페이지네이션 (기본 1 / 20, 최대 100) |
전체 파라미터와 응답 스키마는 OpenAPI 명세를 참고하세요.
단일 숙소 검색 + price_check_token
목적: 특정 숙소의 객실 타입·요금제별 가용성을 조회하고, 다음 단계(price-check)에 사용할 토큰을 발급받습니다.
curl -X GET "https://api.tport.dev/channel/v1/search/availability/117417?checkin=2026-03-15&checkout=2026-03-16&adults=2" \
-H "Authorization: Bearer {access_token}"
필수 파라미터: checkin, checkout, adults
선택 파라미터: children, children_ages(쉼표 구분), rooms, currency
응답 구조:
{
"data": {
"items": [
// 객실 타입·요금제별 가용성 및 가격 목록
],
"price_check_token": "pct_..."
},
"meta": { "request_id": "...", "timestamp": "..." }
}
Price Check + book_token 발급
목적: 예약 직전 실시간 가격을 재확인하고, 예약 생성에 필수인 book_token을 발급받습니다.
curl -X GET "https://api.tport.dev/channel/v1/search/price-check?token={price_check_token}" \
-H "Authorization: Bearer {access_token}"
응답 구조:
{
"data": {
"status": "matched",
"pricing": {
"totals": { "inclusive_amount": 154000 }
},
"cancellation_policy": {
"policy_type": "flexible",
"free_cancellation_before": "2026-03-14T15:00:00.000Z",
"penalties": [
{ "type": "PERCENT", "amount_percent": 100, "from": "2026-03-14T15:00:00.000Z" }
]
},
"book_token": "bkt_..."
},
"meta": { "request_id": "...", "timestamp": "..." }
}
status 필드 분기 처리 (에러가 아닌 200 응답입니다):
| status | 의미 | 처리 |
|---|---|---|
matched | 검색 시점과 가격 동일 | book_token으로 바로 예약 진행 |
price_changed | 가격 변동 | 새 가격(pricing)을 고객에게 확인받은 뒤 함께 발급된 book_token으로 예약 |
sold_out | 매진 | book_token이 null — 다른 객실/날짜 제안 |
토큰이 무효이거나 만료된 경우 400 INVALID_TOKEN / 400 TOKEN_EXPIRED가 반환됩니다. 단일 숙소 검색부터 다시 시작하세요.
Rate Search (요금 상세 검색)
목적: 특정 숙소의 상세 요금 정보 조회 (목록·비교 화면용)
curl -X GET "https://api.tport.dev/channel/v1/search/rates?property_id=117417&checkin=2026-03-15&checkout=2026-03-16&adults=2" \
-H "Authorization: Bearer {access_token}"
| 파라미터 | 필수 | 설명 |
|---|---|---|
property_id | ✅ | 숙소 ID |
checkin / checkout | 체크인/체크아웃 날짜 | |
adults | 성인 수 | |
currency | 통화 코드 (기본 KRW) |
Rate Search는 조회 전용입니다. 예약에 필요한 book_token은 단일 숙소 검색 → price-check 흐름에서만 발급됩니다.
캐싱 전략
캐시 가능 여부
| 데이터 유형 | 캐싱 가능 | 권장 TTL | 이유 |
|---|---|---|---|
| 콘텐츠 (숙소/객실 정보) | ✅ 가능 | 24시간 | 변경 빈도 낮음 |
| Availability (빈방 여부) | ⚠️ 짧게만 | 5분 이내 | 재고 변동 빈번 |
| 가격 / book_token | ❌ 불가 | - | 예약 직전 price-check 필수 |
예약 직전 재검증
재고·가격 변경을 알리는 웹훅은 제공되지 않습니다 (웹훅은 예약 이벤트 4종만 제공). 캐시는 짧은 TTL(예: 5분)로만 사용하고, 예약 직전 price-check로 최신 가격·재고를 다시 확인하세요. 가격이 변동되었으면 새 book_token이 함께 발급되므로 안전하게 예약을 진행할 수 있습니다.
성능 최적화 전략
1. 병렬 검색
여러 숙소를 동시에 조회할 때는 병렬 요청을 사용하세요. 순차 호출 대비 3-5배 빠릅니다. 단, Rate Limit(Sandbox 60/분, Starter 600/분)을 고려해 동시성을 제한하세요.
권장: 비동기 HTTP 클라이언트 (Python: aiohttp, Node.js: Promise.all)
2. 페이지네이션
검색 결과가 많을 경우 한 번에 모두 로드하지 말고 page/per_page를 활용하세요 (페이지당 최대 100건).
3. Gzip 압축
Accept-Encoding: gzip 헤더를 추가하면 응답 크기가 70-80% 감소합니다.
일반적인 에러 시나리오
파라미터 검증 에러 (400 INVALID_REQUEST)
원인: checkin/checkout 누락, 날짜 형식 오류 등
해결: 클라이언트에서 날짜 유효성 검증 후 API 호출
price_check_token 만료 (400 TOKEN_EXPIRED)
원인: 검색 후 시간이 지나 토큰이 만료됨
해결: 단일 숙소 검색을 다시 호출하여 새 토큰 발급
업스트림 오류 (502 HUB_UPSTREAM_ERROR)
원인: ONDA Hub 업스트림 응답 오류
해결: 지수 백오프로 재시도
자세한 에러 코드는 에러 처리 가이드를 참고하세요.
다음 단계
- 예약 관리 - book_token으로 예약 생성하기
- 에러 처리 - 에러 코드 및 처리 방법
- OpenAPI 명세 - 전체 API 명세