ONDA

콘텐츠 연동

숙소, 객실, 패키지 정보를 연동하는 방법을 안내합니다.

ONDA Platform Engineering 관리

콘텐츠 연동

ONDA의 숙박 콘텐츠(숙소/객실 정보)를 효율적으로 동기화하고 최신 상태를 유지하는 전략을 안내합니다.

콘텐츠 연동 개요

콘텐츠 연동은 다음 세 가지 레벨로 구성됩니다:

숙소 (Property)
  └─ 객실 타입 (Room Type)
      └─ 패키지/요금제 (Rate Plan)

데이터 구조

레벨설명예시
Property호텔, 리조트, 펜션 등 숙박 시설서울 센트럴 호텔
Room Type객실 유형 및 구성디럭스 더블룸, 스위트룸
Rate Plan요금제 및 정책 (조식 포함, 환불 가능 등)조식 포함 프로모션

콘텐츠 정보(숙소/객실 설명, 이미지, 편의시설 등)는 자주 변경되지 않으므로 콘텐츠 파일 벌크 다운로드 방식을 사용할 수 있습니다. 가격/재고 정보는 실시간 API로만 조회 가능합니다.

콘텐츠 파일 벌크 다운로드

왜 벌크 다운로드인가?

콘텐츠 데이터(Property → RoomType → RatePlan)는 다음 특징을 가집니다:

  • 변경 빈도가 낮음: 숙소 설명, 이미지, 편의시설 등은 하루에 수십 번 조회되지만 주 1-2회 정도만 변경됨
  • 데이터 크기가 큼: 전체 숙소 정보를 건별 API로 조회하면 수천 건의 요청 필요
  • 일관성 보장: 특정 시점의 스냅샷을 받아 데이터 정합성 유지

콘텐츠 파일 엔드포인트

엔드포인트내용
GET /content/files/content숙소/객실/요금제 상세 콘텐츠 파일
GET /content/files/catalog숙소 카탈로그(목록) 파일

두 엔드포인트 모두 다운로드 URL을 반환합니다 (properties:read scope 필요):

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

{
  "data": {
    "download_url": "https://.../exports/content_20260305.json.gz",
    "format": "json",
    "compressed": true,
    "file_size_bytes": 15234567,
    "record_count": 1250,
    "generated_at": "2026-03-05T06:00:00Z",
    "expires_at": "2026-03-05T07:00:00Z"
  }
}

download_url은 expires_at 이전까지만 유효하므로, 발급 즉시 다운로드하세요.

다운로드 프로세스

다운로드 URL 발급

GET /content/files/content로 최신 콘텐츠 스냅샷의 다운로드 URL을 받습니다.

JSON 파일 다운로드

압축된 JSON 파일(gzip)을 다운로드하고 압축 해제합니다.

로컬 DB 동기화

전체 콘텐츠를 파싱하여 로컬 데이터베이스에 저장합니다.

정기 재동기화

하루 1회(새벽 시간대) 재다운로드로 변경 사항을 반영합니다.

다운로드 주기

시나리오권장 주기이유
초기 동기화시스템 구축 시 1회전체 데이터 로드
정기 갱신하루 1회 (새벽 시간대)변경 누락 방지
특정 숙소 갱신필요 시GET /properties/{id} 등 건별 조회

콘텐츠 변경을 알리는 웹훅은 제공되지 않습니다 (웹훅은 예약 이벤트 4종만 제공). 하루 1회 벌크 재다운로드를 기본으로 하고, 필요 시 건별 조회 API로 보완하세요.

콘텐츠 계층 이해하기

Property (숙소)

  • 기본 정보: 이름, 주소, 성급, 숙박 시설 유형
  • 위치 정보: 위도/경도, 주변 랜드마크
  • 편의시설: Wi-Fi, 주차장, 수영장, 레스토랑 등
  • 정책: 체크인/체크아웃 시간, 반려동물 정책, 어린이 정책
  • 이미지: 외관, 로비, 부대시설 사진

Room Type (객실 타입)

  • 객실 정보: 객실명, 크기(㎡), 최대 수용 인원
  • 침대 구성: 더블 베드 1개, 싱글 베드 2개 등
  • 객실 편의시설: TV, 미니바, 금고, 커피머신 등
  • 전망: 도시 전망, 바다 전망, 산 전망 등
  • 이미지: 객실 내부, 욕실, 전망 사진

Rate Plan (요금제)

  • 패키지 정보: 패키지명, 설명
  • 포함 사항: 조식 포함 여부, 조식 인원수
  • 취소 정책: flexible, moderate, strict, non_refundable
  • 결제 정책: 선결제, 현장 결제
  • 예약 제한: 최소/최대 숙박일, 사전 예약 기간

이미지 활용

숙소·객실 이미지 URL은 콘텐츠 응답(숙소 상세, 콘텐츠 파일)에 포함됩니다. 이미지는 원본을 매번 다운로드하지 말고 자체 CDN 또는 이미지 프록시를 통해 캐싱하여 제공하는 것을 권장합니다.

동기화 아키텍처 예시

권장 동기화 전략

  1. 초기 로드: 콘텐츠 파일 벌크 다운로드로 전체 콘텐츠 로드
  2. 일일 갱신: 매일 새벽 재다운로드로 전체 동기화 (변경 누락 방지)
  3. 건별 갱신: 필요 시 GET /properties/{id} 등 건별 조회로 보완
  4. 캐시 관리: 콘텐츠는 24시간 캐싱 가능 (가격/재고는 캐싱 금지)

다음 단계