최초 판매 준비

공급사가 ONDA로 숙소·객실타입·요금제 모델·요금제 콘텐츠를 생성(POST)하고, 이어서 요금재고(ARI)를 전송해 판매를 준비하는 최초 동기화 흐름입니다. 콘텐츠 생성 방향은 모두 공급사 → ONDA이며, 조회(GET)는 비상용 옵션입니다.

단계별 흐름

코드 카탈로그 조회 — GET /gds/vendor/meta (숙소·객실 생성 시 사용할 _tags 등 tag code 조회)
숙소 생성 — POST /gds/vendor/properties
객실타입 생성 — POST .../{vendor_property_id}/roomtypes
요금제 모델 생성 — POST .../{vendor_property_id}/rateplan-models
요금제 생성 — POST .../roomtypes/{vendor_roomtype_id}/rateplans (vendor_rateplan_model_id 결합)
요금·영업일 전송 — POST .../ari (요금제 단위)
재고 전송 — POST .../ari/avails (객실타입 단위 통합 재고)

체크리스트

GET /gds/vendor/meta로 _tags 등 코드 카탈로그 조회 후 매핑 테이블 내재화
숙소 → 객실타입 → 요금제 모델 → 요금제 순서로 생성
숙소·객실 생성 시 _tags에 meta 조회 tag code 사용
요금제 생성 시 vendor_rateplan_model_id 결합 확인
요금·영업일은 POST .../ari로 요금제 단위 전송, 재고는 POST .../ari/avails로 객실타입 단위 통합 재고 전송
각 호출은 전 채널 공통(default) 값과 채널별 값(channels[] 전체 선언)을 1회 호출에 함께 담아 전송
부분 전송 활용: ari는 변경 항목만 포함 (영업일 is_business_day / 요금 basic_price·sale_price·net_price)
ari/avails 재고는 룸온리(객실타입) 기준에 맞춤, 기간(from-to) 항목당 최대 730일
(옵션) 비상용 콘텐츠 조회(GET) 동작 확인

코드 카탈로그(meta) 활용

숙소·객실의 코드성 필드(_tags 등)는 임의 문자열이 아니라 ONDA가 정의한 tag code를 사용해야 합니다.

조회: GET /gds/vendor/meta — 사용 가능한 코드 목록 반환
최초 동기화(콘텐츠 생성) 전 meta 조회로 코드 매핑 테이블을 내재화합니다
콘텐츠 업데이트 시에도 동일 코드 체계를 참조해 _tags를 설정합니다
meta 코드 변경(추가·삭제) 대응을 위한 주기적 재조회 정책을 수립합니다

한국어 외 언어 콘텐츠 전송

콘텐츠에 한국어 외 언어를 포함할 때는 i18n 다국어 필드에 언어별 값을 전달합니다.

대상: 숙소·객실타입·요금제 모델·요금제의 i18n 필드
지원 언어 코드 체계를 정의합니다 (예: ko, en, ja, zh)
언어별 콘텐츠 매핑 및 기본(fallback) 언어 규칙을 정합니다
표기 불가 특수문자 제거 규칙을 함께 적용합니다

요금제 모델 · 요금제 구조

요금제는 객실타입(roomtype) × 요금제 모델(rateplan-model) 의 결합입니다. 객실타입과 요금제 모델은 모두 숙소(property) 하위에 있습니다.

요금제 모델 type 생성 규칙

숙소(property) 단위로 type별 생성 개수 제한이 다릅니다.

standalone: 숙소당 1개 필수, 최대 1개만 생성 가능
package: 생성 개수 제한 없음

채널 전용 요금제 — 요금제 모델 channels 필드

POST .../rateplan-models의 optional channels 필드로 채널 전용 판매를 지정합니다.

미전송 시 전체 채널 판매, 전송 시 channels에 포함된 채널에만 판매
채널 오픈 시 channels에 포함된 채널에만 요금제 매핑 생성 (해당 채널에 객실 매핑이 생성·오픈된 경우에 한함)
오픈 후 수정 동작
- 추가([131] → [131, 132]): 132만 매핑 생성
- 삭제([131, 132] → [131]): 기존 매핑 유지, 이후 생성되는 요금제는 132 매핑 미생성
- 빈값([131, 132] → []): 생성 가능한 모든 채널 매핑 생성

숙소 기본 추가 성인요금 (`settings.extra_adult_price`)

숙소 생성·수정 요청 바디의 settings object에 포함하는 숙소 단위 기본 추가 성인요금 필드입니다.

값: 정수(KRW). null 전송 시 미설정으로 초기화됩니다.
레거시 채널: Agoda·Trip.com의 Occupancy Based 요금에 포함됩니다. Per Room 요금에는 포함되지 않습니다.
플러스 채널: 인원추가비용으로 사용됩니다.

콘텐츠 엔드포인트

경로 prefix는 /gds/vendor 입니다.

객체	메서드	경로	필수값 · 비고
숙소	`POST`	`/properties`	필수 `id`, `i18n (ko-kr)` · `settings.extra_adult_price` 지원
숙소	`PATCH`	`/properties/{vendor_property_id}`	숙소 수정 · `extra_adult_price` 초기화(`null`)
숙소	`GET`	`/properties` · `/{vendor_property_id}`	비상용 조회
객실타입	`POST`	`/properties/{vendor_property_id}/roomtypes`	필수 `id`, `i18n (ko-kr)`
객실타입	`PATCH`	`.../roomtypes/{vendor_roomtype_id}`	객실 수정
객실타입	`GET`	`.../roomtypes` · `/{vendor_roomtype_id}`	비상용 조회
요금제 모델	`POST`	`/properties/{vendor_property_id}/rateplan-models`	필수 `id`, `i18n (ko-kr)` · optional `channels`
요금제 모델	`PATCH`	`.../rateplan-models/{vendor_rateplan_model_id}`	모델 수정
요금제 모델	`GET`	`.../rateplan-models` · `/{vendor_rateplan_model_id}`	비상용 조회
요금제	`POST`	`.../roomtypes/{vendor_roomtype_id}/rateplans`	필수 `id`, `vendor_rateplan_model_id`
요금제	`PATCH`	`.../rateplans/{vendor_rateplan_id}`	요금제 수정
요금제	`GET`	`.../rateplans` · `/{vendor_rateplan_id}`	비상용 조회

경고

요금제 생성 시 요청 바디 필수값 vendor_rateplan_model_id로 요금제 모델과 결합되는지 반드시 검증하세요.

요금·영업일(ARI) · 재고(Avails) 전송

요금재고 전송은 요금·영업일과 재고로 분리돼 있습니다.

메서드	경로	설명
`POST`	`.../ari`	요금·영업일 (요금제 `vendor_rateplan_id` 단위)
`POST`	`.../ari/avails`	재고 `vacancy` (객실타입 단위 통합 재고 · 항목당 최대 730일)

두 엔드포인트 모두 전 채널 공통 값과 채널별 값(channels[] 배열)을 1회 호출에 함께 담아 전송합니다. channels[]는 채널별 설정 전체 선언이므로, 배열에 없는 채널 설정은 항목 구간(from-to) 내에서 삭제됩니다.

요금·영업일 — 숙박(overnight)

[
  {
    "vendor_roomtype_id": "VRT-001",
    "vendor_rateplan_id": "VRP-001",
    "type": "overnight",
    "from": "2026-01-01",
    "to": "2026-01-31",
    "basic_price": 0,
    "net_price": 0,
    "sale_price": 12000,
    "is_business_day": 0,
    "channels": [
      { "channel_id": 1, "basic_price": 0, "net_price": 0, "sale_price": 10000, "is_business_day": 0 },
      { "channel_id": 2, "basic_price": 0, "net_price": 0, "sale_price": 11000 }
    ]
  }
]

요금·영업일 — 대실(dayuse)

[
  {
    "vendor_roomtype_id": "VRT-001",
    "vendor_rateplan_id": "VRP-001",
    "type": "dayuse",
    "from": "2026-01-01",
    "to": "2026-01-31",
    "basic_price": 0,
    "net_price": 0,
    "sale_price": 12000,
    "is_business_day": 0,
    "use_from": "14:00",
    "use_to": "20:00",
    "use_time": 240,
    "channels": [
      { "channel_id": 1, "sale_price": 10000, "use_from": "14:00", "use_to": "20:00", "use_time": 240 }
    ]
  }
]

재고 — 객실타입 단위 통합 재고

[
  {
    "vendor_roomtype_id": "VRT-001",
    "from": "2026-01-01",
    "to": "2026-01-31",
    "vacancy": 5,
    "channels": [
      { "channel_id": 1, "vacancy": 3 },
      { "channel_id": 2, "vacancy": 5 }
    ]
  }
]

전송 규칙

POST .../ari — 요금·영업일만 요금제 단위로 전송합니다. channels에 없는 채널 설정은 항목 구간 내에서 삭제되며(생략·빈 배열 = 전 채널 설정 삭제), 채널 오브젝트는 값 필드가 하나 이상 있어야 합니다(channel_id만 있으면 400). 생략한 필드는 기존값이 유지됩니다. use_from·use_to·use_time(분)은 대실 항목에만 전송할 수 있습니다.
POST .../ari/avails — 재고를 객실타입 단위 통합 재고로 반영합니다. channels[]는 채널별 재고 전체 선언이며, 배열에 없는 채널 재고는 구간 내에서 삭제됩니다. 기간(from-to)은 항목당 최대 730일입니다.

type 구분 (숙박 / 대실)

ari와 예약(/bookings)은 type으로 상품 유형을 구분합니다.

채널 유형	사용하는 `type`
플러스 채널	`overnight`
직연동 채널	`overnight` (대실을 지원하는 채널은 `dayuse` 추가)

ARI는 필요한 항목만 부분 전송할 수 있습니다

부분 전송: 변경하고 싶은 항목만 요청에 포함하면 됩니다
항목별 필드: 영업일 = is_business_day / 요금 = basic_price·sale_price·net_price / 재고 = vacancy(ari/avails)
대실 전용: use_from·use_to·use_time는 대실인 경우에만 전송 가능
채널별 통합 전송: 공통 값은 최상위 필드, 채널별 값은 channels[] 배열에 담아 1회 호출로 전송

재고 운영 기준 — 룸온리(객실타입) 재고에 맞춤

채널마다 재고 기준이 다릅니다.

룸온리(객실타입) 기준: 부킹닷컴 · 아고다 · 트립닷컴
요금제 기준: 익스피디아 · 플러스 채널 (일부 선택 경우 존재)

ONDA는 객실타입 기준 재고를 사용하므로 룸온리 재고에 맞추어 전송하고, package 재고는 standalone 재고와 동일하게 전송하세요.

단계별 흐름​

체크리스트​

코드 카탈로그(meta) 활용​

한국어 외 언어 콘텐츠 전송​

요금제 모델 · 요금제 구조​

숙소 기본 추가 성인요금 (settings.extra_adult_price)​

콘텐츠 엔드포인트​

요금·영업일(ARI) · 재고(Avails) 전송​