# ONDA Partner Developer Center > ONDA API 통합 개발자 문서 - 벤더 및 채널 파트너를 위한 REST API 레퍼런스 ## docs - [ONDA Partner Developer Center](/docs/): ONDA Hub API 연동을 위한 개발자 문서. 숙박 플랫폼 연동을 빠르고 쉽게! 벤더 파트너와 채널 파트너를 위한 REST API 가이드, 25,000+ 숙박 상품 실시간 연동. - [API 연동 프로세스](/docs/api/channel/api-integration-process): ONDA API 연동 단계별 프로세스 안내 - [Authorization](/docs/api/channel/authorization): ONDA API 인증키 안내 - [Cancel Reservation](/docs/api/channel/cancel-reservation) - [Cancellation Policy](/docs/api/channel/cancellation-policy): 취소환불 정책 가이드 - [Cancellation & Refund Policy before reservation](/docs/api/channel/cancellation-refund-policy-before-reservation) - [Channel API](/docs/api/channel/channel-api) - [Check API Server](/docs/api/channel/check-api-server) - [Search Property Detail](/docs/api/channel/check-availabilities-rates): 조건에 부합하는 숙소의 예약 가능한 모든 객실타입과 요금제를 **실시간**으로 응답합니다. - [Get Lowest Price](/docs/api/channel/check-lowest-price): 특정 기간 내의 숙소의 최저가 정보를 제공합니다. - [Check Reservation](/docs/api/channel/check-reservation) - [Check Avail before reservation](/docs/api/channel/check-vendor-avail-before-reservation) - [Create Reservation](/docs/api/channel/create-reservation) - [DB Cache Type](/docs/api/channel/db-cache-type): DB에 재고/요금을 저장하는 연동 타입 - [Extra Charge](/docs/api/channel/extra-charge): 추가인원 요금 처리 가이드 - [Get Inventories](/docs/api/channel/get-inventories): 정해진 기간에 대한 특정 숙소의 모든 요금제의 재고와 가격 등 상세 정보를 응답합니다. - [Get Property Detail](/docs/api/channel/get-property-detail) - [Get Property List](/docs/api/channel/get-property-list): 전체 숙소 목록을 응답합니다. - [Get Rateplan Detail](/docs/api/channel/get-rateplan-detail) - [Get Rateplan List](/docs/api/channel/get-rateplan-list) - [Get Rateplan List by Property ID](/docs/api/channel/get-rateplan-list-by-property-id): 숙소별 요금제 목록을 응답합니다. - [Get Roomtype Detail](/docs/api/channel/get-roomtype-detail) - [Get Roomtype List](/docs/api/channel/get-roomtype-list) - [Get Updated Rateplan List](/docs/api/channel/get-updated-rateplan-list): lastdate 값을 기준으로 업데이트된 요금제 목록을 응답합니다. - [Get Updated Roomtype List](/docs/api/channel/get-updated-roomtype-list): lastdate 값을 기준으로 업데이트된 객실 목록을 응답합니다. - [Image Contents](/docs/api/channel/image-contents): 이미지 컨텐츠 저장 및 리사이즈 가이드 - [Property Tags](/docs/api/channel/property-tags): 숙소 관련 태그 정보 - [Real Time Type](/docs/api/channel/realtime-type): 실시간 API 호출 방식의 연동 타입 - [Roomtype Tags](/docs/api/channel/roomtype-tags): 객실 관련 태그 정보 - [Search Property](/docs/api/channel/search-property): 조건에 부합하는 이용 가능한 숙소의 가장 저렴한 요금을 **실시간**으로 응답합니다. - [Reservation Comparison](/docs/api/channel/settlement-comparison) - [Test Property](/docs/api/channel/test-property): 테스트용 숙소 정보 및 사용 가이드 - [Get Updated Inventories](/docs/api/channel/update-inventories): 업데이트된 재고와 가격 등 상세 정보를 응답합니다. - [Webhook Overview](/docs/api/channel/webhook-overview): ONDA Webhook API 개요 및 설정 가이드 - [Webhook Specifications](/docs/api/channel/webhook-specifications): Webhook API 상세 스펙 및 샘플 - [숙소 생성](/docs/api/vendor-v3/create-property): - 공급사 숙소를 ONDA에 생성합니다. 객실타입·요금제 모델·요금제가 모두 이 숙소 하위에 생성되므로 콘텐츠 연동의 첫 단계입니다. - [숙소별 채널 신청](/docs/api/vendor-v3/create-property-channel-request): - 해당 채널에 판매 시작(ON) 또는 종료(OFF) 신청을 생성합니다. - [요금제 생성](/docs/api/vendor-v3/create-rateplan): - 객실타입 하위에 요금제를 생성합니다. 요금·영업일 전송의 기준 단위이므로, 판매를 시작하려면 반드시 필요합니다. - [요금제 모델 생성](/docs/api/vendor-v3/create-rateplan-model): - 숙소 단위로 요금제 모델을 생성합니다. 요금제는 객실타입과 이 모델의 결합으로 정의되므로, 요금제를 만들기 전에 먼저 생성해야 합니다. - [객실타입 생성](/docs/api/vendor-v3/create-roomtype): - 숙소 하위에 객실타입을 생성합니다. 숙소를 먼저 생성해야 호출할 수 있습니다. - [예약 조회](/docs/api/vendor-v3/get-booking): - 예약 번호로 예약 한 건의 상세를 조회합니다. - [채널 인증 URL 조회](/docs/api/vendor-v3/get-channel-authorization-url): - **에어비앤비 전용입니다.** 채널 메타의 `requires_cms_authorization`이 `true`인 채널에서만 사용하며, 현재 해당하는 채널은 에어비앤비뿐입니다. 다른 채널에 호출하면 `403`이 반환됩니다. - [채널 숙소 정보 조회](/docs/api/vendor-v3/get-channel-property): - 채널 측에 등록된 숙소와 그 하위 객실·요금제 정보를 조회합니다. - [코드 카탈로그 조회](/docs/api/vendor-v3/get-meta-codes): - 콘텐츠 push에 사용할 pcs.codes.code 값을 code_type별 계층 트리로 조회합니다. - [숙소 단건 조회](/docs/api/vendor-v3/get-property): - 숙소 한 건의 콘텐츠와 판매 상태를 조회합니다. - [숙소별 채널 상세](/docs/api/vendor-v3/get-property-channel-request): 현재 공급사 화이트리스트나 채널 상태와 무관하게 해당 채널의 최신 신청 상태와 신청 이력을 최신순 최대 100건 조회합니다. - [숙소 채널 설정 조회](/docs/api/vendor-v3/get-property-channel-settings): - 숙소에 대한 채널별 부가 설정을 조회합니다. - [숙소 매핑 조회](/docs/api/vendor-v3/get-property-mapping): - 숙소와 채널 사이의 매핑 상태를 조회합니다. - [요금제 단건 조회](/docs/api/vendor-v3/get-rateplan): - 요금제 한 건의 정보와 판매 상태를 조회합니다. - [요금제 매핑 조회](/docs/api/vendor-v3/get-rateplan-mapping): - 요금제와 채널 요금제 사이의 매핑 상태를 조회합니다. - [요금제 모델 단건 조회](/docs/api/vendor-v3/get-rateplan-model): - 요금제 모델 한 건의 판매 조건을 조회합니다. - [객실타입 단건 조회](/docs/api/vendor-v3/get-roomtype): - 객실타입 한 건의 콘텐츠와 판매 상태를 조회합니다. - [객실 채널 설정 조회](/docs/api/vendor-v3/get-roomtype-channel-settings): - 공급사의 객실에 대한 채널별 설정을 조회합니다. - [객실 매핑 조회](/docs/api/vendor-v3/get-roomtype-mapping): - 객실타입과 채널 객실 사이의 매핑 상태를 조회합니다. - [정산 비교 조회](/docs/api/vendor-v3/get-settlement-comparison): - 정산 금액 데이터를 조회합니다. 공급사 내부 정산과 대조할 때 사용합니다. - [에어비앤비 인증 구현](/docs/api/vendor-v3/guides/airbnb-authorization): 에어비앤비 채널 연동에 필요한 호스트 OAuth 인증 구현 가이드 - [직연동 레거시 채널 오픈](/docs/api/vendor-v3/guides/channel-open-legacy): Booking.com·Agoda·Expedia 등 레거시 직연동 채널의 오픈 흐름 - [플러스 채널 오픈](/docs/api/vendor-v3/guides/channel-open-plus): ONDA가 OTA 계약을 대행하는 플러스 채널의 오픈 신청 흐름 - [콘텐츠 변경](/docs/api/vendor-v3/guides/content-update): 숙소·객실타입·요금제 콘텐츠 변경분 전송 - [최초 판매 준비](/docs/api/vendor-v3/guides/initial-setup): 콘텐츠 생성부터 요금·재고 전송까지 최초 동기화 흐름 - [매핑 수정 · 판매 중지](/docs/api/vendor-v3/guides/mapping-update): 직연동 채널의 매핑 수정과 판매 중지 처리 - [공통 · 개요](/docs/api/vendor-v3/guides/overview): Vendor API 3.0 연동 전체 구조와 출시 전 확인 항목 - [취소환불 정책](/docs/api/vendor-v3/guides/refund-policy): 숙소 기본 정책과 일자별 정책의 처리 규칙 - [직연동 채널 예약](/docs/api/vendor-v3/guides/reservation-direct): 직연동 채널의 가예약·확정·변경·취소 처리 흐름 - [플러스 채널 예약](/docs/api/vendor-v3/guides/reservation-plus): 플러스 채널의 가예약·확정·변경·취소 처리 흐름 - [정산 조회](/docs/api/vendor-v3/guides/settlement): 정산 금액 데이터 조회 및 대사 - [상태 변경](/docs/api/vendor-v3/guides/status-update): 숙소·객실타입·요금제 모델·요금제의 판매 상태 변경 - [예약 리스트 조회](/docs/api/vendor-v3/list-bookings): - 기간으로 예약 목록을 조회합니다. - [판매 채널 조회](/docs/api/vendor-v3/list-channels): - 공급사의 판매 채널 목록을 조회합니다. - [숙소 목록 조회](/docs/api/vendor-v3/list-properties): - 공급사가 등록한 숙소 목록을 조회합니다. - [숙소별 채널 신청 목록](/docs/api/vendor-v3/list-property-channel-requests): 현재 공급사 화이트리스트나 채널 상태와 무관하게 숙소에서 실제 신청 이력이 있는 채널과 각 채널의 최신 신청 상태를 조회합니다. - [요금제 모델 목록 조회](/docs/api/vendor-v3/list-rateplan-models): - 숙소에 등록된 요금제 모델 목록을 조회합니다. - [요금제 목록 조회](/docs/api/vendor-v3/list-rateplans): - 객실타입에 연결된 요금제 목록을 조회합니다. - [객실타입 목록 조회](/docs/api/vendor-v3/list-roomtypes): - 숙소에 속한 객실타입 목록을 조회합니다. 응답에는 각 객실타입에 연결된 요금제 정보도 함께 담깁니다. - [ONDA Vendor API 3.0](/docs/api/vendor-v3/onda-vendor-api-3-0): ONDA Vendor API 3.0 — 공급사(Vendor) 연동 API - [재고 전송](/docs/api/vendor-v3/push-avails): - 재고(vacancy)를 설정합니다(항목당 `vacancy` 필수). - [요금/영업일 전송](/docs/api/vendor-v3/push-rates): - 요금·영업일을 설정합니다. - [숙소 수정](/docs/api/vendor-v3/update-property): - 숙소 콘텐츠와 판매 상태를 수정합니다. - [숙소 채널 설정 저장](/docs/api/vendor-v3/update-property-channel-settings): RFC 7396 JSON Merge Patch. null 인 경우 해당 키를 삭제합니다. - [숙소 매핑 수정](/docs/api/vendor-v3/update-property-mapping): - 숙소와 채널 사이의 매핑을 수정합니다. - [요금제 수정](/docs/api/vendor-v3/update-rateplan): - 요금제의 판매 상태를 수정합니다. - [요금제 매핑 수정](/docs/api/vendor-v3/update-rateplan-mapping): - 요금제와 채널 요금제 사이의 매핑을 수정합니다. - [요금제 모델 수정](/docs/api/vendor-v3/update-rateplan-model): - 요금제 모델의 판매 조건을 수정합니다. 이 모델을 참조하는 모든 요금제에 함께 적용됩니다. - [객실타입 수정](/docs/api/vendor-v3/update-roomtype): - 객실타입 콘텐츠와 판매 상태를 수정합니다. - [객실 채널 설정 저장](/docs/api/vendor-v3/update-roomtype-channel-settings): RFC 7396 JSON Merge Patch. null 인 경우 해당 키를 삭제합니다. - [객실 매핑 수정](/docs/api/vendor-v3/update-roomtype-mapping): - 객실타입과 채널 객실 사이의 매핑을 수정합니다. - [Vendor API 3.0](/docs/api/vendor-v3/vendor-api-v3): ONDA Vendor API 3.0 개요 및 소개 - [예약 취소](/docs/api/vendor-v3/webhook-cancel-booking): - 이 엔드포인트는 공급사가 구현하고 ONDA가 호출합니다. - [예약 확정](/docs/api/vendor-v3/webhook-confirm-booking): - 이 엔드포인트는 공급사가 구현하고 ONDA가 호출합니다. - [예약 생성](/docs/api/vendor-v3/webhook-create-booking): - 이 엔드포인트는 공급사가 구현하고 ONDA가 호출합니다. - [취소/환불 정책 조회](/docs/api/vendor-v3/webhook-get-refund-policy): - 이 엔드포인트는 공급사가 구현하고 ONDA가 호출합니다. - [예약 변경](/docs/api/vendor-v3/webhook-modify-booking): - 이 엔드포인트는 공급사가 구현하고 ONDA가 호출합니다. - [기본 연동](/docs/api/vendor/basic-integration): Vendor API 기본 연동 가이드 - [Cancel Reservation](/docs/api/vendor/cancel-reservation): - 온다 > 공급사 (온다가 공급사를 호출해 저장합니다.) - [Cancellation & Refund Policy before reservation](/docs/api/vendor/cancellation-refund-policy-before-reservation): - 온다 > 공급사 (온다가 공급사를 호출해 저장합니다.) - [Check Reservation](/docs/api/vendor/check-reservation): - 온다 > 공급사 (온다가 공급사를 호출해 저장합니다.) - [Confirm Reservation](/docs/api/vendor/confirm-reservation): - 온다 > 공급사 (온다가 공급사를 호출해 저장합니다.) - [Create Reservation](/docs/api/vendor/create-reservation): - 온다 > 공급사 (온다가 공급사를 호출해 저장합니다.) - [에러 코드](/docs/api/vendor/error-codes): 공급사가 온다에 에러를 응답할 때 사용하는 표준 에러 코드와 응답 포맷을 안내합니다. - [Get Avails](/docs/api/vendor/get-avails): - 온다 > 공급사 (온다가 공급사를 호출해 저장합니다.) - [Get Property List (HotelPlus)](/docs/api/vendor/get-property-list-hotelplus): - 공급사 > 온다 (공급사가 온다를 호출해 저장합니다.) - [Get Rates](/docs/api/vendor/get-rates): - 온다 > 공급사 (온다가 공급사를 호출해 저장합니다.) - [Get Roomtype List (HotelPlus)](/docs/api/vendor/get-roomtype-list-hotelplus): - 공급사 > 온다 (공급사가 온다를 호출해 저장합니다.) - [Get Updated Avails](/docs/api/vendor/get-updated-avails): - dapi.tport.dev -> 공급사가 지정한 url 위치 입니다. - [Get Updated Rates](/docs/api/vendor/get-updated-rates): - dapi.tport.dev -> 공급사가 지정한 url 위치 입니다. - [Modify Reservation](/docs/api/vendor/modify-reservation): - 온다 > 공급사 (온다가 공급사를 호출해 저장합니다.) - [ONDA → Vendor Request](/docs/api/vendor/onda-to-vendor-request): 온다에서 벤더로의 데이터 요청 방식 가이드 - [숙소 콘텐츠](/docs/api/vendor/property-content): 숙소 콘텐츠 체크리스트 - [숙소 생성](/docs/api/vendor/property-creation): 숙소 정보 생성 가이드 - [정보 최신화](/docs/api/vendor/property-management): 숙소 정보 관리 가이드 - [예약](/docs/api/vendor/reservation): 예약 관리 가이드 - [Check Reservation](/docs/api/vendor/reservation-information): - 공급사 > 온다 - [객실 콘텐츠](/docs/api/vendor/room-content): 객실 콘텐츠 체크리스트 - [Push Setting Avails](/docs/api/vendor/setting-avails): - 공급사 > 온다 - [Push Setting Business-days](/docs/api/vendor/setting-business-days): - 공급사 > 온다 - [Push Setting Rates](/docs/api/vendor/setting-rates): - 공급사 > 온다 - [Reservation Comparison](/docs/api/vendor/settlement-comparison): - 공급사 > 온다 - [특수 기호](/docs/api/vendor/special-characters): 특수 기호 사용 가이드 - [Tags](/docs/api/vendor/tags): 태그 시스템 가이드 - [Update Property Status](/docs/api/vendor/update-property-status): - 공급사 > 온다 - [Update Rateplan Status](/docs/api/vendor/update-rateplan-status): - 공급사 > 온다 - [Update Roomtype Status](/docs/api/vendor/update-roomtype-status): - 공급사 > 온다 - [Vendor API](/docs/api/vendor/vendor-api): ONDA Vendor API 개요 및 소개 - [Get Updated Property List](/docs/api/vendor/vendor-changed-property-list): - dapi.tport.dev -> 공급사가 지정한 url 위치 입니다. - [Get Property Detail](/docs/api/vendor/vendor-property-detail): - 온다 > 공급사 (온다가 공급사를 호출해 저장합니다.) - [Get Property List](/docs/api/vendor/vendor-property-list): - 온다 > 공급사 (온다가 공급사를 호출해 저장합니다.) - [Get Roomtype Detail](/docs/api/vendor/vendor-roomtype-detail): - 온다 > 공급사 (온다가 공급사를 호출해 저장합니다.) - [Get Roomtype List](/docs/api/vendor/vendor-roomtype-list): - 온다 > 공급사 (온다가 공급사를 호출해 저장합니다.) - [Vendor → ONDA Request](/docs/api/vendor/vendor-to-onda-request): 벤더에서 온다로의 데이터 전송 방식 가이드 - [Get Updated Roomtype List](/docs/api/vendor/vendor-updated-roomtype-list): - dapi.tport.dev -> 공급사가 지정한 url 위치 입니다. - [기타 API](/docs/api/vendor/기타-api): 기타 API - [숙소 생성 API](/docs/api/vendor/숙소-생성-api): 숙소 생성 API - [숙소 정보 관리 (Push) API](/docs/api/vendor/숙소-정보-관리-push-api): 숙소 정보 관리 (Push) API - [숙소 정보 관리 (Sync) API](/docs/api/vendor/숙소-정보-관리-sync-api): 숙소 정보 관리 (Sync) API - [예약 API](/docs/api/vendor/예약-api): 예약 API - [자주 묻는 질문 (FAQ)](/docs/faq): ONDA API 연동 관련 자주 묻는 질문. API 키 발급, 개발 기간, 인증 방법, Real Time Type vs DB Cache Type, Webhook, 테스트 환경 등 연동 전반에 대한 FAQ - [ONDA hub 시작하기](/docs/getting-started): ONDA Hub API 연동 단계별 가이드. 파트너 유형 파악부터 계약, 개발, 런칭까지 평균 1개월 소요. Vendor API와 Channel API 연동 방법을 상세히 안내합니다. - [용어 정리](/docs/glossary): ONDA API 문서에서 사용되는 주요 용어 사전. Vendor, Channel, Property, Rate Plan, Inventory, Real Time Type, DB Cache Type 등 숙박 플랫폼 연동 필수 용어 해설. - [ONDA Hub 소개](/docs/introduction/): ONDA Hub는 70+ 채널과 25,000+ 숙박 시설을 연결하는 통합 온라인 유통 플랫폼. 벤더 파트너와 채널 파트너를 위한 표준 API로 숙박 비즈니스를 확장하세요. - [문서 작성 스타일 가이드](/docs/style-guide): ONDA API 문서 작성을 위한 스타일 가이드 --- # Full Documentation Content # ONDA Partner Developer Center ONDA Hub API 연동을 위한 개발자 문서에 오신 것을 환영합니다. 숙박 상품 공급자와 판매 채널을 연결하는 통합 유통 플랫폼, ONDA Hub의 API를 통해 비즈니스를 확장하세요. ## 시작하기 전에[​](#시작하기-전에 "시작하기 전에에 대한 직접 링크") ### 어떤 파트너이신가요?[​](#어떤-파트너이신가요 "어떤 파트너이신가요?에 대한 직접 링크") ONDA Hub는 두 가지 파트너 유형을 지원합니다: #### Vendor Partner (공급자)[​](#vendor-partner-공급자 "Vendor Partner (공급자)에 대한 직접 링크") 숙박 상품을 ONDA에 공급하고 70+ 채널에 판매하고 싶으신가요? * 호텔, 리조트, 펜션 등 숙박 시설 * PMS 시스템 제공사 * 호텔 체인 및 상품 공급사 **→ [Vendor API 문서 보기](/docs/api/vendor/vendor-api)** #### Channel Partner (판매자)[​](#channel-partner-판매자 "Channel Partner (판매자)에 대한 직접 링크") ONDA의 25,000+ 숙박 상품을 판매하고 싶으신가요? * OTA (Online Travel Agency) * 여행사 및 메타서치 엔진 * 숙박 예약 플랫폼 **→ [Channel API 문서 보기](/docs/api/channel/channel-api)** ## 빠른 시작 가이드[​](#빠른-시작-가이드 "빠른 시작 가이드에 대한 직접 링크") ONDA Hub API 연동은 4단계로 진행됩니다: ### 1. 파트너 유형 파악[​](#1-파트너-유형-파악 "1. 파트너 유형 파악에 대한 직접 링크") 귀사의 비즈니스 모델에 맞는 API를 선택하세요. **→ [파트너 유형 가이드](/docs/getting-started#1-%ED%8C%8C%ED%8A%B8%EB%84%88-%EC%9C%A0%ED%98%95-%ED%8C%8C%EC%95%85%ED%95%98%EA%B8%B0)** ### 2. 계약 및 인증 정보 발급[​](#2-계약-및-인증-정보-발급 "2. 계약 및 인증 정보 발급에 대한 직접 링크") ONDA와 파트너 계약 후 API 키를 발급받으세요. **문의:** [문의하기](https://onda.me/ko/contact/) ### 3. API 연동 개발[​](#3-api-연동-개발 "3. API 연동 개발에 대한 직접 링크") 평균 개발 기간: **1개월 (1 M/M)** **기술 지원:** ### 4. 테스트 및 런칭[​](#4-테스트-및-런칭 "4. 테스트 및 런칭에 대한 직접 링크") QA 완료 후 정식 서비스를 시작하세요. ## 주요 문서[​](#주요-문서 "주요 문서에 대한 직접 링크") ### 가이드[​](#가이드 "가이드에 대한 직접 링크") * **[ONDA Hub 소개](/docs/introduction)** - 플랫폼 상세 소개 * **[시작하기](/docs/getting-started)** - 단계별 연동 가이드 * **[용어 정리](/docs/glossary)** - API 용어 설명 ### API 레퍼런스[​](#api-레퍼런스 "API 레퍼런스에 대한 직접 링크") * **[Vendor API](/docs/api/vendor/vendor-api)** - 공급자용 API * **[Channel API](/docs/api/channel/channel-api)** - 판매자용 API ### 리소스[​](#리소스 "리소스에 대한 직접 링크") * **[Changelog](/changelog)** - API 업데이트 소식 ## 기술 스펙[​](#기술-스펙 "기술 스펙에 대한 직접 링크") ### API 엔드포인트[​](#api-엔드포인트 "API 엔드포인트에 대한 직접 링크") ``` 운영환경: https://gds.tport.io 개발환경: https://dapi.tport.dev ``` ### 기본 정보[​](#기본-정보 "기본 정보에 대한 직접 링크") * **프로토콜:** HTTPS * **데이터 형식:** JSON (UTF-8) * **인증:** API Key / OAuth 2.0 ## 기술 지원[​](#기술-지원 "기술 지원에 대한 직접 링크") ### 문의 채널[​](#문의-채널 "문의 채널에 대한 직접 링크") * **기술 문의:** * **파트너 신청:** [문의하기](https://onda.me/ko/contact/) ### 지원 시간[​](#지원-시간 "지원 시간에 대한 직접 링크") * 평일 10:00 - 18:00 (KST) * 긴급 장애: 24/7 대응 *** --- # API 연동 프로세스 ## 1. 연동 방식 체크[​](#1-연동-방식-체크 "1. 연동 방식 체크에 대한 직접 링크") 채널의 서비스에 따라 연동 방식의 사전 정보를 확보하기 위해 아래 내용을 확인합니다. * 요금 및 재고를 저장하여 서비스하는지? 혹은 클라이언트에서 그때 마다 호출하여 서비스 하는지? * 채널의 서비스 형태가 메타서치 플랫폼인지? OTA 버티컬 서비스인지? ## 2. API 문서 검토[​](#2-api-문서-검토 "2. API 문서 검토에 대한 직접 링크") NDA 작성 후, 채널에 해당 API 문서를 전달하고 검토합니다. ## 3. 연동 개발 전 사전 미팅[​](#3-연동-개발-전-사전-미팅 "3. 연동 개발 전 사전 미팅에 대한 직접 링크") API 문서 검토가 완료되면, 전반적인 연동 가이드 미팅을 갖습니다. 이 미팅을 통해 아래 내용을 동기화 합니다. * \[채널 > ONDA] 채널에서 연동하고자 하는 자사 서비스를 리뷰합니다. * \[ONDA > 채널] 전반적인 연동 과정을 가이드 합니다. * \[ONDA > 채널] 대략적인 개발일정을 산출하고 동기화 합니다. ## 4. 연동 개발[​](#4-연동-개발 "4. 연동 개발에 대한 직접 링크") 연동 개발 방향은 두 가지 서비스 타입에 의해 결정됩니다. 이는 '1. 연동 방식 체크' 에서 사전 확보된 정보를 통해 가이드 됩니다.
타입의 가장 큰 차이점은 '재고 및 요금'의 처리 방식입니다. 아래 두 가지 서비스 타입의 Sequence Diagram 을 확인할 수 있습니다. * [DB Cache Type](ref:db-cache-type) * [Real Time Type](ref:real-time-type) ## 5. 테스트[​](#5-테스트 "5. 테스트에 대한 직접 링크") 온다와 판매사의 개발환경에서 API테스트를 진행합니다. * 상품 등록 * 요금 재고 동기화 * 예약 테스트 * 웹훅 테스트 ## 6. 라이브 배포[​](#6-라이브-배포 "6. 라이브 배포에 대한 직접 링크") 개발환경에서의 테스트가 완료된 후, 양사의 운영환경에 배포 후 실제 상품을 등록하고 판매를 시작합니다. --- # Authorization ## Authorization Key?[​](#authorization-key "Authorization Key?에 대한 직접 링크") ONDA의 API 를 호출하기 위해서는 인증키(Authorization Key) 가 필요합니다.
인증키는 개발환경 인증키와 운영환경 인증키로 나뉘어져있으며, 단계별로 발급하여 담당 매니저가 별도 공유합니다. ## 개발환경(Dev) 인증키[​](#개발환경dev-인증키 "개발환경(Dev) 인증키에 대한 직접 링크") 개발환경 인증키는 ONDA 와 NDA 작성 또는 초기 계약 체결 이후 전달되어 집니다. ## 운영환경(Live) 인증키[​](#운영환경live-인증키 "운영환경(Live) 인증키에 대한 직접 링크") 운영환경 인증키는 개발환경을 통한 개발 및 테스트까지 완료된 경우, 운영환경 호스트 도메인과 함께 전달되어 집니다.
개발환경에서 테스트가 완료되기 이전에는 절대 전달되어지지 않습니다. --- # Cancel Reservation ``` PUT /properties/:property_id/bookings/:booking_number/cancel ``` ## Request[​](#request "Request에 대한 직접 링크") ## Responsesapplication/json[​](#responses "responses에 대한 직접 링크") * 200 * 400 --- # Cancellation Policy > ❗️ > > 검색 시점의 취소환불 정책과 **실제 예약 건의 취소환불 정책이 다를 수 있습니다**. 클레임 방지를 위해 반드시 이 가이드를 따라주세요. ## 핵심 요약[​](#핵심-요약 "핵심 요약에 대한 직접 링크") * **두 가지 정책 존재**: Static Policy(검색용)와 Dynamic Policy(실제 적용)가 있습니다 * **실제 취소는 Dynamic Policy**: 예약 취소 시 Dynamic Policy가 적용됩니다 * **예약 직전 확인 필수**: 결제 전 반드시 Dynamic Policy를 조회하여 고객에게 안내하세요 ## 두 가지 취소환불 정책[​](#두-가지-취소환불-정책 "두 가지 취소환불 정책에 대한 직접 링크") ONDA의 취소환불 정책은 **Static Policy**와 **Dynamic Policy** 두 가지로 나뉩니다. | 구분 | Static Policy | Dynamic Policy | | -------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | | **용도** | 검색 결과 표시용 | 실제 취소 시 적용 | | **특징** | 숙소 단위 기본 정책 (보수적) | 객실/시간별 실제 정책 | | **API** | [Search Property Detail](/docs/api/channel/check-availabilities-rates) | [Cancellation & Refund Policy before reservation](/docs/api/channel/cancellation-refund-policy-before-reservation) | | **필드** | `refund_policy` object | `refund_policy` object | ## Static Policy (정적인 정책)[​](#static-policy-정적인-정책 "Static Policy (정적인 정책)에 대한 직접 링크") 숙소 단위로 설정된 **기본 정책**으로, 가장 보수적인 취소환불 정책을 표기합니다. * **조회 API**: * [Search Property Detail](/docs/api/channel/check-availabilities-rates)의 `refund_policy` object * [Get Property Detail](/docs/api/channel/get-property-detail)의 `property_refunds` object (동일한 값) * **용도**: 검색 결과에서 대략적인 취소 정책 안내 * **주의**: 실제 취소 시 적용되는 정책과 다를 수 있음 > ⚠️ **주의사항** > > Static Policy만으로 고객에게 취소환불 정책을 확정 안내하면 안 됩니다. 실제 취소 시 수수료와 환불금액이 달라질 수 있습니다. ## Dynamic Policy (동적인 정책)[​](#dynamic-policy-동적인-정책 "Dynamic Policy (동적인 정책)에 대한 직접 링크") 고객이 예약하고자 하는 객실의 **실제 취소환불 정책**입니다. 객실, 날짜, 시간에 따라 달라질 수 있습니다. * **조회 API**: [Cancellation & Refund Policy before reservation](/docs/api/channel/cancellation-refund-policy-before-reservation)의 `refund_policy` object * **용도**: 예약 직전 실제 적용될 정책 확인 * **적용**: 고객이 예약 취소 시 이 정책이 적용됨 > 💡 **핵심 포인트** > > 예약 취소 시에는 **항상 Dynamic Policy**가 적용됩니다. ## 구현 가이드[​](#구현-가이드 "구현 가이드에 대한 직접 링크") 파트너사는 다음 플로우로 취소환불 정책을 처리해야 합니다: ### 1단계: 검색 결과 표시[​](#1단계-검색-결과-표시 "1단계: 검색 결과 표시에 대한 직접 링크") ``` API: Search Property Detail 표시: Static Policy (참고용) ``` * 검색 결과에서 대략적인 취소 정책을 안내합니다 * "취소 정책은 예약 시점에 변경될 수 있습니다" 문구 권장 ### 2단계: 예약 직전 확인[​](#2단계-예약-직전-확인 "2단계: 예약 직전 확인에 대한 직접 링크") ``` API: Cancellation & Refund Policy before reservation 표시: Dynamic Policy (실제 적용) ``` * 결제 전 반드시 호출하여 실제 취소환불 정책을 확인합니다 * 고객에게 이 정책을 명확히 안내합니다 ### 3단계: 예약 취소 처리[​](#3단계-예약-취소-처리 "3단계: 예약 취소 처리에 대한 직접 링크") ``` 적용: Dynamic Policy ``` * 예약 취소 시 Dynamic Policy에 따라 수수료/환불이 처리됩니다 --- # Cancellation & Refund Policy before reservation ``` GET /properties/:property_id/roomtypes/:roomtype_id/rateplans/:rateplan_id/refund_policy ``` ## Request[​](#request "Request에 대한 직접 링크") ## Responsesapplication/json[​](#responses "responses에 대한 직접 링크") * 200 * 400 --- # Channel API ## 1. 소개[​](#1-소개 "1. 소개에 대한 직접 링크") 판매사에서 온다ONDA의 일반 숙박 및 숙박 패키지 상품을 연동판매 하기 위해 제공되는 API 문서 입니다. ONDA 에서 제공하는 해당 Channel Affiliate API 는 **RESTful 기반의 API** 로서, ONDA GDS의 5만여 개 Property 를 연동 판매할 수 있습니다. 평균적으로 제휴사(이하 채널/Channel)는 **평균 2주의 개발 시간을 투자하여 ONDA와의 연동을 마무리**하고 있습니다. ## 2. 기능[​](#2-기능 "2. 기능에 대한 직접 링크") ### **컨텐츠 제공**[​](#컨텐츠-제공 "컨텐츠-제공에 대한 직접 링크") * 숙소 컨텐츠 * 객실 컨텐츠 * 패키지 컨텐츠 ### **실시간 재고/가격 검색**[​](#실시간-재고가격-검색 "실시간-재고가격-검색에 대한 직접 링크") * 실시간 빈방 검색 * 실시간 재고/가격 확인 ### **재고/가격 캐시**[​](#재고가격-캐시 "재고가격-캐시에 대한 직접 링크") * 일자별 재고/가격 저장 * 일자별 최저가 저장 ### **예약**[​](#예약 "예약에 대한 직접 링크") * 실시간 취환불 규정 확인 * 예약 생성 * 예약 조회 * 예약 취소 ## 3. API List[​](#3-api-list "3. API List에 대한 직접 링크") | API Name | Method | Endpoint | Description | | ----------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------- | | Get Property List | `GET` | [Get Property List](/docs/api/channel/get-property-list) | 전체 숙소 목록을 응답합니다. | | Get Property Detail | `GET` | [Get Property Detail](/docs/api/channel/get-property-detail) | 특정 숙소의 상세 정보를 응답합니다. | | Get Roomtype List | `GET` | [Get Roomtype List](/docs/api/channel/get-roomtype-list) | 특정 숙소의 전체 객실타입 목록을 응답합니다. | | Get Roomtype Detail | `GET` | [Get Roomtype Detail](/docs/api/channel/get-roomtype-detail) | 특정 객실의 상세 정보를 응답합니다. | | Get Rateplan List | `GET` | [Get Rateplan List](/docs/api/channel/get-rateplan-list) | 특정 객실의 전체 패키지 목록을 응답합니다. | | Get Rateplan Detail | `GET` | [Get Rateplan Detail](/docs/api/channel/get-rateplan-detail) | 특정 패키지의 상세 정보를 응답합니다. | | Search Property | `GET` | [Search Property](/docs/api/channel/search-property) | 조건에 부합하는 이용가능한 숙소를 응답합니다. | | Search Property Detail | `GET` | [Search Property Detail](/docs/api/channel/check-availabilities-rates) | 특정 숙소의 이용가능한 실제 재고와 요금을 응답합니다.
패키지 상품까지 조회할 수 있습니다. | | Get Inventories | `GET` | [Get Inventories](/docs/api/channel/get-inventories) | 특정 숙소의 기간 내 모든 재고와 요금을 응답합니다. | | Get Lowest Price | `GET` | [Get Lowest Price](/docs/api/channel/check-lowest-price) | 특정 숙소의 일자별 최저가 요금을 응답합니다. | | Cancellation & Refund Policy before reservation | `GET` | [Cancellation & Refund Policy before reservation](/docs/api/channel/cancellation-refund-policy-before-reservation) | 예약 직전 취소환불 정책을 응답합니다. | | Create Reservation | `POST` | [Create Reservation](/docs/api/channel/create-reservation) | 예약을 생성합니다. | | Check Reservation | `GET` | [Check Reservation](/docs/api/channel/check-reservation) | 예약을 조회합니다. | | Cancel Reservation | `PUT` | [Cancel Reservation](/docs/api/channel/cancel-reservation) | 예약을 취소합니다. | --- # Check API Server ``` GET / ``` ## Responsesapplication/json[​](#responses "responses에 대한 직접 링크") * 200 * 400 --- # Search Property Detail ``` GET /search/properties/:property_id ``` 조건에 부합하는 숙소의 예약 가능한 모든 객실타입과 요금제를 **실시간**으로 응답합니다. ## Request[​](#request "Request에 대한 직접 링크") ## Responsesapplication/json[​](#responses "responses에 대한 직접 링크") * 200 * 400 --- # Get Lowest Price ``` GET /properties/:property_id/lowest_price ``` 특정 기간 내의 숙소의 최저가 정보를 제공합니다. ## Request[​](#request "Request에 대한 직접 링크") ## Responsesapplication/json[​](#responses "responses에 대한 직접 링크") * 200 * 400 --- # Check Reservation ``` GET /properties/:property_id/bookings/:booking_number ``` ## Request[​](#request "Request에 대한 직접 링크") ## Responsesapplication/json[​](#responses "responses에 대한 직접 링크") * 200 * 400 --- # Check Avail before reservation ``` GET /properties/:property_id/roomtypes/:roomtype_id/rateplans/:rateplan_id/checkavail ``` ## Request[​](#request "Request에 대한 직접 링크") ## Responsesapplication/json[​](#responses "responses에 대한 직접 링크") * 200 * 400 --- # Create Reservation ``` POST /properties/:property_id/bookings ``` #### ⚠️ `400 channel booking number is exist already` 수신 시 처리 안내[​](#️-400-channel-booking-number-is-exist-already-수신-시-처리-안내 "️-400-channel-booking-number-is-exist-already-수신-시-처리-안내에 대한 직접 링크") 동일 `channel_booking_number`로 예약 생성 요청이 중복 수신되면 반환되는 에러입니다. 즉시 결제 취소 등 실패 처리를 하지 마시고, 아래 절차로 실제 예약 상태를 재확인해 주세요. 1. 수신한 `channel_booking_number`로 **Check Reservation API**를 호출 (`type=channel_booking_number` 쿼리 파라미터 사용) 2. 응답에 예약 정보가 존재하면 **예약 성공**으로 간주하고 내부 상태를 동기화 3. 예약 정보가 없으면 실제 실패이므로 결제 취소 등 통상적인 실패 처리를 진행 ## Request[​](#request "Request에 대한 직접 링크") ## Responsesapplication/json[​](#responses "responses에 대한 직접 링크") * 200 * 400 --- # DB Cache Type DB Cache Type 은 모든 판매 상품의 요금 및 재고를 채널의 DB에 적재한 뒤 서비스 하는 형태를 말합니다.
이 경우, 요금 및 재고를 실시간으로 업데이트하기 위하여 **Webhook 개발은 필수** 입니다. ## DB Cache Type Basic Sequence[​](#db-cache-type-basic-sequence "DB Cache Type Basic Sequence에 대한 직접 링크") --- # Extra Charge > ❗️ > > ONDA API의 추가인원 요금(Extra Adult, Extra Child) 필드는 **사용하지 않습니다**. 클레임 방지를 위해 반드시 이 가이드를 따라주세요. ## 핵심 요약[​](#핵심-요약 "핵심 요약에 대한 직접 링크") * **추가인원 요금 미사용**: API 응답의 Extra Adult/Child 금액을 결제에 포함하지 마세요 * **최대인원 기반 검색**: 유아/아동 포함 총 인원수가 투숙 가능한 객실을 검색하세요 * **현장결제 안내 필수**: 추가인원 요금은 현장결제될 수 있음을 고객에게 반드시 안내하세요 ## 왜 추가인원 요금을 사용하지 않나요?[​](#왜-추가인원-요금을-사용하지-않나요 "왜 추가인원 요금을 사용하지 않나요?에 대한 직접 링크") API 응답에 다음과 같은 추가인원 요금 필드가 존재하지만, 대부분의 공급사(숙소)가 이 값을 충분히 제공하지 않습니다. * [Search Property Detail](/docs/api/channel/check-availabilities-rates)의 `extra_person_fee` * [Get Inventories](/docs/api/channel/get-inventories)의 `extra_adult`, `extra_child`, `extra_infant` 따라서 추가인원 요금은: * 채널에서 선결제하지 **않고** * **현장결제**로 처리됩니다 ## 올바른 객실 검색 방법[​](#올바른-객실-검색-방법 "올바른 객실 검색 방법에 대한 직접 링크") ### 기본 원칙[​](#기본-원칙 "기본 원칙에 대한 직접 링크") 유아, 아동을 포함한 **총 이용 인원수**가 투숙할 수 있는 객실을 모두 검색할 수 있습니다. **최대인원** 기준으로 검색합니다. ### 예시[​](#예시 "예시에 대한 직접 링크") | 실제 이용객 | API 검색 시 인원 | | ------------------------------ | ---------------- | | 성인 2명 | 2명 | | 성인 2명 + 아동 1명 | 3명 | | 성인 2명 + 아동 1명 + 유아 1명 | **4명** | > 💡 **예시 시나리오** > > 고객이 성인 2명, 아동 1명, 유아 1명(총 4명)으로 예약을 원할 경우: > > * API 검색: 4명이 투숙할 수 있는 객실 검색 (최대인원 기준) > * 예약 요청: 해당 객실의 **기준인원**과 **기본 객실 요금**으로 예약 ### 검색 결과 예시[​](#검색-결과-예시 "검색 결과 예시에 대한 직접 링크") 4명으로 검색 시, 다음과 같이 **최대인원이 4명 이상**인 객실이 검색됩니다: | 객실 타입 | 기준인원 | 최대인원 | 검색 결과 | | ------------- | -------- | -------- | --------- | | 스탠다드 더블 | 2명 | 4명 | ✅ 포함 | | 디럭스 트리플 | 3명 | 6명 | ✅ 포함 | | 패밀리 룸 | 4명 | 4명 | ✅ 포함 | | 이코노미 더블 | 2명 | 3명 | ❌ 미포함 | ## 예약 요청 시 주의사항[​](#예약-요청-시-주의사항 "예약 요청 시 주의사항에 대한 직접 링크") 예약 요청 시에는 다음 사항을 준수하세요: 1. **기준인원**: 객실의 기준인원으로 예약 2. **요금**: 기본 객실 요금만 결제 (추가인원 요금 미포함) 3. **Extra Charge 필드**: API 응답의 추가인원 요금 필드는 무시 ## 고객 안내 필수사항[​](#고객-안내-필수사항 "고객 안내 필수사항에 대한 직접 링크") > ⚠️ **필수 안내** > > 파트너사는 고객에게 다음 사항을 **반드시** 안내해야 합니다: > > "기준인원을 초과하는 인원에 대해 **추가 요금이 현장에서 발생**할 수 있습니다." ### 안내가 필요한 이유[​](#안내가-필요한-이유 "안내가 필요한 이유에 대한 직접 링크") * 영유아 추가인원 요금은 별도 데이터로 제공되지 않음 * 해당 정보는 숙소 상세 정보(텍스트)에 포함되어 있음 * 현장결제 안내 미비 시 클레임 발생 가능 --- # Get Inventories ``` GET /inventories ``` 정해진 기간에 대한 특정 숙소의 모든 요금제의 재고와 가격 등 상세 정보를 응답합니다. ## Request[​](#request "Request에 대한 직접 링크") ## Responsesapplication/json[​](#responses "responses에 대한 직접 링크") * 200 * 400 --- # Get Property Detail ``` GET /properties/:property_id ``` ## Request[​](#request "Request에 대한 직접 링크") ## Responsesapplication/json[​](#responses "responses에 대한 직접 링크") * 200 * 400 --- # Get Property List ``` GET /properties ``` 전체 숙소 목록을 응답합니다. ## Request[​](#request "Request에 대한 직접 링크") ## Responsesapplication/json[​](#responses "responses에 대한 직접 링크") * 200 * 400 --- # Get Rateplan Detail ``` GET /properties/:property_id/roomtypes/:roomtype_id/rateplans/:rateplan_id ``` ## Request[​](#request "Request에 대한 직접 링크") ## Responsesapplication/json[​](#responses "responses에 대한 직접 링크") * 200 * 400 --- # Get Rateplan List ``` GET /properties/:property_id/roomtypes/:roomtype_id/rateplans ``` ## Request[​](#request "Request에 대한 직접 링크") ## Responsesapplication/json[​](#responses "responses에 대한 직접 링크") * 200 * 400 --- # Get Rateplan List by Property ID ``` GET /properties/:property_id/rateplans ``` 숙소별 요금제 목록을 응답합니다. ## Request[​](#request "Request에 대한 직접 링크") ## Responsesapplication/json[​](#responses "responses에 대한 직접 링크") * 200 * 400 --- # Get Roomtype Detail ``` GET /properties/:property_id/roomtypes/:roomtype_id ``` ## Request[​](#request "Request에 대한 직접 링크") ## Responsesapplication/json[​](#responses "responses에 대한 직접 링크") * 200 * 400 --- # Get Roomtype List ``` GET /properties/:property_id/roomtypes ``` ## Request[​](#request "Request에 대한 직접 링크") ## Responsesapplication/json[​](#responses "responses에 대한 직접 링크") * 200 * 400 --- # Get Updated Rateplan List ``` GET /rateplans ``` lastdate 값을 기준으로 업데이트된 요금제 목록을 응답합니다. ## Request[​](#request "Request에 대한 직접 링크") ## Responsesapplication/json[​](#responses "responses에 대한 직접 링크") * 200 * 400 --- # Get Updated Roomtype List ``` GET /roomtypes ``` lastdate 값을 기준으로 업데이트된 객실 목록을 응답합니다. ## Request[​](#request "Request에 대한 직접 링크") ## Responsesapplication/json[​](#responses "responses에 대한 직접 링크") * 200 * 400 --- # Image Contents ## 이미지 컨텐츠 저장[​](#이미지-컨텐츠-저장 "이미지 컨텐츠 저장에 대한 직접 링크") * 온다에서 제공하는 이미지는 별도로 반드시 채널 자체 저장하여 사용하셔야 합니다. (eg. S3) * 해당 API 는 기본적으로 채널 자체 DB에 숙소 정보, 객실 정보, 요금/재고, 이미지 등을 저장하여 사용합니다. ## 이미지 리사이즈 (resize)[​](#이미지-리사이즈-resize "이미지 리사이즈 (resize)에 대한 직접 링크") * 기본적으로 제공되는 이미지는 original file 입니다. * 이미지 용량이 너무 커 부담스럽다면 아래 순서대로 처리하면 됩니다. * 이미지 URL 마지막 `-original` 부분을 아래 알맞는 사이즈로 변경하여 호출하면 성공합니다. * 제공 사이즈는 1000, 500, 150, original 입니다. `*1000 size 를 권장합니다.` ## 이미지 샘플[​](#이미지-샘플 "이미지 샘플에 대한 직접 링크") **original size** (default) * **1000 size** * **500 size** * **250 size** * --- # Property Tags 온다에서 제공하는 숙소 관련 태그들의 전체 목록입니다. ## 📌 숙소 특성 태그 (property\_tags)[​](#-숙소-특성-태그-property_tags "📌 숙소 특성 태그 (property_tags)에 대한 직접 링크") 숙소의 컨셉과 특성, 등급을 나타내는 태그입니다. * 가족 * 고급/럭셔리 * 단체/MT/워크샵 * 커플 * 풀빌라 * 한옥 * 애견펜션 * 키즈펜션 * 5성 * 4성 * 3성 * 2성 * 1성 * 특급1급 * 특급 * 1급 * 관광 * 비즈니스 * 레지던스 * 부티크 ## 🏢 숙소 분류 (classifications)[​](#-숙소-분류-classifications "🏢 숙소 분류 (classifications)에 대한 직접 링크") 숙소의 기본 유형을 구분하는 태그입니다. * 호텔 * 펜션 * 게스트하우스 * 모텔 * 카라반 * 글램핑 * 캠핑 * 리조트 * 한옥 * 풀빌라 * 레지던스 ## 🏊 시설 태그 (facility\_tags)[​](#-시설-태그-facility_tags "🏊 시설 태그 (facility_tags)에 대한 직접 링크") 숙소에서 이용할 수 있는 부대시설을 나타내는 태그입니다. * 스파/월풀 * 노래방 * 농구장 * 매점/편의점 * 바베큐장 * 세미나실 * 수영장 * 워터슬라이드 * 족구장 * 찜질방 * 축구장/풋살장 * 카페 * 탁구장 * 피트니스 * 공용스파 * 골프장 * 레스토랑 * 키즈플레이룸 * 공용샤워실 * 공용화장실 * 공용주방 * 워터파크 * 온천 * 사우나 * 연회장 * 비즈니스센터 * 루프탑 * 유아시설 ## 🌊 주변 관광지 태그 (attraction\_tags)[​](#-주변-관광지-태그-attraction_tags "🌊 주변 관광지 태그 (attraction_tags)에 대한 직접 링크") 숙소 주변의 관광지와 액티비티를 나타내는 태그입니다. * 계곡 주변 * 골프장 주변 * 낚시장 주변 * 수목원/휴양림 주변 * 수상레져 * 스키장 주변 * 해수욕장 주변 * 강/호수 주변 ## 🛎️ 서비스 태그 (service\_tags)[​](#️-서비스-태그-service_tags "🛎️ 서비스 태그 (service_tags)에 대한 직접 링크") 숙소에서 제공하는 서비스를 나타내는 태그입니다. * WIFI * 반려동물 동반가능 * 발렛파킹 * 보드게임 * 셔틀버스 * 영화관람 * 자전거대여 * 조식 서비스 * 짐보관 * 취사가능 * 캠프파이어 * 프로포즈/파티/이벤트 * 프린터 사용 * 픽업 * 상비약 * 금연 * 객실내흡연 * 개인사물함 * 무료주차 * 장애인편의시설 * 공항 셔틀 * 바/라운지 * 마사지 * 주차가능 * 기본양념 ## 🛏️ 편의시설 태그 (amenity\_tags)[​](#️-편의시설-태그-amenity_tags "🛏️ 편의시설 태그 (amenity_tags)에 대한 직접 링크") 객실 내 편의시설과 어메니티를 나타내는 태그입니다. * 가스레인지/인덕션 * 개별/테라스 바베큐 * 기본양념 * 냉장고 * 다리미 * 드라이기 * 미니바 * 벽난로 * 쇼파 * 스파/월풀 * 식탁 * 에어컨 * 욕실용품 * 욕조 * 전기밥솥 * 전자레인지 * 취사도구 * 커피포트 * 타월 * TV * 개별 수영장 * 비데 * 흡연가능 * 파티룸 * 화장실 * VOD --- # Real Time Type Real Time Type 은 서비스 클라이언트에서 이벤트가 발생할 때마다 ONDA API 를 호출하여 재고 및 요금 정보를 실시간으로 확인 합니다. 채널에서는 DB에 재고 및 요금을 저장할 필요 없이 서비스 할 수 있습니다. ## Real Time Type Basic Sequence[​](#real-time-type-basic-sequence "Real Time Type Basic Sequence에 대한 직접 링크") ## 컨텐츠 동기화[​](#컨텐츠-동기화 "컨텐츠 동기화에 대한 직접 링크") Channel DB Cache는 최초의 싱크를 맞추는 단계로 Property, Roomtype, Rateplan 정보를 가져와 적재하시면 됩니다. 이후 온다에서 업데이트 되는 컨텐츠는 Webhook을 통해 변경사항을 받으실 수 있습니다. ## 재고 업데이트[​](#재고-업데이트 "재고 업데이트에 대한 직접 링크") Search Property를 이용하여 실시간으로 재고를 업데이트 받으실 수 있습니다. 이 때 숙소(Property ID)는 최대 200개, 보편적으로 50개를 권장합니다. 채널의 응답 속도를 고려하셔서 개발하시면 됩니다. --- # Roomtype Tags 온다에서 제공하는 객실 관련 태그들의 전체 목록입니다. ## 🏠 객실 유형 태그 (roomtype\_tags)[​](#-객실-유형-태그-roomtype_tags "🏠 객실 유형 태그 (roomtype_tags)에 대한 직접 링크") 객실의 구조와 형태를 나타내는 태그입니다. * 도미토리형 * 독채형 * 복층형 * 원룸형 * 분리형 * 싱글룸 * 더블룸 * 트윈룸 * 온돌룸 * 트리플룸 * 패밀리룸 * 스위트룸 * 펜트하우스 * 여성전용 * 남성전용 * 남녀공용 ## 🌅 전망 태그 (view\_tags)[​](#-전망-태그-view_tags "🌅 전망 태그 (view_tags)에 대한 직접 링크") 객실에서 바라볼 수 있는 전망을 나타내는 태그입니다. * 바다 전망 * 산 전망 * 도시 전망 * 정원 전망 * 수영장 전망 * 강 전망 * 항구 전망 --- # Search Property ``` GET /search/properties ``` 조건에 부합하는 이용 가능한 숙소의 가장 저렴한 요금을 **실시간**으로 응답합니다. ## Request[​](#request "Request에 대한 직접 링크") ## Responsesapplication/json[​](#responses "responses에 대한 직접 링크") * 200 * 400 --- # Reservation Comparison ``` GET /bookings ``` ## Request[​](#request "Request에 대한 직접 링크") ## Responsesapplication/json[​](#responses "responses에 대한 직접 링크") * 200 * 400 --- # Test Property ## Basic[​](#basic "Basic에 대한 직접 링크") * **실제 숙소로는 테스트 할 수 없습니다.** * 담당 매니저와의 사전 협의에 따라 실제 숙소의 **컨텐츠 정보까지는** 호출하여 보실 수 있습니다. * 기본적으로 아래 property\_id 를 제외하고 나머지 property\_id 로는 **예약 테스트를 절대 진행해서는 안됩니다.** * 테스트 숙소 상품을 이용한 예약 후에는 반드시 취소 처리까지 해주셔야 합니다. ## Test Property Account[​](#test-property-account "Test Property Account에 대한 직접 링크") | property\_id | classifications | rateplan 포함여부 | | ------------ | --------------- | ----------------- | | 117417 | 호텔 HOTEL | 포함 | | 120135 | 호텔 HOTEL | 포함 | --- # Get Updated Inventories ``` GET /update_inventories ``` 업데이트된 재고와 가격 등 상세 정보를 응답합니다. ## Request[​](#request "Request에 대한 직접 링크") ## Responsesapplication/json[​](#responses "responses에 대한 직접 링크") * 200 * 400 --- # Webhook Overview ## Webhook?[​](#webhook "Webhook?에 대한 직접 링크") ONDA GDS에서 변경된 숙소, 객실, 패키지의 각 컨텐츠와 요금 및 재고 정보를 실시간으로 채널에 업데이트할 수 있도록 하기 위해 사용하는 API 입니다. 기본적으로 ONDA 에서 전송하는 Webhook API 의 Method 는 `PUT` 입니다. ## Webhook 종류[​](#webhook-종류 "Webhook 종류에 대한 직접 링크") | Webhook | Description | | ------------------- | ------------------------------------------------------------------------------------------------- | | `contents_updated` | 숙소, 객실, 패키지 플랜의 **컨텐츠 정보가 변경되었다는 사실**을 알리는 웹훅 입니다. | | `status_updated` | 숙소, 객실, 패키지 플랜이 **새롭게 추가**되었거나 **변경된 판매상태의 정보**를 알리는 웹훅입니다. | | `inventory_updated` | 특정 패키지 플랜의 특정 일자 **요금 및 재고 정보를 알리는** 웹훅입니다. | ## Webhook 설정 순서[​](#webhook-설정-순서 "Webhook 설정 순서에 대한 직접 링크") 1. 채널에서 어떤 종류의 Webhook API 스펙을 개발 할 지 선택합니다. 2. ONDA 에서 제공한 Webhook API 스펙을 참고하여 채널에서 개발합니다. 3. API domain 과 Auth Key 등 Webhook API 환경 정보를 ONDA 에 공유합니다. 4. 공유 된 환경 정보를 ONDA 에서 설정한 뒤 배포 합니다. 5. 각 항목별로 업데이트 된 내역을 실행하여 상호 간 테스트 합니다. --- # Webhook Specifications ## Object[​](#object "Object에 대한 직접 링크") ### event\_type[​](#event_type "event_type에 대한 직접 링크") 각 웹훅의 이벤트를 선언합니다.
각 이벤트에 따라 호출하는 Body 값이 다릅니다. #### 예제:[​](#예제 "예제:에 대한 직접 링크") ``` "event_type": "contents_updated" ``` #### 사용 가능한 `event_type` 값:[​](#사용-가능한-event_type-값 "사용-가능한-event_type-값에 대한 직접 링크") * `contents_updated` * `status_updated` * `inventory_updated` ### event\_detail[​](#event_detail "event_detail에 대한 직접 링크") `event_type` 에 대한 상내 내용을 담습니다. `event_type` 과 `event_detail` 에 따라 포함되는 attribute 는 다를 수 있습니다. 아래 `event_type / event_detail` 별 Sample 을 참고해주세요. inventory\_updated 의 경우에는 `event_details` 복수 Array로 응답합니다. ## Sample[​](#sample "Sample에 대한 직접 링크") ### contents\_updated[​](#contents_updated "contents_updated에 대한 직접 링크") `event_type` 에 `contents_update` 가 확인된다면, 지정된 `target` 의 컨텐츠가 업데이트 되었다는 의미입니다. 각 target 의 id 를 이용하여 컨텐츠 업데이트 할 수 있도록 각각의 컨텐츠 API 를 호출해 주세요. 만약 업데이트 할 property, roomtype, rateplan 이 없다면 새로 추가해주세요. `UPSERT` #### target = property Sample[​](#target--property-sample "target = property Sample에 대한 직접 링크") ``` { "event_type": "contents_updated", "event_detail": { "target": "property", "property_id": 32124 }, "timestamp": "2021-01-27T10:39:12+09:00" } ``` #### target = roomtype Sample[​](#target--roomtype-sample "target = roomtype Sample에 대한 직접 링크") ``` { "event_type": "contents_updated", "event_detail": { "target": "roomtype", "property_id": 32124, "roomtype_id": 111111 }, "timestamp": "2021-01-27T10:39:12+09:00" } ``` #### target = rateplan Sample[​](#target--rateplan-sample "target = rateplan Sample에 대한 직접 링크") ``` { "event_type": "contents_updated", "event_detail": { "target": "rateplan", "property_id": 32124, "roomtype_id": 111111, "rateplan_id": 1234567 }, "timestamp": "2021-01-27T10:39:12+09:00" } ``` ### status\_updated[​](#status_updated "status_updated에 대한 직접 링크") `event_type` 에 `status_update` 가 확인된다면, 지정된 `target` 의 상태가 변경 되었다는 의미입니다. 각 target 의 id 에 대한 상태 업데이트를 처리해주세요. #### 지원하는 상태(status):[​](#지원하는-상태status "지원하는 상태(status):에 대한 직접 링크") | status | description | | -------- | ------------------------------------------------------------------------------------------------------------- | | enabled | 판매상태가 활성 상태로 변경됨을 뜻합니다.
활성화 상태로 업데이트 해주세요. | | disabled | 판매상태가 비활성 상태로 변경됨을 뜻합니다.
비활성화 상태로 업데이트 해주세요. | | deleted | 더 이상 판매될 수 없도록 영구적으로 삭제됨을 뜻합니다.
삭제 상태 또는 비활성화 상태로 업데이트 해주세요. | #### target = property Sample / disabled case[​](#target--property-sample--disabled-case "target = property Sample / disabled case에 대한 직접 링크") ``` { "event_type": "status_updated", "event_detail": { "target": "property", "property_id": 32124, "status": "disabled" }, "timestamp": "2021-01-27T10:39:12+09:00" } ``` #### target = roomtype Sample / enabled case[​](#target--roomtype-sample--enabled-case "target = roomtype Sample / enabled case에 대한 직접 링크") ``` { "event_type": "status_updated", "event_detail": { "target": "roomtype", "property_id": 32124, "roomtype_id": 111111, "status": "enabled" }, "timestamp": "2021-01-27T10:39:12+09:00" } ``` #### target = rateplan Sample / deleted case[​](#target--rateplan-sample--deleted-case "target = rateplan Sample / deleted case에 대한 직접 링크") ``` { "event_type": "status_updated", "event_detail": { "target": "rateplan", "property_id": 32124, "roomtype_id": 111111, "rateplan_id": 1234567, "status": "deleted" }, "timestamp": "2021-01-27T10:39:12+09:00" } ``` ### inventory\_updated[​](#inventory_updated "inventory_updated에 대한 직접 링크") 새롭게 추가되거나 변경되는 요금 및 재고 정보를 포함합니다. `rateplan_id` 의 요금 및 재고를 정보 그대로 추가 하거나 업데이트 해주세요. `UPSERT` 여러 일자에 대한 업데이트 인 경우, 1개 웹훅에 `event_detail` 이 Array 로 응답됩니다. #### 지원하는 정보 Field[​](#지원하는-정보-field "지원하는 정보 Field에 대한 직접 링크") | Field | Description | | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | `date` | 요금재고가 적용되는 Checkin 일자입니다. | | `basic_price` | 기본 요금 입니다. | | `sale_price` | 실제 판매 요금입니다. basic\_price 보다 sale\_price 가 클 수 없습니다.
basic\_price 와의 차이를 통해 할인율을 계산 할 수 있습니다. | | `extra_adult` | 성인 추가 비용입니다. | | `extra_child` | 아동 추가 비용입니다. | | `extra_infant` | 유아 추가 비용입니다. | | `promotion_type` | basic\_price 에 적용된 지정된 프로모션이 있을 경우 반환합니다. 없는 경우 Null 을 반환 합니다. | | `vacancy` | 예약 가능한 재고 수 입니다.
0인 경우, 재고 없음으로 인해 예약이 불가능한 상태입니다. | #### available case / vacancy >= 1[​](#available-case--vacancy--1 "available case / vacancy >= 1에 대한 직접 링크") ``` { "event_type": "inventory_updated", "event_details": [ { "property_id": 32124, "roomtype_id": 111111, "rateplan_id": 1234567, "date": "2022-10-10", "basic_price": 100000, "sale_price": 80000, "extra_adult": 10000, "extra_child": 0, "extra_infant": 0, "promotion_type": null, "vacancy": 1 } ], "timestamp": "2021-01-27T10:39:12+09:00" } ``` #### unavailable case / vacancy = 0[​](#unavailable-case--vacancy--0 "unavailable case / vacancy = 0에 대한 직접 링크") ``` { "event_type": "inventory_updated", "event_details": [ { "property_id": 32124, "roomtype_id": 111111, "rateplan_id": 1234567, "date": "2022-10-10", "basic_price": 100000, "sale_price": 80000, "extra_adult": 10000, "extra_child": 0, "extra_infant": 0, "promotion_type": null, "vacancy": 0 } ], "timestamp": "2021-01-27T10:39:12+09:00" } ``` #### update array case[​](#update-array-case "update array case에 대한 직접 링크") ``` { "event_type": "inventory_updated", "event_details": [ { "property_id": 32124, "roomtype_id": 111111, "rateplan_id": 1234567, "date": "2022-10-10", "basic_price": 100000, "sale_price": 80000, "extra_adult": 10000, "extra_child": 0, "extra_infant": 0, "promotion_type": null, "vacancy": 1 }, { "property_id": 32124, "roomtype_id": 111111, "rateplan_id": 1234567, "date": "2022-10-11", "basic_price": 100000, "sale_price": 80000, "extra_adult": 10000, "extra_child": 0, "extra_infant": 0, "promotion_type": null, "vacancy": 1 }, { "property_id": 32124, "roomtype_id": 111111, "rateplan_id": 1234567, "date": "2022-10-12", "basic_price": 100000, "sale_price": 70000, "extra_adult": 10000, "extra_child": 0, "extra_infant": 0, "promotion_type": null, "vacancy": 0 }, { "property_id": 32124, "roomtype_id": 337222, "rateplan_id": 7654321, "date": "2022-10-10", "basic_price": 100000, "sale_price": 80000, "extra_adult": 10000, "extra_child": 0, "extra_infant": 0, "promotion_type": null, "vacancy": 0 } ], "timestamp": "2021-01-27T10:39:12+09:00" } ``` --- # 숙소 생성 ``` POST /gds/vendor/properties ``` * 공급사 숙소를 ONDA에 생성합니다. 객실타입·요금제 모델·요금제가 모두 이 숙소 하위에 생성되므로 콘텐츠 연동의 첫 단계입니다. * `id`(공급사 숙소 ID)가 필수이며, 숙소명은 `i18n`의 `ko-kr`에 담습니다. * `classifications`·`property_tags`·`facility_tags` 등 코드성 필드에는 코드 카탈로그 조회로 받은 코드만 사용할 수 있습니다. * `settings.extra_adult_price`는 숙소 기본 추가 성인요금(정수 KRW)으로, 인원 기반 요금을 쓰는 채널에 반영됩니다. * 이미 존재하는 `id`로 다시 호출하면 `409`가 반환됩니다. 기존 숙소를 바꾸려면 숙소 수정을 사용하세요. ## Request[​](#request "Request에 대한 직접 링크") ## Responsesapplication/json[​](#responses "responses에 대한 직접 링크") * 200 * 400 * 401 * 403 * 404 * 409 생성 결과 Bad Request (식별자 path/body 불일치 등) Unauthorized Forbidden Not Found Conflict (이미 존재하는 id) --- # 숙소별 채널 신청 ``` POST /gds/vendor/properties/:vendor_property_id/channels/:channel_id ``` * 해당 채널에 판매 시작(ON) 또는 종료(OFF) 신청을 생성합니다. * ON 신청 시 공통 사전 검증을 수행하며, 조건 미충족 시 즉시 reject 처리됩니다. * 단 CMS 연동 채널은 숙소 이미지, 숙소 카테고리, 객실 이미지 조건을 검사하지 않습니다. * OFF 요청은 모든 채널에서 즉시 자동 승인 처리됩니다. ## Request[​](#request "Request에 대한 직접 링크") ## Responsesapplication/json[​](#responses "responses에 대한 직접 링크") * 200 * 400 * 401 * 403 * 404 * 409 * 500 신청 처리 결과 Bad Request Unauthorized Forbidden Not Found Conflict Internal Server Error --- # 요금제 생성 ``` POST /gds/vendor/properties/:vendor_property_id/roomtypes/:vendor_roomtype_id/rateplans ``` * 객실타입 하위에 요금제를 생성합니다. 요금·영업일 전송의 기준 단위이므로, 판매를 시작하려면 반드시 필요합니다. * `id`와 `vendor_rateplan_model_id`가 필수입니다. `vendor_rateplan_model_id`로 요금제 모델과 결합되어 판매 조건이 정해집니다. * 결합할 요금제 모델과 객실타입이 모두 먼저 생성돼 있어야 합니다. * 이미 존재하는 `id`는 `409`, 참조하는 요금제 모델이 없거나 불변식을 위반하면 `422`가 반환됩니다. ## Request[​](#request "Request에 대한 직접 링크") ## Responsesapplication/json[​](#responses "responses에 대한 직접 링크") * 200 * 400 * 401 * 403 * 404 * 409 * 422 생성 결과 Bad Request (식별자 path/body 불일치 등) Unauthorized Forbidden Not Found Conflict (이미 존재하는 id) Unprocessable Entity (참조/invariant 위반) --- # 요금제 모델 생성 ``` POST /gds/vendor/properties/:vendor_property_id/rateplan-models ``` * 숙소 단위로 요금제 모델을 생성합니다. 요금제는 객실타입과 이 모델의 결합으로 정의되므로, 요금제를 만들기 전에 먼저 생성해야 합니다. * `id`와 `i18n`(`ko-kr` 필수)이 필요합니다. * `type`이 `standalone`인 모델은 숙소당 1개만 만들 수 있고 반드시 있어야 합니다. `package`는 개수 제한이 없습니다. * `sale_from`과 `sale_to`는 두 값을 모두 보내거나 모두 생략해야 하며, 한쪽만 보내면 거부됩니다. `max_los`를 `0`으로 두면 최대 숙박일 제한이 없습니다. * `channels`를 보내면 해당 채널에서만 판매되고, 생략하면 전 채널에서 판매됩니다. * 이미 존재하는 `id`는 `409`, 참조나 불변식을 위반하면 `422`가 반환됩니다. ## Request[​](#request "Request에 대한 직접 링크") ## Responsesapplication/json[​](#responses "responses에 대한 직접 링크") * 200 * 400 * 401 * 403 * 404 * 409 * 422 생성 결과 Bad Request (식별자 path/body 불일치 등) Unauthorized Forbidden Not Found Conflict (이미 존재하는 id) Unprocessable Entity (참조/invariant 위반) --- # 객실타입 생성 ``` POST /gds/vendor/properties/:vendor_property_id/roomtypes ``` * 숙소 하위에 객실타입을 생성합니다. 숙소를 먼저 생성해야 호출할 수 있습니다. * `id`(공급사 객실타입 ID)가 필수이며, 객실명은 `i18n`의 `ko-kr`에 담습니다. * `roomtype_tags`·`amenity_tags`·`view_tags` 등 코드성 필드에는 코드 카탈로그 조회로 받은 코드만 사용할 수 있습니다. * 재고는 객실타입 단위로 관리되므로, 여기서 만든 `id`가 이후 재고 전송의 기준이 됩니다. * 이미 존재하는 `id`로 다시 호출하면 `409`가 반환됩니다. ## Request[​](#request "Request에 대한 직접 링크") ## Responsesapplication/json[​](#responses "responses에 대한 직접 링크") * 200 * 400 * 401 * 403 * 404 * 409 생성 결과 Bad Request (식별자 path/body 불일치 등) Unauthorized Forbidden Not Found Conflict (이미 존재하는 id) --- # 예약 조회 ``` GET /gds/vendor/booking/:vendor_booking_number ``` * 예약 번호로 예약 한 건의 상세를 조회합니다. * 공급사 예약은 `gds_sub_booking_number` 기준으로 생성됩니다. 하나의 `gds_booking_number`에 여러 건이 대응할 수 있습니다. * 투숙 정보·금액·상태와 채널 정보를 함께 확인할 수 있습니다. ## Request[​](#request "Request에 대한 직접 링크") ## Responsesapplication/json[​](#responses "responses에 대한 직접 링크") * 200 * 400 * 401 * 403 * 404 예약 정보 Bad Request Unauthorized Forbidden Not Found --- # 채널 인증 URL 조회 ``` GET /gds/vendor/channels/:channel_id/authorization ``` * **에어비앤비 전용입니다.** 채널 메타의 `requires_cms_authorization`이 `true`인 채널에서만 사용하며, 현재 해당하는 채널은 에어비앤비뿐입니다. 다른 채널에 호출하면 `403`이 반환됩니다. * 에어비앤비는 숙소마다 호스트 계정의 OAuth 승인이 필요합니다. 이 API로 인증 URL을 발급받아 호스트를 이동시키고, 승인이 끝나야 객실·요금제 매핑을 진행할 수 있습니다. * 호스트가 인증을 마치면 `redirect_url`로 `?auth_result=success|fail`이 붙어 복귀합니다. * `auth_result`는 화면 힌트이며, 연동 완료 판정은 숙소 매핑 조회의 `channel_property_id` 존재 여부를 기준으로 합니다. * 발급된 인증 URL은 1시간 내에 사용해야 하며, 만료되면 새로 발급해야 합니다. 호스트가 버튼을 누르는 시점에 발급하세요. * 인증은 숙소 단위로 진행되므로, 같은 호스트 계정이 여러 숙소를 운영해도 숙소마다 반복해야 합니다. ## Request[​](#request "Request에 대한 직접 링크") ## Responsesapplication/json[​](#responses "responses에 대한 직접 링크") * 200 * 400 * 401 * 403 * 404 * 500 채널 인증 URL 조회 성공 Bad Request Unauthorized Forbidden Not Found Internal Server Error --- # 채널 숙소 정보 조회 ``` GET /gds/vendor/channels/:channel_id/properties/:channel_property_id ``` * 채널 측에 등록된 숙소와 그 하위 객실·요금제 정보를 조회합니다. * 직연동 채널에서 매핑을 만들기 전에 호출해, 연결할 채널 객실 ID와 요금제 ID 후보를 확보하는 용도입니다. * 응답의 `channel_parent_rateplan_id`는 부모 요금제를 가리킵니다. 이 요금제에 요금을 따로 보내도 채널에 반영되지 않고, 부모 요금제의 요금을 따라 자동으로 변동합니다. * 채널 측 조회를 거치므로 채널 상황에 따라 `500`이 날 수 있습니다. 재시도 처리를 두는 편이 안전합니다. ## Request[​](#request "Request에 대한 직접 링크") ## Responsesapplication/json[​](#responses "responses에 대한 직접 링크") * 200 * 400 * 401 * 403 * 404 * 500 채널 숙소 정보 조회 성공 Bad Request Unauthorized Forbidden Not Found Internal Server Error --- # 코드 카탈로그 조회 ``` GET /gds/vendor/meta ``` * 콘텐츠 push에 사용할 pcs.codes.code 값을 code\_type별 계층 트리로 조회합니다. * 하위 코드가 없는 leaf 노드는 children 필드를 생략합니다. ## Request[​](#request "Request에 대한 직접 링크") ## Responsesapplication/json[​](#responses "responses에 대한 직접 링크") * 200 * 400 * 401 * 403 코드 카탈로그 Bad Request Unauthorized Forbidden --- # 숙소 단건 조회 ``` GET /gds/vendor/properties/:vendor_property_id ``` * 숙소 한 건의 콘텐츠와 판매 상태를 조회합니다. * 3.0에서 콘텐츠는 공급사가 ONDA로 전송하는 것이 기본이므로, 조회는 전송 결과를 확인하는 보조 수단입니다. * 경로의 `vendor_property_id`는 공급사가 숙소 생성 시 보낸 `id`입니다. ## Request[​](#request "Request에 대한 직접 링크") ## Responsesapplication/json[​](#responses "responses에 대한 직접 링크") * 200 * 400 * 401 * 403 * 404 * 409 숙소 콘텐츠 Bad Request (식별자 path/body 불일치 등) Unauthorized Forbidden Not Found Conflict (이미 존재하는 id) --- # 숙소별 채널 상세 ``` GET /gds/vendor/properties/:vendor_property_id/channels/:channel_id ``` 현재 공급사 화이트리스트나 채널 상태와 무관하게 해당 채널의 최신 신청 상태와 신청 이력을 최신순 최대 100건 조회합니다. ## Request[​](#request "Request에 대한 직접 링크") ## Responsesapplication/json[​](#responses "responses에 대한 직접 링크") * 200 * 400 * 401 * 403 * 404 * 500 채널 신청 상태 Bad Request Unauthorized Forbidden Not Found Internal Server Error --- # 숙소 채널 설정 조회 ``` GET /gds/vendor/properties/:vendor_property_id/channels/:channel_id/settings ``` * 숙소에 대한 채널별 부가 설정을 조회합니다. * 저장된 값이 없으면 빈 객체가 반환됩니다. 설정하지 않은 상태와 오류를 구분해 처리하세요. * 설정 항목은 채널마다 다릅니다. 인원 추가요금 방식처럼 일부 채널에서만 쓰이는 항목이 있습니다. ## Request[​](#request "Request에 대한 직접 링크") ## Responsesapplication/json[​](#responses "responses에 대한 직접 링크") * 200 * 400 * 401 * 403 * 404 * 500 채널 설정 조회 성공. 저장된 값이 없으면 빈 객체 반환. Bad Request Unauthorized Forbidden Not Found Internal Server Error --- # 숙소 매핑 조회 ``` GET /gds/vendor/properties/:vendor_property_id/channels/:channel_id/mappings ``` * 숙소와 채널 사이의 매핑 상태를 조회합니다. * 응답의 `channel_property_id`에 값이 있으면 채널 측 숙소와 연결된 상태입니다. 채널 오픈이 끝났는지 판단하는 기준으로 사용합니다. * 매핑은 직연동 채널에서만 사용합니다. 플러스 채널은 ONDA가 매핑을 관리하므로 대상이 아닙니다. ## Request[​](#request "Request에 대한 직접 링크") ## Responsesapplication/json[​](#responses "responses에 대한 직접 링크") * 200 * 400 * 401 * 403 * 404 * 500 숙소 매핑 조회 성공 Bad Request Unauthorized Forbidden Not Found Internal Server Error --- # 요금제 단건 조회 ``` GET /gds/vendor/properties/:vendor_property_id/roomtypes/:vendor_roomtype_id/rateplans/:vendor_rateplan_id ``` * 요금제 한 건의 정보와 판매 상태를 조회합니다. * 3.0에서 콘텐츠는 공급사가 ONDA로 전송하는 것이 기본이므로, 조회는 전송 결과를 확인하는 보조 수단입니다. * 어떤 요금제 모델과 결합돼 있는지 확인할 수 있습니다. ## Request[​](#request "Request에 대한 직접 링크") ## Responsesapplication/json[​](#responses "responses에 대한 직접 링크") * 200 * 400 * 401 * 403 * 404 * 409 요금제 콘텐츠 Bad Request (식별자 path/body 불일치 등) Unauthorized Forbidden Not Found Conflict (이미 존재하는 id) --- # 요금제 매핑 조회 ``` GET /gds/vendor/properties/:vendor_property_id/roomtypes/:vendor_roomtype_id/rateplans/:vendor_rateplan_id/channels/:channel_id/mappings ``` * 요금제와 채널 요금제 사이의 매핑 상태를 조회합니다. * 숙소·객실 매핑이 끝난 뒤에 의미가 있습니다. 매핑은 숙소에서 객실, 요금제 순으로 이어집니다. * 매핑은 직연동 채널에서만 사용합니다. ## Request[​](#request "Request에 대한 직접 링크") ## Responsesapplication/json[​](#responses "responses에 대한 직접 링크") * 200 * 400 * 401 * 403 * 404 * 500 요금제 매핑 조회 성공 Bad Request Unauthorized Forbidden Not Found Internal Server Error --- # 요금제 모델 단건 조회 ``` GET /gds/vendor/properties/:vendor_property_id/rateplan-models/:vendor_rateplan_model_id ``` * 요금제 모델 한 건의 판매 조건을 조회합니다. * 3.0에서 콘텐츠는 공급사가 ONDA로 전송하는 것이 기본이므로, 조회는 전송 결과를 확인하는 보조 수단입니다. * 판매 기간·숙박일수·환불 여부·판매 채널 등 이 모델을 참조하는 요금제에 공통 적용되는 조건을 확인할 수 있습니다. ## Request[​](#request "Request에 대한 직접 링크") ## Responsesapplication/json[​](#responses "responses에 대한 직접 링크") * 200 * 400 * 401 * 403 * 404 * 409 요금제 모델 콘텐츠 Bad Request (식별자 path/body 불일치 등) Unauthorized Forbidden Not Found Conflict (이미 존재하는 id) --- # 객실타입 단건 조회 ``` GET /gds/vendor/properties/:vendor_property_id/roomtypes/:vendor_roomtype_id ``` * 객실타입 한 건의 콘텐츠와 판매 상태를 조회합니다. * 3.0에서 콘텐츠는 공급사가 ONDA로 전송하는 것이 기본이므로, 조회는 전송 결과를 확인하는 보조 수단입니다. * 경로의 `vendor_roomtype_id`는 공급사가 객실타입 생성 시 보낸 `id`입니다. ## Request[​](#request "Request에 대한 직접 링크") ## Responsesapplication/json[​](#responses "responses에 대한 직접 링크") * 200 * 400 * 401 * 403 * 404 * 409 객실타입 콘텐츠 Bad Request (식별자 path/body 불일치 등) Unauthorized Forbidden Not Found Conflict (이미 존재하는 id) --- # 객실 채널 설정 조회 ``` GET /gds/vendor/properties/:vendor_property_id/roomtypes/:vendor_roomtype_id/channels/:channel_id/settings ``` * 공급사의 객실에 대한 채널별 설정을 조회합니다. * 저장된 값이 없으면 빈 객체 반환. ## Request[​](#request "Request에 대한 직접 링크") ## Responsesapplication/json[​](#responses "responses에 대한 직접 링크") * 200 * 400 * 401 * 403 * 404 * 500 객실 채널 설정 조회 성공 Bad Request Unauthorized Forbidden Not Found Internal Server Error --- # 객실 매핑 조회 ``` GET /gds/vendor/properties/:vendor_property_id/roomtypes/:vendor_roomtype_id/channels/:channel_id/mappings ``` * 객실타입과 채널 객실 사이의 매핑 상태를 조회합니다. * 숙소 매핑이 끝난 뒤에 의미가 있습니다. 숙소가 연결되지 않은 상태에서는 객실 매핑을 만들 수 없습니다. * 매핑은 직연동 채널에서만 사용합니다. ## Request[​](#request "Request에 대한 직접 링크") ## Responsesapplication/json[​](#responses "responses에 대한 직접 링크") * 200 * 400 * 401 * 403 * 404 * 500 객실 매핑 조회 성공 Bad Request Unauthorized Forbidden Not Found Internal Server Error --- # 정산 비교 조회 ``` GET /gds/vendor/bookings ``` * 정산 금액 데이터를 조회합니다. 공급사 내부 정산과 대조할 때 사용합니다. * `option`으로 기준일을 고릅니다. `checkin`은 체크인일, `checkout`은 체크아웃일 기준이며 `from`·`to`와 함께 필수입니다. * `offset`과 `limit`으로 페이지를 나눠 가져옵니다. `vendor_property_id`를 주면 특정 숙소로 좁힐 수 있습니다. * 수수료를 뺀 정산 예정 금액은 `net_price`입니다. ## Request[​](#request "Request에 대한 직접 링크") ## Responsesapplication/json[​](#responses "responses에 대한 직접 링크") * 200 * 400 * 401 * 403 * 404 정산 비교 데이터 Bad Request Unauthorized Forbidden Not Found --- # 에어비앤비 인증 구현 에어비앤비는 숙소마다 **호스트의 에어비앤비 계정 승인(OAuth)** 이 필요한 채널입니다. 호스트가 직접 로그인해 접근 권한을 승인해야 ONDA가 그 계정 권한으로 리스팅 조회·요금재고 전송·예약 수신을 할 수 있습니다. 공급사 시스템이 대신 처리할 수 없고, 반드시 **호스트 본인의 브라우저**에서 진행됩니다. 이미 승인한 적 있는 계정이면 승인 화면이 생략되고 바로 완료되기도 합니다. 전제 * 채널 메타의 `requires_cms_authorization`이 `true`인 채널이 대상입니다 → [직연동 레거시 채널 오픈](/docs/api/vendor-v3/guides/channel-open-legacy#%EB%A7%A4%ED%95%91-%EC%82%AC%EC%A0%84-%EB%8B%A8%EA%B3%84-%EB%B6%84%EA%B8%B0) * 에어비앤비의 `channel_id`는 [`GET /gds/vendor/channels`](/docs/api/vendor-v3/list-channels)로 확인하세요. 아래 예시는 `133`을 사용합니다. ## 언제 필요한가[​](#언제-필요한가 "언제 필요한가에 대한 직접 링크") | 시점 | 인증 필요 여부 | | ----------------------------------------- | ----------------------------------- | | 숙소를 에어비앤비에 처음 연동할 때 | **필요** — 최초 1회 | | 호스트가 다른 에어비앤비 계정으로 바꿀 때 | **필요** — 재인증 | | 토큰 만료 | **불필요** — ONDA가 자동 갱신합니다 | 전체 온보딩에서의 위치는 아래와 같습니다. **인증이 끝나기 전에는 객실·요금제 매핑을 진행할 수 없습니다.** ``` 숙소 등록(연동) 완료 → 호스트 인증(이 가이드) → 객실·요금제 매핑 → 판매 개시 ``` ## 공급사가 구현할 것[​](#공급사가-구현할-것 "공급사가 구현할 것에 대한 직접 링크") 1. **연동 시작 진입점** — 관리 화면에 "에어비앤비 계정 연동" 버튼을 두고, 클릭 시 인증 URL 발급 API를 호출해 받은 `url`로 호스트를 이동시킵니다 (새 창 권장) 2. **복귀 전용 경로** — 인증 결과가 돌아올 전용 콜백 경로(예: `/airbnb/callback`). ONDA가 이 경로에 `auth_result`를 붙여 복귀시키므로, 경로에서 결과를 읽어 화면을 분기합니다 3. **완료 판정** — `auth_result`는 화면 힌트일 뿐이므로, 최종 연동 여부는 매핑 조회 API로 확인합니다 ## 전체 흐름[​](#전체-흐름 "전체 흐름에 대한 직접 링크") ## 1단계 · 인증 URL 발급[​](#1단계--인증-url-발급 "1단계 · 인증 URL 발급에 대한 직접 링크") 공급사 서버에서 [`GET /gds/vendor/channels/{channel_id}/authorization`](/docs/api/vendor-v3/get-channel-authorization-url)을 호출합니다. ``` curl -H "Authorization: {vendor_access_token}" \ "https://vendor.dapi.tport.dev/gds/vendor/channels/133/authorization?vendor_property_id=VP-001&redirect_url=https%3A%2F%2Fvendor.example.com%2Fairbnb%2Fcallback" ``` | 쿼리 파라미터 | 필수 | 설명 | | -------------------- | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `vendor_property_id` | 필수 | 공급사 시스템의 숙소 ID | | `redirect_url` | 필수 | 인증 완료 후 복귀할 전용 경로. `http(s)`만 허용하며 파이프 문자(`\|`)는 넣을 수 없습니다. ONDA가 복귀 시 `auth_result`를 덧붙이며, 공급사가 미리 붙여 둔 쿼리 파라미터는 그대로 보존됩니다 | **성공 응답 (200)** ``` { "url": "https://www.airbnb.com/oauth2/auth?client_id=...&redirect_uri=...&scope=...&state=..." } ``` 발급된 `url`은 **1시간 동안 유효**합니다. 만료된 URL로 진행하면 복귀 없이 실패하므로 재발급 후 다시 시도해야 합니다. **오류 응답** | 상태 | 원인 | 공급사 조치 | | -------------------------- | -------------------------------------------------------------------- | ----------------------------- | | `400` | `redirect_url` 형식 오류 — `http(s)` URL이 아니거나 파이프 문자 포함 | 요청 값 수정 | | `401` | 인증 토큰 오류 | 토큰 확인 | | `403` `UnsupportedChannel` | 해당 채널이 OAuth 인증 대상이 아님 | 이 인증이 불필요한 채널입니다 | | `404` `Property not found` | 숙소가 아직 미연동이거나 소유가 아님 | 숙소 등록 절차를 먼저 완료 | ## 2단계 · 호스트 인증 진행[​](#2단계--호스트-인증-진행 "2단계 · 호스트 인증 진행에 대한 직접 링크") 발급받은 `url`을 그대로 새 창으로 엽니다. 호스트는 **연동하려는 에어비앤비 계정**으로 로그인해 권한을 승인합니다. ## 3단계 · 복귀 처리[​](#3단계--복귀-처리 "3단계 · 복귀 처리에 대한 직접 링크") ONDA는 인증 처리 후 호스트 브라우저를 `redirect_url`로 302 복귀시키며, 결과를 `auth_result` 파라미터로 붙입니다. | 복귀 형태 | 의미 | 처리 | | ---------------------------------- | ------ | ---------------------------------------------------- | | `redirect_url?auth_result=success` | 성공 | 곧바로 매핑 조회로 실제 연동 여부를 확정 | | `redirect_url?auth_result=fail` | 실패 | "인증 실패, 다시 시도"를 안내 | | 복귀 자체가 없음 | 미확정 | 호스트가 이탈했거나 콜백이 ONDA에 도달하지 못한 경우 | ## 4단계 · 완료 확인[​](#4단계--완료-확인 "4단계 · 완료 확인에 대한 직접 링크") [`GET /gds/vendor/properties/{vendor_property_id}/channels/{channel_id}/mappings`](/docs/api/vendor-v3/get-property-mapping)로 확인합니다. ``` curl -H "Authorization: {vendor_access_token}" \ "https://vendor.dapi.tport.dev/gds/vendor/properties/VP-001/channels/133/mappings" ``` ``` { "vendor_property_id": "VP-001", "channel_id": "133", "channel_name": "Airbnb", "status": "enabled", "channel_property_id": "123456789", "roomtype_mappings": [], "rateplan_mappings": [] } ``` `channel_property_id`에 **인증된 호스트 계정 ID**가 채워져 있으면 인증 완료입니다. 매핑 저장은 성공 복귀(302)를 보내기 전에 끝나므로, 성공 복귀 후라면 보통 첫 조회에서 바로 확인됩니다. ## 성공 · 실패 판정 기준[​](#성공--실패-판정-기준 "성공 · 실패 판정 기준에 대한 직접 링크") | 관측된 상태 | 판정 | 다음 행동 | | --------------------------------------------------------- | ------------- | ------------------------------------------------------------------------------------- | | `auth_result=success` + 매핑에 `channel_property_id` 있음 | **인증 완료** | 객실·요금제 매핑 진행 | | `auth_result=success` + 매핑에 값 없음 | 비정상 조합 | `vendor_property_id`가 맞는지 확인 후 1\~2회 재조회. 그래도 없으면 실패로 보고 재인증 | | `auth_result=fail` | 인증 실패 | 재시도 안내 | | 복귀 자체가 없음 | 미확정 | 매핑 조회를 1회 더 → 값이 있으면 완료, 없으면 재시도 | 단일 기준값은 매핑 조회입니다 `auth_result`는 어떤 화면을 보여줄지 정하는 힌트일 뿐입니다. 브라우저 주소는 호스트가 조작할 수 있으므로(손으로 `?auth_result=success`를 붙여 들어올 수 있음) 연동 완료의 증거로 삼으면 안 됩니다. 성공 표시 전 반드시 매핑 조회로 확정하세요. ## 복귀가 없을 때[​](#복귀가-없을-때 "복귀가 없을 때에 대한 직접 링크") 두 경우로 갈리며, 처리가 정반대입니다. | 경우 | ONDA 상태 | 공급사 처리 | | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------ | ---------------------------- | | **A. 콜백이 ONDA에 도달하지 않음**
(호스트가 에어비앤비 화면에서 이탈·거부) | 토큰·매핑 **아무것도 생성되지 않음**. 인증 코드는 일회성이라 그대로 소멸 | URL 재발급부터 다시 시도 | | **B. ONDA에는 도달했으나 브라우저 복귀만 실패**
(공급사 사이트 다운·창 닫힘) | 토큰·매핑 **이미 생성됨**. 공급사만 복귀 신호를 못 받은 상태 | 매핑 조회를 하면 완료로 잡힘 | 팁 창 닫힘·타임아웃을 **"실패 확정"이 아니라 "매핑 조회를 한 번 더 하라"는 트리거**로 다루세요. 조회해도 비어 있을 때만 미완료(경우 A)로 처리합니다. ## 재인증 · 계정 교체[​](#재인증--계정-교체 "재인증 · 계정 교체에 대한 직접 링크") | 케이스 | ONDA 동작 | 공급사가 알아야 할 것 | | ---------------------------------- | ------------------------------------------------------------------------------------ | -------------------------------------------------------- | | 같은 계정으로 재인증 | 토큰만 갱신, 기존 객실·요금제 매핑 유지 | 추가 작업 없음 | | 다른 계정으로 재인증 (호스트 교체) | 숙소 매핑이 새 계정으로 교체되고, **기존 객실·요금제 매핑은 전부 미매핑으로 초기화** | 객실·요금제 매핑을 처음부터 다시 진행해야 판매 재개 가능 | 경고 계정 교체는 매핑 초기화를 동반합니다. 재인증 진입 시 **"다른 계정으로 인증하면 객실·요금제 매핑이 초기화됩니다"** 안내를 권장합니다. ## 구현 팁[​](#구현-팁 "구현 팁에 대한 직접 링크") **복귀는 전용 경로로 받기** — 인증 복귀 전용 경로(예: `/airbnb/callback`)를 두면 그 경로에 들어온 것 자체가 복귀 신호가 됩니다. 별도 마커 파라미터 없이 `auth_result`만 읽으면 됩니다. **`redirect_url`은 URL 인코딩해서 전달** — 발급 API의 쿼리 값이라 인코딩 없이 보내면 `://` 등에서 값이 잘립니다. `https%3A%2F%2F...` 형태로 전달하세요. **새 창으로 열고 부모 화면에 알리기** — 새 창에서 진행하면 호스트가 관리 화면을 잃지 않습니다. 복귀 경로에서 부모 창에 결과를 알리고(`window.opener.postMessage` 등) 창을 닫으면, 부모 화면이 매핑 조회와 결과 표시를 이어갈 수 있습니다. **완료 확인 재조회에는 상한을 둘 것** — 보통 첫 조회로 충분하지만, 일시적 조회 실패에 대비한 재조회에는 상한을 두세요. 무한 폴링은 금물입니다. 예를 들어 2초 간격 최대 5회 조회 후에도 `channel_property_id`가 비어 있으면 실패로 판정하고 재인증을 안내합니다. **엉뚱한 계정으로 승인되지 않게 안내** — 새 창은 브라우저 로그인 세션을 공유하므로, 이미 로그인돼 있으면 그 계정으로 바로 승인될 수 있습니다. 재인증이라면 계정 교체로 간주되어 기존 매핑이 초기화됩니다. 인증 시작 전에 "연동할 계정으로 로그인돼 있는지 확인하세요" 안내를 권장합니다. **인증은 숙소 단위** — 같은 호스트 계정이 여러 숙소를 운영하더라도 인증은 `vendor_property_id` 단위로 진행됩니다. 숙소마다 발급 → 승인 → 확인을 반복해야 합니다. **인증 URL은 버튼을 누르는 시점에 발급** — 발급된 URL은 1시간만 유효하므로, 미리 발급해 화면·메일에 저장해 두면 호스트가 열 때 이미 만료돼 있을 수 있습니다. ## 자주 겪는 문제[​](#자주-겪는-문제 "자주 겪는 문제에 대한 직접 링크") 에어비앤비 화면에 "You can only authorize a test app to a test user created under that same app"이 뜹니다 개발 환경은 에어비앤비 테스트 앱으로 동작합니다. 테스트 앱은 그 앱 아래에서 생성된 테스트 유저로만 인증할 수 있으므로, 실계정을 로그아웃하고 안내받은 테스트 유저 계정으로 진행하세요. auth\_result=success로 복귀했는데 매핑 조회에 값이 없습니다 정상 흐름에서는 없는 조합입니다. 매핑 저장이 끝난 뒤에 성공 복귀가 일어나기 때문입니다. 조회한 `vendor_property_id`가 인증한 숙소와 같은지 먼저 확인하고, 1\~2회 재조회 후에도 비어 있으면 인증 실패로 보고 재인증합니다. 주소창에 손으로 붙인 `auth_result`일 가능성도 있습니다. 복귀 자체가 오지 않습니다 콜백이 ONDA에 도달하지 못한 경우(경우 A)로, 대개 아무것도 생성되지 않습니다. 다만 매핑 조회를 한 번 해보세요 — 경우 B라면 이미 연동돼 있을 수 있습니다. 비어 있으면 URL 재발급부터 재시도합니다. 인증 후 객실·요금제 매핑이 사라졌습니다 이전과 다른 계정으로 인증한 경우입니다. 재매핑이 필요합니다. --- # 직연동 레거시 채널 오픈 `channel_type=cms` 채널 중 **레거시 직연동 채널**(Booking.com, Agoda, Expedia, Trip.com 등)의 오픈 흐름입니다. 플러스 채널과 달리 **채널 설정과 매핑 단계**가 필요합니다. ## 매핑 사전 단계 분기[​](#매핑-사전-단계-분기 "매핑 사전 단계 분기에 대한 직접 링크") 채널 메타의 `requires_cms_authorization` 값에 따라 매핑 사전 단계가 갈립니다. | `requires_cms_authorization` | 매핑 사전 단계 | 예시 채널 | | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- | | `false` | 채널 측 숙소 정보 조회 — [`GET /gds/vendor/channels/{channel_id}/properties/{channel_property_id}`](/docs/api/vendor-v3/get-channel-property) | 부킹닷컴, 아고다, 익스피디아, 트립닷컴 | | `true` | OAuth 인증 — [`GET /gds/vendor/channels/{channel_id}/authorization`](/docs/api/vendor-v3/get-channel-authorization-url) · 구현은 [에어비앤비 인증 구현](/docs/api/vendor-v3/guides/airbnb-authorization) 참고 | 에어비앤비 | ## 단계별 흐름[​](#단계별-흐름 "단계별 흐름에 대한 직접 링크") 1. **채널 탐색** — [`GET /gds/vendor/channels`](/docs/api/vendor-v3/list-channels) 2. **채널 ON 신청** — [`POST .../channels/{channel_id}`](/docs/api/vendor-v3/create-property-channel-request) `{ "request_type": "on" }` 3. **매핑 사전 단계** — 위 분기 표에 따라 채널 측 숙소 정보 조회 또는 [OAuth 인증](/docs/api/vendor-v3/guides/airbnb-authorization) 4. **채널별 부가옵션 설정** — [`PATCH .../channels/{channel_id}/settings`](/docs/api/vendor-v3/update-property-channel-settings) (RFC 7396 Merge Patch) 5. **매핑** — `PATCH .../mappings` (숙소 → 객실 → 요금제) 6. **요금·영업일 전송** — [`POST .../ari`](/docs/api/vendor-v3/push-rates) (`type: overnight`) 7. **재고 전송** — [`POST .../ari/avails`](/docs/api/vendor-v3/push-avails) ## 체크리스트[​](#체크리스트 "체크리스트에 대한 직접 링크") * 채널 메타에서 `requires_cms_authorization` 값 확인 후 매핑 사전 단계 분기 * 채널 측 숙소 정보로 `channel_roomtype_id` / `channel_rateplan_id` 후보 확보 * 숙소 → 객실 → 요금제 매핑 완료 * 에어비앤비: 요금제 개념이 없어 요금제 매핑 시 `0`으로 매핑 * ON 신청 후 `processing_mode` 분기 처리 (`auto_approve` / `external_review`) * [ ] `POST .../ari` 요금·영업일 전송 완료 (`type: overnight`) * [ ] `POST .../ari/avails` 재고 전송 완료 (객실타입 단위 통합 재고 · 최대 730일) * 재고는 룸온리(객실타입) 기준 — `package` 재고를 `standalone`에 맞추어 전송 에어비앤비 요금제 매핑 에어비앤비는 요금제 개념이 없으므로 요금제 매핑 시 `channel_rateplan_id`를 `0`으로 매핑합니다. ## 채널 오픈 신청 요청 바디[​](#채널-오픈-신청-요청-바디 "채널 오픈 신청 요청 바디에 대한 직접 링크") ``` { "request_type": "on", "channel_property_id": "CP-001", "note": "채널 담당자와 협의된 오픈 요청입니다." } ``` | 필드 | 설명 | | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `request_type` | `on` (오픈) / `off` (중지) | | `channel_property_id` | 채널 측 숙소 ID (선택). `processing_mode=external_review` 채널(예: 부킹닷컴) 신청 시 함께 전송 가능. `request_type: "on"` 에만 허용되며, `off`에 전송하면 `400`. 같은 채널에서 다른 숙소가 이미 사용 중인 ID면 `409`. 제출 시 신청 시점에 숙소 매핑에 반영됩니다. | | `note` | 신청자 비고 (선택, 최대 16,000자). `on`·`off` 모두 허용되며 운영자가 확인할 전달 사항을 기입합니다. | ## 채널별 인원추가비용 설정[​](#채널별-인원추가비용-설정 "채널별 인원추가비용 설정에 대한 직접 링크") 채널별 부가옵션은 채널 설정 엔드포인트(RFC 7396 Merge Patch)로 설정합니다. 인원추가비용은 채널마다 지원 여부와 설정 방법이 다릅니다. | 채널 | 인원추가비용 | 설정 방법 | | ---------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | 익스피디아 | 미지원 | — | | 부킹닷컴 | 미지원 | — | | 트립닷컴 | 지원 | 숙소 단위 설정의 `pricing_model` — `OBP`(Occupancy Based) / `Standard`(Per Room). `OBP`인 경우 숙소 `settings.extra_adult_price`가 요금에 포함됩니다. | | 아고다 | 지원 | 인원수별 금액 전송(Occupancy Based). 기준 인원 초과분에 대해 인원수에 해당하는 금액을 채널로 전송하며, 숙소 `settings.extra_adult_price`가 포함됩니다. | | 에어비앤비 | 지원 | 객실 단위 설정 시 숙소 `settings.extra_adult_price`가 자동 반영됩니다. | 경고 객실 단위 채널 설정(`.../roomtypes/{vendor_roomtype_id}/channels/{channel_id}/settings`)은 **에어비앤비 전용**입니다. 다른 채널에서 호출하면 에러가 발생합니다. ## 부모 요금제 (`channel_parent_rateplan_id`)[​](#부모-요금제-channel_parent_rateplan_id "부모-요금제-channel_parent_rateplan_id에 대한 직접 링크") [`GET /gds/vendor/channels/{channel_id}/properties/{channel_property_id}`](/docs/api/vendor-v3/get-channel-property) 응답의 `rateplans` object에 부모 요금제 ID가 반환됩니다. * 해당 요금제는 연결은 가능하나, 별도 요금을 전송해도 채널에 전송되지 않습니다 * 요금은 `channel_parent_rateplan_id`가 가리키는 부모 요금제 요금을 기준으로 자동 변동합니다 * 지원 채널: 부킹닷컴 · 아고다 ## 채널 오픈 조건 검증[​](#채널-오픈-조건-검증 "채널 오픈 조건 검증에 대한 직접 링크") 검증 항목 전체는 [플러스 채널 오픈 가이드](/docs/api/vendor-v3/guides/channel-open-plus#%EC%B1%84%EB%84%90-%EC%98%A4%ED%94%88-%EC%A1%B0%EA%B1%B4-%EA%B2%80%EC%A6%9D)와 동일합니다. 레거시 채널 콘텐츠 검증 완화 레거시 채널(`requires_cms_authorization=false`)은 채널 오픈 시 **숙소 대표 이미지 · 카테고리 · 객실 이미지 검증을 하지 않습니다.** ## 엔드포인트[​](#엔드포인트 "엔드포인트에 대한 직접 링크") 경로 prefix는 `/gds/vendor` 입니다. **채널 탐색 · 인증** | 메서드 | 경로 | 설명 | | ------ | --------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | | `GET` | `/channels` | 전체 채널 메타 | | `GET` | `/properties/{vendor_property_id}/channels` | 숙소별 오픈 가능 채널·신청 상태 | | `GET` | `/channels/{channel_id}/properties/{channel_property_id}` | 채널 측 숙소 정보 · 응답에 `channel_parent_rateplan_id` 포함 | | `GET` | `/channels/{channel_id}/authorization` | OAuth 인증 URL — `requires_cms_authorization=true` 채널 전용 ([구현 가이드](/docs/api/vendor-v3/guides/airbnb-authorization)) | **채널 매핑** | 범위 | 메서드 | 경로 | | ------ | --------------- | ------------------------------------------------------------------- | | 숙소 | `GET` · `PATCH` | `/properties/{vendor_property_id}/channels/{channel_id}/mappings` | | 객실 | `GET` · `PATCH` | `.../roomtypes/{vendor_roomtype_id}/channels/{channel_id}/mappings` | | 요금제 | `GET` · `PATCH` | `.../rateplans/{vendor_rateplan_id}/channels/{channel_id}/mappings` | **채널 오픈 신청** | 메서드 | 경로 | 설명 | | ------ | -------------------------------------------------------- | ----------------------- | | `POST` | `/properties/{vendor_property_id}/channels/{channel_id}` | ON·OFF 신청 | | `GET` | `/properties/{vendor_property_id}/channels/{channel_id}` | 신청 상태·히스토리 조회 | --- # 플러스 채널 오픈 ONDA가 OTA 계약을 대행하는 **플러스 채널**(`channel_type=hub`)의 오픈 신청 흐름입니다. 공급사가 HUB API를 통해 ONDA에 신청합니다. 플러스 채널은 직연동 채널과 달리 **매핑·인증 단계 없이** 신청만으로 오픈됩니다. ## 단계별 흐름[​](#단계별-흐름 "단계별 흐름에 대한 직접 링크") 1. **전체 채널 조회** — [`GET /gds/vendor/channels`](/docs/api/vendor-v3/list-channels) 2. **숙소별 오픈 가능 채널 조회** — [`GET .../properties/{vendor_property_id}/channels`](/docs/api/vendor-v3/list-property-channel-requests) 3. **채널 오픈 신청** — [`POST .../properties/{vendor_property_id}/channels/{channel_id}`](/docs/api/vendor-v3/create-property-channel-request) 4. **신청 상태 확인** — [`GET .../properties/{vendor_property_id}/channels/{channel_id}`](/docs/api/vendor-v3/get-property-channel-request) ## 체크리스트[​](#체크리스트 "체크리스트에 대한 직접 링크") * 전체 채널 목록 + 이용안내 확인 * 숙소 기준 오픈 가능 채널 확인 * 오픈 신청 후 신청 상태·히스토리 추적 * 오픈 완료 후 요금재고 전송 선행 여부 확인 * 채널 오픈 조건(숙소·객실) 사전 충족 확인 — 미충족 시 자동 반려 * 숙소 `settings.extra_adult_price`가 플러스 채널 인원추가비용으로 반영되는지 확인 ## 채널 오픈 조건 검증[​](#채널-오픈-조건-검증 "채널 오픈 조건 검증에 대한 직접 링크") 오픈 신청 시 아래 숙소·객실 조건을 검증하며, **하나라도 충족되지 않으면 자동으로 반려(reject)** 됩니다. **숙소 조건** | 검증 항목 | 내용 | | -------------- | -------------------------------------------------- | | 채널 오픈 여부 | 동일 채널 중복 오픈 방지 | | 판매 상태 | ONDA Hub 판매 상태 및 공급사 판매 상태 모두 활성화 | | 숙소 삭제 여부 | 삭제된 숙소 제외 | | 숙소명 유효성 | `null` 또는 1자 등 비정상 값 제외 | | 대표 이미지 | 3장 이상 보유 | | 주소 | 정확한 주소 입력 여부 | | 카테고리 | 1개 이상 지정 | **객실 조건** | 검증 항목 | 내용 | | -------------- | ------------------------------------------------------------------------------ | | 판매 가능 객실 | 1개 이상 존재 | | 객실명 유효성 | 비정상 값 제외 | | 객실 이미지 | 3장 이상 보유 | | 예약 가능 날짜 | 최근 30일 이내 예약 가능 날짜 1일 이상 (요금·재고·영업일 3가지 조건 모두 충족) | ## 오픈 신청 처리 방식 분기[​](#오픈-신청-처리-방식-분기 "오픈 신청 처리 방식 분기에 대한 직접 링크") 채널 메타의 `processing_mode` 값에 따라 신청 처리 방식이 갈립니다. | `processing_mode` | 동작 | | ----------------- | ------------------------------------------------------------------------ | | `auto_approve` | 신청 즉시 활성화 — `request_status: "confirm"` | | `external_review` | 운영자 승인 대기 — `request_status: "pending"` → `confirm` 또는 `reject` | `external_review` 채널은 주기적으로 신청 상태를 조회해 결과를 확인합니다. ## 엔드포인트[​](#엔드포인트 "엔드포인트에 대한 직접 링크") 경로 prefix는 `/gds/vendor` 입니다. | 메서드 | 경로 | 설명 | | ------ | -------------------------------------------------------- | -------------------------------------------------------------------------------- | | `GET` | `/channels` | 전체 채널 메타 (`channel_type`, `processing_mode`, `requires_cms_authorization`) | | `GET` | `/properties/{vendor_property_id}/channels` | 숙소별 오픈 가능 채널·신청 상태 | | `POST` | `/properties/{vendor_property_id}/channels/{channel_id}` | 채널 ON 신청 (`request_type: "on"`) | | `GET` | `/properties/{vendor_property_id}/channels/{channel_id}` | 신청 상태·히스토리 조회 | --- # 콘텐츠 변경 공급사에서 콘텐츠가 변경되면 ONDA로 `PATCH` 전송해 반영합니다. 조회(`GET`)는 비상용 옵션입니다. ## 단계별 흐름[​](#단계별-흐름 "단계별 흐름에 대한 직접 링크") ## 체크리스트[​](#체크리스트 "체크리스트에 대한 직접 링크") * 변경된 콘텐츠만 `PATCH` 전송 * 변경 방향이 공급사 → ONDA (Push)인지 확인 * 숙소 `settings.extra_adult_price` 변경 시 `PATCH .../properties/{vendor_property_id}`로 전송, 해제 시 `null` 전송 * 요금제 모델 `channels` 수정 시 요금제 매핑 변경 규칙 반영 * (옵션) 비상용 조회 동작 확인 숙소 기본 추가 성인요금 변경 `settings.extra_adult_price`(정수 KRW)는 숙소 수정의 `settings` object로 변경하며, `null` 전송 시 미설정으로 초기화됩니다. 레거시 Agoda·Trip.com의 Occupancy Based 요금과 플러스 채널 인원추가비용에 반영됩니다. 요금제 모델 `channels` 수정 시 매핑 변경 * 추가(`[131] → [131, 132]`): 132만 매핑 생성 * 삭제(`[131, 132] → [131]`): 기존 매핑은 유지되며 삭제되지 않음. 이후 생성되는 요금제는 132 매핑이 생성되지 않음 * 빈값(`[131, 132] → []`): 생성 가능한 모든 채널 매핑 생성 ## 엔드포인트[​](#엔드포인트 "엔드포인트에 대한 직접 링크") **변경 전송 (필수)** | 대상 | 엔드포인트 | | ----------- | --------------------------------------------------------------------------------------------------- | | 숙소 | [`PATCH /gds/vendor/properties/{vendor_property_id}`](/docs/api/vendor-v3/update-property) | | 객실타입 | [`PATCH .../roomtypes/{vendor_roomtype_id}`](/docs/api/vendor-v3/update-roomtype) | | 요금제 모델 | [`PATCH .../rateplan-models/{vendor_rateplan_model_id}`](/docs/api/vendor-v3/update-rateplan-model) | | 요금제 | [`PATCH .../rateplans/{vendor_rateplan_id}`](/docs/api/vendor-v3/update-rateplan) | **비상용 조회 (옵션)** | 대상 | 목록 | 단건 | | ----------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------------ | | 숙소 | [`GET /gds/vendor/properties`](/docs/api/vendor-v3/list-properties) | [`GET .../{vendor_property_id}`](/docs/api/vendor-v3/get-property) | | 객실타입 | [`GET .../roomtypes`](/docs/api/vendor-v3/list-roomtypes) | [`GET .../{vendor_roomtype_id}`](/docs/api/vendor-v3/get-roomtype) | | 요금제 모델 | [`GET .../rateplan-models`](/docs/api/vendor-v3/list-rateplan-models) | [`GET .../{vendor_rateplan_model_id}`](/docs/api/vendor-v3/get-rateplan-model) | | 요금제 | [`GET .../rateplans`](/docs/api/vendor-v3/list-rateplans) | [`GET .../{vendor_rateplan_id}`](/docs/api/vendor-v3/get-rateplan) | 팁 콘텐츠 생성·수정의 기본 방향은 **공급사 → ONDA Push**(`POST`·`PATCH`)입니다. 조회는 비상용(옵셔널) 기능으로, 운영 정책에 따라 구현 여부를 결정하세요. --- # 최초 판매 준비 공급사가 ONDA로 숙소·객실타입·요금제 모델·요금제 콘텐츠를 생성(`POST`)하고, 이어서 요금재고(ARI)를 전송해 판매를 준비하는 최초 동기화 흐름입니다. 콘텐츠 생성 방향은 모두 **공급사 → ONDA**이며, 조회(`GET`)는 비상용 옵션입니다. ## 단계별 흐름[​](#단계별-흐름 "단계별 흐름에 대한 직접 링크") 1. **코드 카탈로그 조회** — [`GET /gds/vendor/meta`](/docs/api/vendor-v3/get-meta-codes) (숙소·객실 생성 시 사용할 `_tags` 등 tag code 조회) 2. **숙소 생성** — [`POST /gds/vendor/properties`](/docs/api/vendor-v3/create-property) 3. **객실타입 생성** — [`POST .../{vendor_property_id}/roomtypes`](/docs/api/vendor-v3/create-roomtype) 4. **요금제 모델 생성** — [`POST .../{vendor_property_id}/rateplan-models`](/docs/api/vendor-v3/create-rateplan-model) 5. **요금제 생성** — [`POST .../roomtypes/{vendor_roomtype_id}/rateplans`](/docs/api/vendor-v3/create-rateplan) (`vendor_rateplan_model_id` 결합) 6. **요금·영업일 전송** — [`POST .../ari`](/docs/api/vendor-v3/push-rates) (요금제 단위) 7. **재고 전송** — [`POST .../ari/avails`](/docs/api/vendor-v3/push-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) 활용[​](#코드-카탈로그meta-활용 "코드 카탈로그(meta) 활용에 대한 직접 링크") 숙소·객실의 코드성 필드(`_tags` 등)는 임의 문자열이 아니라 ONDA가 정의한 tag code를 사용해야 합니다. * 조회: [`GET /gds/vendor/meta`](/docs/api/vendor-v3/get-meta-codes) — 사용 가능한 코드 목록 반환 * 최초 동기화(콘텐츠 생성) 전 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`)[​](#숙소-기본-추가-성인요금-settingsextra_adult_price "숙소-기본-추가-성인요금-settingsextra_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) 전송[​](#요금영업일ari--재고avails-전송 "요금·영업일(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` 재고와 동일하게 전송하세요. --- # 매핑 수정 · 판매 중지 직연동 채널의 숙소·객실·요금제 매핑을 수정하거나, 더 이상 판매하지 않는 채널의 매핑을 제거하는 흐름입니다. 모두 `PATCH`로 처리하며, 삭제는 매핑 값을 `null`로 전달합니다. 직연동 채널 전용 채널 매핑 `PATCH`는 **직연동 채널**(`channel_type=cms`)만 가능합니다. 플러스 채널(`channel_type=hub`)은 ONDA가 매핑을 관리하므로 매핑 조회·수정·삭제 대상이 아닙니다. ## 매핑 수정[​](#매핑-수정 "매핑 수정에 대한 직접 링크") ## 판매 중지 — 매핑 삭제[​](#판매-중지--매핑-삭제 "판매 중지 — 매핑 삭제에 대한 직접 링크") 동일한 `PATCH` 엔드포인트에 매핑 값을 `null`로 전달하면 매핑이 삭제됩니다. 별도의 `DELETE` 메서드는 없습니다. 숙소 → 객실 → 요금제 순으로 매핑을 제거합니다. ## 엔드포인트[​](#엔드포인트 "엔드포인트에 대한 직접 링크") | 범위 | 조회 | 수정 · 삭제 | | ------ | ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | | 숙소 | [`GET .../channels/{channel_id}/mappings`](/docs/api/vendor-v3/get-property-mapping) | [`PATCH`](/docs/api/vendor-v3/update-property-mapping) | | 객실 | [`GET .../roomtypes/{vendor_roomtype_id}/channels/{channel_id}/mappings`](/docs/api/vendor-v3/get-roomtype-mapping) | [`PATCH`](/docs/api/vendor-v3/update-roomtype-mapping) | | 요금제 | [`GET .../rateplans/{vendor_rateplan_id}/channels/{channel_id}/mappings`](/docs/api/vendor-v3/get-rateplan-mapping) | [`PATCH`](/docs/api/vendor-v3/update-rateplan-mapping) | ## 체크리스트[​](#체크리스트 "체크리스트에 대한 직접 링크") * 매핑 `PATCH`는 직연동 채널만 호출 — 플러스 채널 제외 검증 * 숙소·객실·요금제 매핑 수정 처리 * 판매 중지 시 매핑 값 `null` 처리 * 매핑 변경 후 반영 결과 확인 채널 자체를 중지하려면 매핑 삭제와 별개로, 채널 판매를 중지하려면 [`POST .../channels/{channel_id}`](/docs/api/vendor-v3/create-property-channel-request)에 `{ "request_type": "off" }`로 OFF 신청합니다. --- # 공통 · 개요 Vendor API 3.0 연동을 시작하기 전에 전체 구조와 준비 항목을 확인합니다. 엔드포인트 총괄 HUB API **38개** + 공급사 API(Webhook) **5개** = 총 **43개** HUB API 메서드 규칙: 생성 `POST` · 수정 `PATCH` · 조회 `GET`, 성공 응답 `200 OK` 공급사 API는 동작에 따라 메서드가 다릅니다. 예약 확정·변경은 `PUT`, 예약 생성·취소는 `POST`, 정책 조회는 `GET`입니다. ## API 방향 · 역할 구분 (필독)[​](#api-방향--역할-구분-필독 "API 방향 · 역할 구분 (필독)에 대한 직접 링크") 채널은 **플러스 채널**(`channel_type=hub`)과 **직연동 채널**(`channel_type=cms`)로 나뉩니다. HUB API에서 공급사는 클라이언트, 공급사 API(Webhook)에서 공급사는 서버입니다. | 구분 | 방향 | 공급사 구현 역할 | | -------------------- | ------------- | ------------------------------------------------------------------------------------- | | HUB API | 공급사 → ONDA | **클라이언트** — `/gds/vendor/...` 호출 (콘텐츠 Push, ARI Push, 채널, 예약·정산 조회) | | 공급사 API (Webhook) | ONDA → 공급사 | **서버** — ONDA가 호출하는 엔드포인트 제공 (예약 처리, 정책 조회) | ## 채널 유형 — 플러스와 직연동[​](#채널-유형--플러스와-직연동 "채널 유형 — 플러스와 직연동에 대한 직접 링크") ONDA에 연결된 판매 채널은 **누가 채널을 운영하느냐**에 따라 두 가지로 나뉩니다. 이 구분이 채널 오픈 절차부터 예약 처리 방식까지 전 과정의 차이를 만듭니다. | | **플러스 채널** | **직연동 채널** | | ------------------- | ---------------------------------------------------- | ------------------------------------------- | | `channel_type` | `hub` | `cms` | | 한 줄 정의 | ONDA와 한 번 계약하면 ONDA에 연결된 채널 전체에 판매 | 숙소가 OTA와 직접 계약하고 채널을 직접 운영 | | 채널 등록·운영·정산 | ONDA가 대행 | 숙소가 직접 | ### 단계별로 누가 처리하나요?[​](#단계별로-누가-처리하나요 "단계별로 누가 처리하나요?에 대한 직접 링크") | 처리 항목 | 플러스 채널 | 직연동 채널 | | ------------------ | -------------------------- | ------------------- | | 요금 · 재고 동기화 | ONDA | ONDA | | 채널 계약 | ONDA | 숙소가 직접 | | 입점 · 정보 배포 | ONDA | 숙소가 직접 | | 정산 · 회계 | ONDA | 숙소가 직접 | | 예약 확정 방식 | ONDA가 유효성 검사 후 확정 | 검사 없이 즉시 생성 | 요금·재고 동기화는 **두 유형 모두 ONDA를 거칩니다.** 공급사가 구현할 콘텐츠·ARI 전송 코드는 채널 유형과 무관하게 동일합니다. **플러스 채널** — 계약부터 정산까지 ONDA를 거칩니다. **직연동 채널** — 요금·재고만 ONDA를 거치고, 계약·정산은 숙소가 채널과 직접 진행합니다. ### API에서는 무엇이 달라지나요?[​](#api에서는-무엇이-달라지나요 "API에서는 무엇이 달라지나요?에 대한 직접 링크") | 항목 | 플러스 채널 | 직연동 채널 | | ------------------- | --------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | | 채널 오픈 | 신청만 하면 됨 — [플러스 채널 오픈](/docs/api/vendor-v3/guides/channel-open-plus) | 매핑 사전 단계 · 채널 설정 · 매핑이 필요 — [직연동 레거시 채널 오픈](/docs/api/vendor-v3/guides/channel-open-legacy) | | 매핑 API | 사용하지 않음 (ONDA가 관리) | `PATCH .../mappings` 필수 | | 채널별 부가 설정 | 사용하지 않음 | `PATCH .../settings` 사용 | | 예약 유효성 검사 | ONDA · 공급사 각자 수행 | 없음 — 무조건 수용 | | 예약 변경(`modify`) | Soft Change만 허용 | Soft · Hard Change 모두 | | 상품 `type` | `overnight` | `overnight` (대실을 지원하는 채널은 `dayuse` 추가) | 채널 유형은 채널마다 다릅니다 숙소 단위가 아니라 **채널 단위**로 정해집니다. 한 숙소가 어떤 채널은 플러스로, 어떤 채널은 직연동으로 운영할 수 있습니다. [`GET /gds/vendor/channels`](/docs/api/vendor-v3/list-channels) 응답의 `channel_type`으로 확인하세요. 숙소 운영자 관점의 설명은 [ONDA Plus 채널 매니저 소개](https://global.onda.me/ko/onda-plus/)에서 볼 수 있습니다. ## 연동 라이프사이클[​](#연동-라이프사이클 "연동 라이프사이클에 대한 직접 링크") ## 연동 준비 체크리스트[​](#연동-준비-체크리스트 "연동 준비 체크리스트에 대한 직접 링크") * HUB API 호출용 베이스 URL 확정 및 환경(스테이징·운영) 분리 * 공급사 API(Webhook) 수신 서버 엔드포인트 및 베이스 URL 제공 * 인증: HUB API 호출 시 `Authorization` 헤더에 Vendor access token 적용 * 인증: 공급사 API 수신 시 ONDA 요청에 대한 토큰·서명 검증 로직 구현 * [ ] [코드 카탈로그 조회](/docs/api/vendor-v3/get-meta-codes) 후 코드 매핑 테이블 내재화 ## 출시 전 통합 검증[​](#출시-전-통합-검증 "출시 전 통합 검증에 대한 직접 링크") * 최초 동기화 E2E: 숙소 → 객실타입 → 요금제 모델 → 요금제 생성 후 요금·영업일·재고 Push까지 채널 반영 확인 * 플러스 채널 오픈 → 예약 발생 → 확정 → 취소 전체 플로우 검증 * 직연동 채널(레거시·OAuth) 매핑 → ON 신청 → 예약 플로우 검증 * 인증 토큰 만료·갱신 및 오류 응답(4xx·5xx) 처리 검증 * 멱등성·재시도 정책(중복 예약·중복 취소 방지) 검증 * 스테이징 검증 완료 후 운영 전환 사인오프 ## 운영 · 비즈니스 로직 확인[​](#운영--비즈니스-로직-확인 "운영 · 비즈니스 로직 확인에 대한 직접 링크") API 구현과 별개로, 라이브 전 ONDA와 협의·확인해야 하는 항목입니다. 📘 표기 항목은 별도 가이드로 정리돼 있습니다. | 분류 | 항목 | 확인 내용 | | --------------- | ---------------------------- | ----------------------------------------------------------------------------------------------------- | | 콘텐츠·언어 | 다국어 콘텐츠 사용 여부 | 한국어 외 언어 사용 여부. 사용 시 전송 방법 협의 | | 콘텐츠·언어 | 숙소명·숙소 소개 특수문자 | 표기 불가 특수문자 제외 처리 | | 콘텐츠·언어 | 객실명·객실 설명 특수문자 | 표기 불가 특수문자 제외 처리 | | 판매범위·상품 | 판매 숙소 범위 | 해외 숙소 판매 / 국내만 판매 여부 | | 판매범위·상품 | 상품 구성 | 객실 단위 vs 객실별 패키지(요금제) 판매 여부 | | 요금·재고 | 추가인원 요금 | 추가인원 요금 전송 가능 여부 | | 요금·재고 | 요금재고 전송 기간 | 몇 개월치 전송 가능한지 | | 예약구조·유효성 | 예약 번호 구조 인지 📘 | 1 `gds_booking_number` : N `gds_sub_booking_number`. 공급사 예약은 `gds_sub_booking_number` 기준 생성 | | 예약구조·유효성 | 플러스 채널 예약 유효성 검사 | 재고·요금 일치·판매상태 활성 등 검사 수행 | | 취소·환불 | 일자별 취소환불 정책 📘 | 날짜별 정책 상이 여부 확인 ([취소환불 정책](/docs/api/vendor-v3/guides/refund-policy)) | | 바우처 | 예약 바우처 발송 | 확정·취소 바우처를 공급사가 숙소에 직접 발송 | ## 예약 번호 구조[​](#예약-번호-구조 "예약 번호 구조에 대한 직접 링크") | 필드 | 설명 | | ------------------------ | ------------------------------------------------------------------------------------------------------------- | | `gds_booking_number` | ONDA Hub 예약 번호 | | `gds_sub_booking_number` | ONDA Hub 서브 예약 번호. 공급사 예약은 **이 값 기준**으로 생성 | | `channel_booking_number` | 판매 채널 예약 번호. 판매 채널이 자기 예약 번호를 주지 않으면 **키 자체가 생략**되므로 필수로 기대하지 마세요 | `gds_booking_number` 1건에 `gds_sub_booking_number` N건이 대응하며, 공급사의 `booking_number`와 `gds_sub_booking_number`는 1:1입니다. --- # 취소환불 정책 날짜별로 취소환불 정책이 다를 수 있어, 숙소 단위 기본 정책과 일자별 정책을 구분해 처리합니다. 정책을 잘못 전달하면 고객 위약금이 과다 청구되어 클레임으로 이어집니다. ## 정책의 두 종류[​](#정책의-두-종류 "정책의 두 종류에 대한 직접 링크") | 종류 | 전달 방식 | | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | **숙소 기본 취소환불 정책** | 숙소 `refunds` 필드에 **1개**만 전달 | | **일자별 취소환불 정책** | [`GET .../rateplans/{vendor_rateplan_id}/refund_policy`](/docs/api/vendor-v3/webhook-get-refund-policy) 조회 API로 제공 (공급사가 구현) | ## 처리 규칙[​](#처리-규칙 "처리 규칙에 대한 직접 링크") 1. 기본 정책은 숙소 `refunds`에 **1개만** 전달합니다. 2. 예약 직전 고객 확인용 정책은 `refund_policy` 조회 API로 **일자별 정책**을 내려줍니다. 3. 실제 예약 생성 시에는 숙소 단위 정책이 아니라 **일자별 취소환불 정책**으로 내려줍니다. 4. 숙소 기본 정책은 일자별 정책 중 **가장 보수적인 값**으로 설정합니다. 5. 숙소 정책이 일자별 정책보다 고객 위약금을 더 발생시켜서는 안 됩니다. 위험 숙소 기본 정책이 일자별 정책보다 고객에게 불리하면(위약금 과다) **클레임이 발생합니다.** 반드시 일자별 정책 중 가장 보수적인 값으로 맞추세요. ## 레거시 채널의 취소환불 정책[​](#레거시-채널의-취소환불-정책 "레거시 채널의 취소환불 정책에 대한 직접 링크") 정보 직연동 레거시 채널(부킹닷컴·아고다·익스피디아 등)은 ONDA·숙소 공통 정책이 아니라 **각 채널에 직접 설정한 취소환불 규정**을 따릅니다. 위 규칙은 플러스 채널 기준입니다. ## 체크리스트[​](#체크리스트 "체크리스트에 대한 직접 링크") * 숙소 `refunds`에 기본 정책 1개 전달 * 일자별 정책을 `refund_policy` 조회 API로 제공 * 예약 생성 시 일자별 취소환불 정책으로 전달 * 기본 정책 = 일자별 정책 중 가장 보수적인 값 * 기본 정책이 일자별 정책보다 고객 위약금이 과다하지 않은지 검증 * 레거시 채널은 각 채널에 설정된 취소환불 규정을 따르도록 처리 --- # 직연동 채널 예약 직연동 채널 예약의 가예약·확정·변경·취소 흐름입니다. 플러스 채널과 달리 **유효성 검사 없이 모든 단계를 무조건 수용**합니다. ## 플러스 채널과의 차이[​](#플러스-채널과의-차이 "플러스 채널과의 차이에 대한 직접 링크") | 항목 | 플러스 채널 | 직연동 채널 | | ----------- | --------------------- | -------------------------------------------------- | | 유효성 검사 | ONDA·공급사 각자 수행 | 없음 — 무조건 수용 | | 예약 변경 | Soft Change만 | Soft · Hard Change 모두 | | 예약 `type` | `overnight` | `overnight` (대실을 지원하는 채널은 `dayuse` 추가) | ## 단계별 흐름[​](#단계별-흐름 "단계별 흐름에 대한 직접 링크") 1. **가예약 생성** — [`POST /bookings`](/docs/api/vendor-v3/webhook-create-booking) (검사 없이 수용, 재고 차감) 2. **예약 확정** — [`PUT /bookings/{vendor_booking_number}/confirm`](/docs/api/vendor-v3/webhook-confirm-booking) 3. **예약 변경** — [`PUT /bookings/{vendor_booking_number}/modify`](/docs/api/vendor-v3/webhook-modify-booking) (Soft · Hard Change) 4. **예약 취소** — [`POST /bookings/{vendor_booking_number}/cancel`](/docs/api/vendor-v3/webhook-cancel-booking) ## 예약 변경 유형[​](#예약-변경-유형 "예약 변경 유형에 대한 직접 링크") `modify` 요청은 변경 범위에 따라 구분합니다. 직연동 채널은 두 유형을 모두 허용합니다. | 유형 | 범위 | | --------------- | ----------------------------------------------------------------------- | | **Soft Change** | 예약자·투숙자 정보 변경 (재고·일정에 영향 없는 메타성 변경) | | **Hard Change** | 체크인·체크아웃(투숙일) 변경, 예약 객실 변경 등 (재고·요금·매핑에 영향) | ## 체크리스트[​](#체크리스트 "체크리스트에 대한 직접 링크") * 모든 예약 단계 무조건 수용 처리 (유효성 검사 없음) * 예약 `type` 처리 — 대실을 지원하는 채널은 `overnight` + `dayuse`, 그 외 채널은 `overnight`만 * [ ] `visit_type`(방문수단 `car`·`walk`) 수신·처리 * 실제 공급사 예약은 `gds_sub_booking_number` 기준으로 생성 * [ ] `modify` 처리 흐름 구현 — Soft Change / Hard Change 구분 처리 * Hard Change 시 재고 차감·복원 및 요금 재계산 처리 * 예약 바우처(확정·취소) 숙소에 직접 발송 ## 주요 필드[​](#주요-필드 "주요 필드에 대한 직접 링크") | 필드 | 엔드포인트 | 설명 | | ------------------- | --------------------------------- | ----------------------------------------------------------------------------------------------- | | `payment_type` | `POST /bookings` · `confirm` 응답 | 선결제(`prepayment`) / 후결제(`postpayment`) 구분. `paid_amount`(결제 금액)는 제거됐습니다. | | `net_price` | `POST /bookings` · `modify` 요청 | 수수료를 제외한 정산금액(입금예정액) | | `canceled_by` | `cancel` 요청 | 취소 주체 — `user` / `admin` / `channel` / `system` | | `memo` | `cancel` 요청 | 취소 사유·메모. 채널 관리자가 취소한 경우 `canceled_by=channel`과 함께 사유가 전달됩니다 | | `type` | `POST /bookings` 요청 | `overnight`(숙박). 대실을 지원하는 채널은 `dayuse`가 함께 전달됩니다 | | `visit_type` | `POST /bookings` 요청 | 투숙객 방문수단 — `car`(차량) / `walk`(도보). 대실을 지원하는 일부 채널에서만 전달됩니다 | | `secondary_channel` | `POST /bookings` 요청 | 2차 채널링으로 판매된 경우의 판매 경로(정보성). 이를 지원하는 일부 레거시 채널에서만 전달됩니다 | 예약 번호 구조는 [공통 · 개요](/docs/api/vendor-v3/guides/overview#%EC%98%88%EC%95%BD-%EB%B2%88%ED%98%B8-%EA%B5%AC%EC%A1%B0)를 참고하세요. ## 엔드포인트[​](#엔드포인트 "엔드포인트에 대한 직접 링크") 모두 **공급사 API**(ONDA → 공급사)입니다. | 메서드 | 경로 | 설명 | | ------ | -------------------------------------------------- | ------------------------------ | | `GET` | `.../rateplans/{vendor_rateplan_id}/refund_policy` | 취소·환불 정책 사전 조회 | | `POST` | `/bookings` | 가예약 생성 (재고 차감) | | `PUT` | `/bookings/{vendor_booking_number}/confirm` | 예약 확정 | | `PUT` | `/bookings/{vendor_booking_number}/modify` | 예약 변경 (Soft · Hard Change) | | `POST` | `/bookings/{vendor_booking_number}/cancel` | 예약 취소 | --- # 플러스 채널 예약 플러스 채널 예약의 가예약·확정·변경·취소 흐름입니다. **각 단계마다 ONDA와 공급사가 각자 유효성 검사**를 수행합니다. 예약 처리 엔드포인트는 모두 **공급사 API**(ONDA → 공급사)이므로, 공급사가 서버로 구현합니다. ## 단계별 흐름[​](#단계별-흐름 "단계별 흐름에 대한 직접 링크") 1. **취소환불정책 사전 조회** — [`GET .../rateplans/{vendor_rateplan_id}/refund_policy`](/docs/api/vendor-v3/webhook-get-refund-policy) 2. **가예약 생성** — [`POST /bookings`](/docs/api/vendor-v3/webhook-create-booking) (유효성 검사 후 재고 차감) 3. **예약 확정** — [`PUT /bookings/{vendor_booking_number}/confirm`](/docs/api/vendor-v3/webhook-confirm-booking) 4. **예약 변경** — [`PUT /bookings/{vendor_booking_number}/modify`](/docs/api/vendor-v3/webhook-modify-booking) (**Soft Change만 허용**) 5. **예약 취소** — [`POST /bookings/{vendor_booking_number}/cancel`](/docs/api/vendor-v3/webhook-cancel-booking) 6. **재고 재전송** — [`POST .../ari/avails`](/docs/api/vendor-v3/push-avails) ## 체크리스트[​](#체크리스트 "체크리스트에 대한 직접 링크") * 가예약·확정·취소 각 단계 유효성 검사 (재고·요금·판매상태·영업일) * 가예약 생성 후 15분 이내 `confirm` 미호출 시 가예약 자동 취소(재고 복원) 로직 구현 * 실제 공급사 예약은 `gds_sub_booking_number` 기준으로 생성 * 예약 직전 일자별 취소환불 정책 전달 * 확정 후 변경된 재고 재전송 (`POST .../ari/avails`) * 예약 `type`은 `overnight`(숙박)만 사용 * [ ] `modify`는 Soft Change만 허용 — Hard Change 요청 수신 시 거부·예외 처리 규격 정의 * 예약 바우처(확정·취소) 숙소에 직접 발송 플러스 채널의 `modify`는 Soft Change만 허용 예약자·투숙자 정보 변경 같은 메타성 변경만 가능합니다. 투숙일 변경·예약 객실 변경 등 **Hard Change는 플러스 채널에서 허용되지 않으며**, 필요한 경우 취소 후 재예약으로 처리합니다. (직연동 채널은 Hard Change도 허용) 가예약 자동 취소 — 15분 타임아웃 가예약 생성 후 **15분 이내**에 예약 확정 호출이 없으면 해당 가예약은 **자동으로 취소 처리**되고 재고가 복원됩니다. ## 주요 필드[​](#주요-필드 "주요 필드에 대한 직접 링크") | 필드 | 엔드포인트 | 설명 | | -------------- | --------------------------------- | -------------------------------------------------------------------------------------------- | | `payment_type` | `POST /bookings` · `confirm` 응답 | 플러스 채널은 **항상 `prepayment`(선결제)** 입니다. `paid_amount`(결제 금액)는 제거됐습니다. | | `net_price` | `POST /bookings` · `modify` 요청 | 수수료를 제외한 정산금액(입금예정액) | | `canceled_by` | `cancel` 요청 | 취소 주체 — `user` / `admin` / `channel` / `system` | | `memo` | `cancel` 요청 | 취소 사유·메모. 채널 관리자가 취소한 경우 `canceled_by=channel`과 함께 사유가 전달됩니다 | | `type` | `POST /bookings` 요청 | `overnight`(숙박)만 사용합니다 | 플러스 채널에서 취급하지 않는 필드 스펙에는 있지만 플러스 채널 예약에서는 전달되지 않습니다. 구현 대상이 아닙니다. * `visit_type` — 방문수단. 대실을 지원하는 일부 직연동 채널에서만 사용합니다 * `secondary_channel` — 2차 채널링 판매 경로. 이를 지원하는 일부 레거시 채널에서만 전달됩니다 예약 번호 구조는 [공통 · 개요](/docs/api/vendor-v3/guides/overview#%EC%98%88%EC%95%BD-%EB%B2%88%ED%98%B8-%EA%B5%AC%EC%A1%B0)를 참고하세요. 공급사 예약은 반드시 `gds_sub_booking_number` 기준으로 생성합니다. ## 엔드포인트[​](#엔드포인트 "엔드포인트에 대한 직접 링크") 모두 **공급사 API**(ONDA → 공급사)입니다. | 메서드 | 경로 | 설명 | | ------ | -------------------------------------------------- | ------------------------- | | `GET` | `.../rateplans/{vendor_rateplan_id}/refund_policy` | 취소·환불 정책 사전 조회 | | `POST` | `/bookings` | 가예약 생성 (재고 차감) | | `PUT` | `/bookings/{vendor_booking_number}/confirm` | 예약 확정 | | `PUT` | `/bookings/{vendor_booking_number}/modify` | 예약 변경 (Soft Change만) | | `POST` | `/bookings/{vendor_booking_number}/cancel` | 예약 취소 | 공급사가 ONDA의 예약 데이터를 조회할 때는 HUB API인 [`GET /gds/vendor/bookinglist`](/docs/api/vendor-v3/list-bookings) · [`GET /gds/vendor/booking/{vendor_booking_number}`](/docs/api/vendor-v3/get-booking)를 사용합니다. --- # 정산 조회 ONDA의 정산 금액 데이터를 공급사가 직접 조회해 내부 정산과 대사하는 흐름입니다. ## 단계별 흐름[​](#단계별-흐름 "단계별 흐름에 대한 직접 링크") ## 엔드포인트[​](#엔드포인트 "엔드포인트에 대한 직접 링크") | 용도 | 엔드포인트 | | ---------------- | ------------------------------------------------------------------------------------ | | 정산 비교 조회 | [`GET /gds/vendor/bookings`](/docs/api/vendor-v3/get-settlement-comparison) | | 예약 리스트 조회 | [`GET /gds/vendor/bookinglist`](/docs/api/vendor-v3/list-bookings) | | 예약 단건 조회 | [`GET /gds/vendor/booking/{vendor_booking_number}`](/docs/api/vendor-v3/get-booking) | ## 체크리스트[​](#체크리스트 "체크리스트에 대한 직접 링크") * 정산 금액 데이터 조회 및 내부 정산과 대사 * 예약 리스트·상세 조회 연계 확인 * 정산 불일치 건 처리 프로세스 정의 정보 예약 데이터의 `net_price`는 수수료를 제외한 정산금액(입금예정액)입니다. 정산 대사 시 이 값을 기준으로 비교합니다. --- # 상태 변경 숙소·객실타입·요금제 모델·요금제의 활성·비활성 상태를 공급사가 ONDA에 `PATCH`로 반영하는 흐름입니다. ## 단계별 흐름[​](#단계별-흐름 "단계별 흐름에 대한 직접 링크") ## 엔드포인트[​](#엔드포인트 "엔드포인트에 대한 직접 링크") | 대상 | 엔드포인트 | | ----------- | --------------------------------------------------------------------------------------------------- | | 숙소 | [`PATCH /gds/vendor/properties/{vendor_property_id}`](/docs/api/vendor-v3/update-property) | | 객실타입 | [`PATCH .../roomtypes/{vendor_roomtype_id}`](/docs/api/vendor-v3/update-roomtype) | | 요금제 모델 | [`PATCH .../rateplan-models/{vendor_rateplan_model_id}`](/docs/api/vendor-v3/update-rateplan-model) | | 요금제 | [`PATCH .../rateplans/{vendor_rateplan_id}`](/docs/api/vendor-v3/update-rateplan) | ## 체크리스트[​](#체크리스트 "체크리스트에 대한 직접 링크") * 숙소 단위 활성·비활성 반영 * 객실타입·요금제 모델·요금제 단위 활성·비활성 반영 * 상태 변경 응답 `200 OK` 확인 정보 상태 변경과 콘텐츠 변경은 동일한 `PATCH` 엔드포인트를 사용합니다. `PATCH`는 RFC 7396 Merge Patch를 따르므로, 상태 필드만 담아 전송하면 나머지 콘텐츠는 그대로 유지됩니다. --- # 예약 리스트 조회 ``` GET /gds/vendor/bookinglist ``` * 기간으로 예약 목록을 조회합니다. * `from`과 `to`가 필수입니다. * 예약 처리 자체는 ONDA가 공급사 엔드포인트를 호출하는 방식이므로, 이 API는 공급사가 자기 데이터와 대조하거나 누락을 찾을 때 사용합니다. ## Request[​](#request "Request에 대한 직접 링크") ## Responsesapplication/json[​](#responses "responses에 대한 직접 링크") * 200 * 400 * 401 * 403 * 404 예약 목록 Bad Request Unauthorized Forbidden Not Found --- # 판매 채널 조회 ``` GET /gds/vendor/channels ``` * 공급사의 판매 채널 목록을 조회합니다. * 응답의 `processing_mode` 로 채널별 오픈 신청 처리 방식(auto\_approve / external\_review)을 확인할 수 있습니다. ## Responsesapplication/json[​](#responses "responses에 대한 직접 링크") * 200 * 400 * 401 * 500 채널 목록 Bad Request Unauthorized Internal Server Error --- # 숙소 목록 조회 ``` GET /gds/vendor/properties ``` * 공급사가 등록한 숙소 목록을 조회합니다. * 3.0에서 콘텐츠는 공급사가 ONDA로 전송하는 것이 기본이므로, 조회는 전송 결과를 확인하거나 장애 시 대조하는 보조 수단입니다. * ONDA에 저장된 값을 그대로 반환하므로, 공급사 데이터와 어긋나는 항목을 찾을 때 사용합니다. ## Responsesapplication/json[​](#responses "responses에 대한 직접 링크") * 200 * 400 * 401 * 403 * 404 * 409 숙소 목록 Bad Request (식별자 path/body 불일치 등) Unauthorized Forbidden Not Found Conflict (이미 존재하는 id) --- # 숙소별 채널 신청 목록 ``` GET /gds/vendor/properties/:vendor_property_id/channels ``` 현재 공급사 화이트리스트나 채널 상태와 무관하게 숙소에서 실제 신청 이력이 있는 채널과 각 채널의 최신 신청 상태를 조회합니다. ## Request[​](#request "Request에 대한 직접 링크") ## Responsesapplication/json[​](#responses "responses에 대한 직접 링크") * 200 * 400 * 401 * 403 * 404 * 500 신청 이력이 없으면 빈 배열을 반환하는 채널 신청 현황 목록입니다. Bad Request Unauthorized Forbidden Not Found Internal Server Error --- # 요금제 모델 목록 조회 ``` GET /gds/vendor/properties/:vendor_property_id/rateplan-models ``` * 숙소에 등록된 요금제 모델 목록을 조회합니다. * 3.0에서 콘텐츠는 공급사가 ONDA로 전송하는 것이 기본이므로, 조회는 전송 결과를 확인하는 보조 수단입니다. * 요금제를 만들기 전에 결합할 모델의 `id`를 확인할 때 사용할 수 있습니다. ## Request[​](#request "Request에 대한 직접 링크") ## Responsesapplication/json[​](#responses "responses에 대한 직접 링크") * 200 * 400 * 401 * 403 * 404 * 409 요금제 모델 목록 Bad Request (식별자 path/body 불일치 등) Unauthorized Forbidden Not Found Conflict (이미 존재하는 id) --- # 요금제 목록 조회 ``` GET /gds/vendor/properties/:vendor_property_id/roomtypes/:vendor_roomtype_id/rateplans ``` * 객실타입에 연결된 요금제 목록을 조회합니다. * 3.0에서 콘텐츠는 공급사가 ONDA로 전송하는 것이 기본이므로, 조회는 전송 결과를 확인하는 보조 수단입니다. * 요금·영업일 전송에 사용할 `vendor_rateplan_id`를 확인할 때 사용합니다. ## Request[​](#request "Request에 대한 직접 링크") ## Responsesapplication/json[​](#responses "responses에 대한 직접 링크") * 200 * 400 * 401 * 403 * 404 * 409 요금제 목록 Bad Request (식별자 path/body 불일치 등) Unauthorized Forbidden Not Found Conflict (이미 존재하는 id) --- # 객실타입 목록 조회 ``` GET /gds/vendor/properties/:vendor_property_id/roomtypes ``` * 숙소에 속한 객실타입 목록을 조회합니다. 응답에는 각 객실타입에 연결된 요금제 정보도 함께 담깁니다. * 3.0에서 콘텐츠는 공급사가 ONDA로 전송하는 것이 기본이므로, 조회는 전송 결과를 확인하는 보조 수단입니다. * 객실타입과 요금제의 연결 상태를 한 번에 확인할 때 유용합니다. ## Request[​](#request "Request에 대한 직접 링크") ## Responsesapplication/json[​](#responses "responses에 대한 직접 링크") * 200 * 400 * 401 * 403 * 404 * 409 객실타입 목록 Bad Request (식별자 path/body 불일치 등) Unauthorized Forbidden Not Found Conflict (이미 존재하는 id) --- Version: 3.0.0 Export * [OpenAPI Spec](/openapi/vendor/vendor-v30-api.yaml) # ONDA Vendor API 3.0 ONDA Vendor API 3.0 — 공급사(Vendor) 연동 API ## Authentication[​](#authentication "Authentication에 대한 직접 링크") * API Key: Authorization Vendor access token | Security Scheme Type: | apiKey | | ---------------------- | ------------- | | Header parameter name: | Authorization | --- # 재고 전송 ``` POST /gds/vendor/properties/:vendor_property_id/ari/avails ``` * 재고(vacancy)를 설정합니다(항목당 `vacancy` 필수). * 재고는 객실(roomtype) 단위로 반영됩니다. * 해당 객실(roomtype)에 생성된 요금제(rateplan)가 하나도 없으면 전송한 재고가 반영되지 않습니다. * `channels` 배열에 없는 채널의 재고 설정은 구간(from-to) 내에서 삭제됩니다(생략/빈 배열 = 전 채널 재고 설정 삭제). * 기간은 항목당 최대 730일입니다. ## Request[​](#request "Request에 대한 직접 링크") ## Responsesapplication/json[​](#responses "responses에 대한 직접 링크") * 200 * 400 * 401 * 403 * 404 설정 결과 Bad Request Unauthorized Forbidden Not Found --- # 요금/영업일 전송 ``` POST /gds/vendor/properties/:vendor_property_id/ari ``` * 요금·영업일을 설정합니다. * 항목마다 `is_business_day`와 `net_price` 또는 `sale_price`가 필수입니다. * `channels`의 각 채널에는 `is_business_day`와 항목에 보낸 요금 필드를 똑같이 넣어야 합니다(빠뜨리거나 항목에 없는 요금 필드를 넣으면 400). * `channels`에 없는 채널의 요금·영업일 설정은 구간(from-to) 내에서 삭제됩니다(생략/빈 배열 = 전 채널 설정 삭제). * 대실(dayuse) 항목에만 use\_from/use\_to/use\_time을 보낼 수 있습니다(use\_time 단위는 분). * 재고는 재고 전송 API(`POST /gds/vendor/properties/{vendor_property_id}/ari/avails`)를 사용하세요. ## Request[​](#request "Request에 대한 직접 링크") ## Responsesapplication/json[​](#responses "responses에 대한 직접 링크") * 200 * 400 * 401 * 403 * 404 설정 결과 Bad Request Unauthorized Forbidden Not Found --- # 숙소 수정 ``` PATCH /gds/vendor/properties/:vendor_property_id ``` * 숙소 콘텐츠와 판매 상태를 수정합니다. * RFC 7396 JSON Merge Patch를 따릅니다. 생략한 필드는 기존값이 유지되고, `null`을 보내면 해당 값이 초기화됩니다. * 판매 중지·재개도 이 API로 처리합니다. `status`만 담아 보내면 나머지 콘텐츠는 그대로 유지됩니다. * `settings.extra_adult_price`에 `null`을 보내면 숙소 기본 추가 성인요금이 미설정으로 돌아갑니다. * 경로의 `vendor_property_id`와 본문의 식별자가 어긋나면 `400`이 반환됩니다. ## Request[​](#request "Request에 대한 직접 링크") ## Responsesapplication/json[​](#responses "responses에 대한 직접 링크") * 200 * 400 * 401 * 403 * 404 * 409 수정 결과 Bad Request (식별자 path/body 불일치 등) Unauthorized Forbidden Not Found Conflict (이미 존재하는 id) --- # 숙소 채널 설정 저장 ``` PATCH /gds/vendor/properties/:vendor_property_id/channels/:channel_id/settings ``` RFC 7396 JSON Merge Patch. null 인 경우 해당 키를 삭제합니다. ## Request[​](#request "Request에 대한 직접 링크") ## Responsesapplication/json[​](#responses "responses에 대한 직접 링크") * 200 * 400 * 401 * 403 * 404 * 500 채널 설정 저장 성공. 저장 후의 전체 설정 반환. Bad Request Unauthorized Forbidden Not Found Internal Server Error --- # 숙소 매핑 수정 ``` PATCH /gds/vendor/properties/:vendor_property_id/channels/:channel_id/mappings ``` * 숙소와 채널 사이의 매핑을 수정합니다. * `channel_property_id`에 채널 측 숙소 ID를 넣어 연결하고, `status`로 매핑을 켜고 끕니다. * `null`을 보내면 매핑이 초기화되고, 생략하면 기존 값이 유지됩니다. 매핑 삭제용 `DELETE`가 따로 없으므로 판매를 중지할 때도 `null`을 사용합니다. * 직연동 채널에서만 수정할 수 있습니다. ## Request[​](#request "Request에 대한 직접 링크") ## Responsesapplication/json[​](#responses "responses에 대한 직접 링크") * 200 * 400 * 401 * 403 * 404 * 500 숙소 매핑 수정 성공 Bad Request Unauthorized Forbidden Not Found Internal Server Error --- # 요금제 수정 ``` PATCH /gds/vendor/properties/:vendor_property_id/roomtypes/:vendor_roomtype_id/rateplans/:vendor_rateplan_id ``` * 요금제의 판매 상태를 수정합니다. * RFC 7396 JSON Merge Patch를 따릅니다. 생략한 필드는 기존값이 유지됩니다. * 판매 조건(판매 기간·숙박일수·환불 여부 등)은 요금제가 아니라 결합된 요금제 모델에서 관리하므로, 조건을 바꾸려면 요금제 모델 수정을 사용하세요. * 경로의 식별자와 본문의 식별자가 어긋나면 `400`이 반환됩니다. ## Request[​](#request "Request에 대한 직접 링크") ## Responsesapplication/json[​](#responses "responses에 대한 직접 링크") * 200 * 400 * 401 * 403 * 404 * 409 수정 결과 Bad Request (식별자 path/body 불일치 등) Unauthorized Forbidden Not Found Conflict (이미 존재하는 id) --- # 요금제 매핑 수정 ``` PATCH /gds/vendor/properties/:vendor_property_id/roomtypes/:vendor_roomtype_id/rateplans/:vendor_rateplan_id/channels/:channel_id/mappings ``` * 요금제와 채널 요금제 사이의 매핑을 수정합니다. * `channel_rateplan_id`에 채널 측 요금제 ID를 넣어 연결하고, `status`로 매핑을 켜고 끕니다. * `null`을 보내면 매핑이 초기화되고, 생략하면 기존 값이 유지됩니다. * 요금제 개념이 없는 채널에서는 `0`으로 매핑합니다. * 숙소·객실 매핑을 먼저 끝내야 하며, 직연동 채널에서만 수정할 수 있습니다. ## Request[​](#request "Request에 대한 직접 링크") ## Responsesapplication/json[​](#responses "responses에 대한 직접 링크") * 200 * 400 * 401 * 403 * 404 * 500 요금제 매핑 수정 성공 Bad Request Unauthorized Forbidden Not Found Internal Server Error --- # 요금제 모델 수정 ``` PATCH /gds/vendor/properties/:vendor_property_id/rateplan-models/:vendor_rateplan_model_id ``` * 요금제 모델의 판매 조건을 수정합니다. 이 모델을 참조하는 모든 요금제에 함께 적용됩니다. * RFC 7396 JSON Merge Patch를 따르며, `i18n`은 수정 요청에도 필요합니다. * `channels`를 수정하면 요금제 매핑이 달라집니다. 채널을 추가하면 추가된 채널에만 매핑이 새로 생기고, 채널을 빼도 이미 만들어진 매핑은 삭제되지 않습니다. 빈 배열로 두면 생성 가능한 모든 채널에 매핑이 만들어집니다. * `sale_from`과 `sale_to`는 두 값을 모두 보내거나 모두 생략해야 합니다. * 참조나 불변식을 위반하면 `422`가 반환됩니다. ## Request[​](#request "Request에 대한 직접 링크") ## Responsesapplication/json[​](#responses "responses에 대한 직접 링크") * 200 * 400 * 401 * 403 * 404 * 409 * 422 수정 결과 Bad Request (식별자 path/body 불일치 등) Unauthorized Forbidden Not Found Conflict (이미 존재하는 id) Unprocessable Entity (참조/invariant 위반) --- # 객실타입 수정 ``` PATCH /gds/vendor/properties/:vendor_property_id/roomtypes/:vendor_roomtype_id ``` * 객실타입 콘텐츠와 판매 상태를 수정합니다. * RFC 7396 JSON Merge Patch를 따릅니다. 생략한 필드는 기존값이 유지되고, `null`을 보내면 해당 값이 초기화됩니다. * 판매 중지·재개도 이 API로 처리합니다. `status`만 담아 보내면 나머지 콘텐츠는 그대로 유지됩니다. * 경로의 식별자와 본문의 식별자가 어긋나면 `400`이 반환됩니다. ## Request[​](#request "Request에 대한 직접 링크") ## Responsesapplication/json[​](#responses "responses에 대한 직접 링크") * 200 * 400 * 401 * 403 * 404 * 409 수정 결과 Bad Request (식별자 path/body 불일치 등) Unauthorized Forbidden Not Found Conflict (이미 존재하는 id) --- # 객실 채널 설정 저장 ``` PATCH /gds/vendor/properties/:vendor_property_id/roomtypes/:vendor_roomtype_id/channels/:channel_id/settings ``` RFC 7396 JSON Merge Patch. null 인 경우 해당 키를 삭제합니다. ## Request[​](#request "Request에 대한 직접 링크") ## Responsesapplication/json[​](#responses "responses에 대한 직접 링크") * 200 * 400 * 401 * 403 * 404 * 500 객실 채널 설정 저장 성공. 저장 후의 전체 설정 반환. Bad Request Unauthorized Forbidden Not Found Internal Server Error --- # 객실 매핑 수정 ``` PATCH /gds/vendor/properties/:vendor_property_id/roomtypes/:vendor_roomtype_id/channels/:channel_id/mappings ``` * 객실타입과 채널 객실 사이의 매핑을 수정합니다. * `channel_roomtype_id`에 채널 측 객실 ID를 넣어 연결하고, `status`로 매핑을 켜고 끕니다. * `null`을 보내면 매핑이 초기화되고, 생략하면 기존 값이 유지됩니다. * 숙소 매핑을 먼저 끝내야 하며, 직연동 채널에서만 수정할 수 있습니다. ## Request[​](#request "Request에 대한 직접 링크") ## Responsesapplication/json[​](#responses "responses에 대한 직접 링크") * 200 * 400 * 401 * 403 * 404 * 500 객실 매핑 수정 성공 Bad Request Unauthorized Forbidden Not Found Internal Server Error --- # Vendor API 3.0 ONDA Vendor API 3.0은 공급사(Vendor)와 ONDA 플랫폼을 연동하는 RESTful API입니다. 공급사는 숙소·객실·요금제 콘텐츠와 요금·재고를 ONDA로 전송하고, ONDA는 OTA 채널에서 발생한 예약을 공급사로 전달합니다. 1.5 버전을 쓰고 계신가요? 기존 [Vendor API 1.5](/docs/api/vendor/vendor-api)는 계속 지원됩니다. 신규 연동은 3.0을 사용하세요. ## 연동의 두 방향[​](#연동의-두-방향 "연동의 두 방향에 대한 직접 링크") 3.0에서 가장 먼저 이해해야 할 것은 **API 호출 방향**입니다. 공급사는 클라이언트이면서 동시에 서버입니다. | 구분 | 방향 | 경로 패턴 | 공급사의 역할 | | -------------- | ------------- | ----------------- | ------------------------------------------ | | **HUB API** | 공급사 → ONDA | `/gds/vendor/...` | **클라이언트** — ONDA API를 호출 | | **공급사 API** | ONDA → 공급사 | `/bookings` 등 | **서버** — ONDA가 호출할 엔드포인트를 제공 | ## 채널 유형[​](#채널-유형 "채널 유형에 대한 직접 링크") 판매 채널은 **플러스 채널**(`channel_type=hub`)과 **직연동 채널**(`channel_type=cms`)로 나뉩니다. 플러스 채널은 계약·입점·정산까지 ONDA가 대행하고, 직연동 채널은 숙소가 OTA와 직접 계약해 운영합니다. 요금·재고 동기화는 두 유형 모두 ONDA를 거칩니다. 이 구분에 따라 채널 오픈 절차와 예약 처리 방식이 달라집니다. 자세한 비교는 [공통 · 개요](/docs/api/vendor-v3/guides/overview#%EC%B1%84%EB%84%90-%EC%9C%A0%ED%98%95--%ED%94%8C%EB%9F%AC%EC%8A%A4%EC%99%80-%EC%A7%81%EC%97%B0%EB%8F%99)를 참고하세요. ## 1.5에서 달라진 점[​](#15에서-달라진-점 "1.5에서 달라진 점에 대한 직접 링크") * **콘텐츠 방향 반전** — ONDA가 `GET`으로 가져가던 방식에서, 공급사가 `POST`·`PATCH`로 **직접 전송**하는 방식으로 바뀌었습니다. * **요금제 모델 신설** — 요금제는 `객실 × 요금제 모델`의 결합으로 정의됩니다. * **요금재고 전송 분리** — 요금·영업일은 `POST .../ari`, 재고는 `POST .../ari/avails`로 나뉩니다. * **채널 API 추가** — 채널 탐색·오픈 신청·설정·매핑을 API로 처리합니다. ## 콘텐츠 4분류[​](#콘텐츠-4분류 "콘텐츠 4분류에 대한 직접 링크") | 분류 | 생성 | 수정 | | ----------- | --------------------------------------------------- | ------------------------------------------------------ | | 숙소 | `POST /gds/vendor/properties` | `PATCH /gds/vendor/properties/{vendor_property_id}` | | 객실타입 | `POST .../{vendor_property_id}/roomtypes` | `PATCH .../roomtypes/{vendor_roomtype_id}` | | 요금제 모델 | `POST .../{vendor_property_id}/rateplan-models` | `PATCH .../rateplan-models/{vendor_rateplan_model_id}` | | 요금제 | `POST .../roomtypes/{vendor_roomtype_id}/rateplans` | `PATCH .../rateplans/{vendor_rateplan_id}` | ## 인증[​](#인증 "인증에 대한 직접 링크") HUB API 호출 시 `Authorization` 헤더에 발급받은 Vendor access token을 담습니다. ``` GET /gds/vendor/meta HTTP/1.1 Authorization: {vendor_access_token} ``` ### 베이스 URL[​](#베이스-url "베이스 URL에 대한 직접 링크") | 환경 | URL | | ----------- | ------------------------------- | | 개발(alpha) | `https://vendor.dapi.tport.dev` | | 운영 | 연동 계약 후 ONDA 담당자가 안내 | 토큰은 연동 계약 후 ONDA 담당자가 발급합니다. 공급사 API는 반대로 **공급사가 인증을 검증하는 쪽**입니다. ONDA 요청에 대한 토큰·서명 검증 로직을 구현해야 합니다. ## 공통 규칙[​](#공통-규칙 "공통 규칙에 대한 직접 링크") * 생성 `POST` · 수정 `PATCH` · 조회 `GET`, 성공 응답은 `200 OK` * `PATCH`는 RFC 7396 Merge Patch를 따릅니다. 생략한 필드는 기존값이 유지됩니다. * 요청·응답 본문은 JSON입니다. * 날짜·시각은 ISO 8601을 사용합니다. (예: `2026-01-20T15:00:00+09:00`) ## 시작하기[​](#시작하기 "시작하기에 대한 직접 링크") 1. **파트너십 협약** — ONDA 사업팀과 연동 계약 체결 2. **인증 정보 발급** — 스테이징·운영 환경 access token 및 베이스 URL 수령 3. **[연동 가이드](/docs/api/vendor-v3/guides/overview) 검토** — 준비부터 채널 오픈, 예약 운영까지 순서대로 정리돼 있습니다 4. **코드 카탈로그 조회** — [`GET /gds/vendor/meta`](/docs/api/vendor-v3/get-meta-codes)로 코드 값을 내려받아 매핑 테이블 구성 5. **스테이징 검증 후 운영 전환** *** 연동 순서대로 따라가려면 [연동 가이드](/docs/api/vendor-v3/guides/overview)부터 확인하세요. 엔드포인트별 상세 스펙은 API 레퍼런스에 있습니다. --- # 예약 취소 ``` POST /bookings/:vendor_booking_number/cancel ``` * 이 엔드포인트는 공급사가 구현하고 ONDA가 호출합니다. * ONDA에서 공급사 예약 취소를 요청합니다. * 공급사는 취소 사유(memo)를 함께 전달받습니다. ## Request[​](#request "Request에 대한 직접 링크") ## Responsesapplication/json[​](#responses "responses에 대한 직접 링크") * 200 * 400 * 403 * 404 * 409 * 500 예약 취소 요청 성공 Validation Error Access Denied Reservation not found Business Error System Error --- # 예약 확정 ``` PUT /bookings/:vendor_booking_number/confirm ``` * 이 엔드포인트는 공급사가 구현하고 ONDA가 호출합니다. * ONDA에서 공급사 예약 확정을 요청합니다. * 공급사에는 결제 금액(paid\_amount)을 전달하지 않습니다. * 확정할 예약은 경로의 `vendor_booking_number`로 특정합니다. 본문의 `property_id`·`roomtype_id`는 참고용이라 전달되지 않을 수 있으니, 이 값에 의존해 예약을 찾지 마세요. `rateplan_id`는 항상 전달됩니다. ## Request[​](#request "Request에 대한 직접 링크") ## Responsesapplication/json[​](#responses "responses에 대한 직접 링크") * 200 * 400 * 403 * 404 * 409 * 500 예약 확정 요청 성공 Validation Error Access Denied Reservation not found Business Error System Error --- # 예약 생성 ``` POST /bookings ``` * 이 엔드포인트는 공급사가 구현하고 ONDA가 호출합니다. * ONDA에서 공급사 예약 생성을 요청합니다. ## Request[​](#request "Request에 대한 직접 링크") ## Responsesapplication/json[​](#responses "responses에 대한 직접 링크") * 200 * 400 * 403 * 404 * 409 * 500 예약 생성 요청 성공 Validation Error Access Denied Reservation not found Business Error System Error --- # 취소/환불 정책 조회 ``` GET /properties/:vendor_property_id/roomtypes/:vendor_roomtype_id/rateplans/:vendor_rateplan_id/refund_policy ``` * 이 엔드포인트는 공급사가 구현하고 ONDA가 호출합니다. * ONDA에서 공급사 취소/환불 정책을 조회합니다. ## Request[​](#request "Request에 대한 직접 링크") ## Responsesapplication/json[​](#responses "responses에 대한 직접 링크") * 200 * 400 * 403 * 500 취소/환불 정책 조회 성공 Validation Error Access Denied System Error --- # 예약 변경 ``` PUT /bookings/:vendor_booking_number/modify ``` * 이 엔드포인트는 공급사가 구현하고 ONDA가 호출합니다. * ONDA에서 공급사 예약 변경을 요청합니다. ## Request[​](#request "Request에 대한 직접 링크") ## Responsesapplication/json[​](#responses "responses에 대한 직접 링크") * 200 * 400 * 403 * 404 * 409 * 500 예약 변경 요청 성공 Validation Error Access Denied Reservation not found Business Error System Error --- # 기본 연동 --- # Cancel Reservation ``` POST /bookings/:vendor_booking_number/cancel ``` * 온다 > 공급사 (온다가 공급사를 호출해 저장합니다.) * 판매 채널에서 예약 취소 발생 시, 공급사로 예약 취소를 호출합니다. * Create Reservation 또는 Confirm Reservation 진행 후 호출 합니다. ## Request[​](#request "Request에 대한 직접 링크") ## Responsesapplication/json[​](#responses "responses에 대한 직접 링크") * 200 * 400 * 403 * 409 * 500 Validation Error Access Denied Business Error System Error --- # Cancellation & Refund Policy before reservation ``` GET /properties/:vendor_property_id/roomtypes/:vendor_roomtype_id/rateplans/:vendor_rateplan_id/refund_policy ``` * 온다 > 공급사 (온다가 공급사를 호출해 저장합니다.) * 판매 채널에서 예약 발생시, 예약 전 공급사로 요금제의 환불 정책과 체크인/체크아웃 시간을 불러옵니다. ## Request[​](#request "Request에 대한 직접 링크") ## Responsesapplication/json[​](#responses "responses에 대한 직접 링크") * 200 * 400 * 403 * 500 Validation Error Access Denied System Error --- # Check Reservation ``` GET /bookings/:vendor_booking_number ``` * 온다 > 공급사 (온다가 공급사를 호출해 저장합니다.) * 공급사에 생성된 예약을 조회합니다. ## Request[​](#request "Request에 대한 직접 링크") ## Responsesapplication/json[​](#responses "responses에 대한 직접 링크") * 200 * 400 * 403 * 404 * 500 Validation Error Access Denied Not Found System Error --- # Confirm Reservation ``` PUT /bookings/:vendor_booking_number/confirm ``` * 온다 > 공급사 (온다가 공급사를 호출해 저장합니다.) * ONDA Hub에 생성한 pending 예약을 확정 하기 위해 공급사를 호출합니다. * 해당 시점에서 업체 및 고객 모두 예약을 인지 할 수 있습니다. * pending예약 요청 이후 약 15분 동안 Confirm Reservation API 까지 예약 확정이 이루어지지 않을 경우, ONDA Hub에서 해당 예약은 취소 됩니다. ## Request[​](#request "Request에 대한 직접 링크") ## Responsesapplication/json[​](#responses "responses에 대한 직접 링크") * 200 * 400 * 403 * 409 * 500 Validation Error Access Denied Business Error System Error --- # Create Reservation ``` POST /bookings ``` * 온다 > 공급사 (온다가 공급사를 호출해 저장합니다.) * 대기 예약이 아닌, 실제 재고를 차감하여 예약을 생성합니다. * 예약이 확정 되기 전 재고를 확보하기 위해 호출 합니다. * 공급사로 부터 Create Reservation API를 통한 pending 예약의 응답을 약 15분간 받지 못 할 경우, ONDA Hub에서 해당 예약은 취소됩니다. ## Request[​](#request "Request에 대한 직접 링크") ## Responsesapplication/json[​](#responses "responses에 대한 직접 링크") * 200 * 400 * 403 * 409 * 500 Validation Error Access Denied Business Error System Error --- # 에러 코드 ## 개요[​](#개요 "개요에 대한 직접 링크") 공급사(Vendor)는 온다(ONDA Hub)로부터 API 요청을 받았을 때 처리에 실패하거나 비즈니스 로직 상 오류가 발생한 경우, 표준 에러 응답 포맷을 사용해 응답해야 합니다. 온다는 공급사의 에러 응답을 수신하여 `code` 필드를 기반으로 표준 에러 코드로 분류하고, 예약 처리 결과에 반영합니다. *** ## 에러 응답 포맷[​](#에러-응답-포맷 "에러 응답 포맷에 대한 직접 링크") 공급사는 아래 JSON 포맷으로 에러를 응답해야 합니다. ``` { "code": "4000", "error": "No rooms available for booking" } ``` | 필드 | 타입 | 필수 | 설명 | | ------- | ------ | -------- | ----------------------------------------------------- | | `code` | string | **필수** | 아래 에러 코드 목록에 정의된 숫자 코드 (예: `"4000"`) | | `error` | string | **필수** | 아래 목록에 정의된 영문 에러 메시지 | *** ## 에러 코드 목록[​](#에러-코드-목록 "에러 코드 목록에 대한 직접 링크") ### SYSTEM\_ERROR — 시스템 오류[​](#system_error--시스템-오류 "SYSTEM_ERROR — 시스템 오류에 대한 직접 링크") | code | error | HTTP | 설명 | | ------ | -------------------------------------------- | ---- | ---------------------------------- | | `1000` | `An error occurred during system processing` | 500 | 시스템 처리 중 오류가 발생했습니다 | ### AUTH\_ERROR — 인증/권한 오류[​](#auth_error--인증권한-오류 "AUTH_ERROR — 인증/권한 오류에 대한 직접 링크") | code | error | HTTP | 설명 | | ------ | --------------- | ---- | -------------------- | | `2000` | `Access denied` | 403 | 접근 권한이 없습니다 | ### VALIDATION\_ERROR — 입력값 오류[​](#validation_error--입력값-오류 "VALIDATION_ERROR — 입력값 오류에 대한 직접 링크") | code | error | HTTP | 설명 | | ------ | ------------------------------------- | ---- | ------------------------ | | `3000` | `Please check your input information` | 400 | 입력 정보를 확인해주세요 | ### BUSINESS\_ERROR — 비즈니스 로직 오류[​](#business_error--비즈니스-로직-오류 "BUSINESS_ERROR — 비즈니스 로직 오류에 대한 직접 링크") 가장 중요한 에러 코드 BUSINESS\_ERROR는 예약 생성·확정·취소·조회 과정에서 발생하는 핵심 에러입니다. 공급사는 반드시 해당 상황에 맞는 코드를 정확히 반환해야 하며, 잘못된 코드 또는 누락 시 온다 시스템이 예약 처리를 올바르게 수행할 수 없습니다. | code | error | HTTP | 설명 | | ------ | --------------------------------------------- | ---- | ---------------------------------------------------------------------------------------------- | | `4000` | `No rooms available for booking` | 409 | 예약 가능한 객실이 없습니다 ([Create Reservation](/docs/api/vendor/create-reservation)) | | `4001` | `Requested amount differs from actual amount` | 409 | 요청 금액과 실제 금액이 다릅니다 ([Create Reservation](/docs/api/vendor/create-reservation)) | | `4002` | `Minimum guest requirement not met` | 409 | 최소 예약 인원을 충족하지 않습니다 ([Create Reservation](/docs/api/vendor/create-reservation)) | | `4003` | `Maximum guest capacity exceeded` | 409 | 예약 가능 인원을 초과했습니다 ([Create Reservation](/docs/api/vendor/create-reservation)) | | `4004` | `Reservation not found` | 404 | 해당 예약을 찾을 수 없습니다 ([Check Reservation](/docs/api/vendor/check-reservation)) | | `4005` | `Reservation already cancelled` | 409 | 이미 취소된 예약입니다 ([Cancel Reservation](/docs/api/vendor/cancel-reservation)) | | `4006` | `Reservation cannot be cancelled` | 409 | 예약 취소가 불가능한 상태입니다 ([Cancel Reservation](/docs/api/vendor/cancel-reservation)) | | `4007` | `Reservation cannot be confirmed` | 409 | 예약 확정이 불가능한 상태입니다 ([Confirm Reservation](/docs/api/vendor/confirm-reservation)) | ### UNKNOWN\_ERROR — 알 수 없는 오류[​](#unknown_error--알-수-없는-오류 "UNKNOWN_ERROR — 알 수 없는 오류에 대한 직접 링크") | code | error | HTTP | 설명 | | ------ | --------------------------- | ---- | ------------------------------ | | `9999` | `An unknown error occurred` | 500 | 알 수 없는 오류가 발생했습니다 | *** ## 주의사항[​](#주의사항 "주의사항에 대한 직접 링크") * **`code` 필드 우선 사용**: `code` 필드가 포함된 경우 온다는 해당 코드를 우선 사용합니다. `code`가 없거나 알 수 없는 값인 경우 `error` 메시지를 패턴 매칭으로 분류합니다. * **`error` 필드는 위 목록의 영문 메시지를 사용**해야 합니다. 임의의 문자열을 사용할 경우 온다가 에러를 올바르게 분류하지 못할 수 있습니다. * **정의되지 않은 코드**: 위 목록에 없는 코드가 포함된 경우, 온다는 HTTP 상태코드 기반으로 에러를 분류하거나 `9999 (UNKNOWN_ERROR)`로 처리합니다. --- # Get Avails ``` GET /properties/:vendor_property_id/roomtypes/:vendor_roomtype_id/rateplans/:vendor_rateplan_id/avails ``` * 온다 > 공급사 (온다가 공급사를 호출해 저장합니다.) * 요금제의 일자별 재고를 불러옵니다. ## Request[​](#request "Request에 대한 직접 링크") ## Responsesapplication/json[​](#responses "responses에 대한 직접 링크") * 200 * 400 * 403 * 500 Validation Error Access Denied System Error --- # Get Property List (HotelPlus) ``` GET /properties ``` * 공급사 > 온다 (공급사가 온다를 호출해 저장합니다.) * 호텔플러스에 만든 숙소를 공급사 PMS, CMS 등에서 맵핑하기 위해 제공 된 API 입니다. * 공급사 PMS, CMS에서 호텔플러스의 숙소 목록을 응답받습니다. * 이때 응답받는 숙소 아이디는 온다의 숙소 아이디입니다. * 공급사에서는 온다의 숙소 아이디와 동일하게 공급사 숙소 아이디를 설정 해주셔야합니다. ## Request[​](#request "Request에 대한 직접 링크") ## Responsesapplication/json[​](#responses "responses에 대한 직접 링크") * 200 * 400 --- # Get Rates ``` GET /properties/:vendor_property_id/roomtypes/:vendor_roomtype_id/rateplans/:vendor_rateplan_id/rates ``` * 온다 > 공급사 (온다가 공급사를 호출해 저장합니다.) * 요금제의 일자별 가격을 불러옵니다. ## Request[​](#request "Request에 대한 직접 링크") ## Responsesapplication/json[​](#responses "responses에 대한 직접 링크") * 200 * 400 * 403 * 500 Validation Error Access Denied System Error --- # Get Roomtype List (HotelPlus) ``` GET /properties/:vendor_property_id/roomtypes ``` * 공급사 > 온다 (공급사가 온다를 호출해 저장합니다.) * 호텔플러스에 만든 숙소를 공급사 PMS, CMS 등에서 맵핑하기 위해 제공 된 API 입니다. * 공급사 PMS, CMS에서 호텔플러스의 숙소 목록을 응답받습니다. * 이때 응답받는 숙소 아이디는 온다의 숙소 아이디입니다. * 공급사에서는 온다의 숙소 아이디와 동일하게 공급사 숙소 아이디를 설정 해주셔야합니다. ## Request[​](#request "Request에 대한 직접 링크") ## Responsesapplication/json[​](#responses "responses에 대한 직접 링크") * 200 * 400 --- # Get Updated Avails ``` GET /sync/avails ``` * dapi.tport.dev -> 공급사가 지정한 url 위치 입니다. * 온다 > 공급사 (온다가 공급사를 호출해 저장합니다.) * lastdate 부터 호출 시점까지 재고 수가 변경 된 요금제 목록을 불러옵니다. * 정해진 주기별로 호출하며, 주기는 온다 기술 담당 매니저와 협의가 필요합니다. (기본 연동 방식 - 숙소 관리 참고) ## Request[​](#request "Request에 대한 직접 링크") ## Responsesapplication/json[​](#responses "responses에 대한 직접 링크") * 200 * 400 * 403 * 500 Validation Error Access Denied System Error --- # Get Updated Rates ``` GET /sync/rates ``` * dapi.tport.dev -> 공급사가 지정한 url 위치 입니다. * 온다 > 공급사 (온다가 공급사를 호출해 저장합니다.) * lastdate 부터 호출 시점까지 가격이 변경 된 요금제 목록을 불러옵니다. * 정해진 주기별로 호출하며, 주기는 온다 기술 담당 매니저와 협의가 필요합니다. (기본 연동 방식 - 숙소 관리 참고) ## Request[​](#request "Request에 대한 직접 링크") ## Responsesapplication/json[​](#responses "responses에 대한 직접 링크") * 200 * 400 * 403 * 500 Validation Error Access Denied System Error --- # Modify Reservation ``` PUT /bookings/:vendor_booking_number/modify ``` * 온다 > 공급사 (온다가 공급사를 호출해 저장합니다.) * 판매 채널에서 고객 예약정보 변경 시, 공급사로 예약 정보 수정을 호출합니다. ## Request[​](#request "Request에 대한 직접 링크") ## Responsesapplication/json[​](#responses "responses에 대한 직접 링크") * 200 * 400 * 403 * 500 Validation Error Access Denied System Error --- # ONDA → Vendor Request 온다에서 벤더(숙박업체) 시스템으로 데이터를 요청하는 Pull 방식의 연동 가이드입니다. ## 개요[​](#개요 "개요에 대한 직접 링크") ONDA → Vendor Request 방식은 온다 시스템이 벤더의 API를 직접 호출하여 최신 정보를 획득하는 연동 방식입니다. ### 특징[​](#특징 "특징에 대한 직접 링크") * **실시간 데이터 획득**: 온다가 필요한 시점에 벤더 시스템에서 최신 데이터 조회 * **Pull 방식**: 온다가 능동적으로 데이터를 요청 * **즉시성**: 실시간으로 최신 정보 확인 가능 * **신뢰성**: 벤더 시스템을 직접 조회하여 정확한 정보 획득 ## 연동 흐름[​](#연동-흐름 "연동 흐름에 대한 직접 링크") ## 주요 API 엔드포인트[​](#주요-api-엔드포인트 "주요 API 엔드포인트에 대한 직접 링크") 벤더 시스템(공급사가 직접 구축·호스팅하는 서버)에서 구현해야 하는 API들입니다. 스펙상 서버 주소는 `https://vendor.dapi.tport.dev`로 표기되어 있으나, 이는 실제로는 **공급사가 지정한 자체 서버 URL을 나타내는 placeholder**입니다. 상세 파라미터와 스키마는 각 링크의 API 레퍼런스에서 확인할 수 있습니다. ### 숙소 생성 API[​](#숙소-생성-api "숙소 생성 API에 대한 직접 링크") | Method | Endpoint | 설명 | | ------ | ------------------------------------------------------------------------------------- | -------------------------- | | GET | [`/properties`](/docs/api/vendor/vendor-property-list) | 공급사 전체 숙소 목록 조회 | | GET | [`/properties/{vendor_property_id}`](/docs/api/vendor/vendor-property-detail) | 숙소 상세 정보 조회 | | GET | [`/properties/{vendor_property_id}/roomtypes`](/docs/api/vendor/vendor-roomtype-list) | 객실 목록 조회 | | GET | [`.../roomtypes/{vendor_roomtype_id}`](/docs/api/vendor/vendor-roomtype-detail) | 객실 상세(+요금제) 조회 | | GET | [`.../rateplans/{vendor_rateplan_id}/avails`](/docs/api/vendor/get-avails) | 일자별 재고 조회 | | GET | [`.../rateplans/{vendor_rateplan_id}/rates`](/docs/api/vendor/get-rates) | 일자별 요금 조회 | ### 숙소 정보 관리 (Sync) API[​](#숙소-정보-관리-sync-api "숙소 정보 관리 (Sync) API에 대한 직접 링크") `lastdate` 쿼리 파라미터를 기준으로 변경분만 주기적으로 조회합니다. 호출 주기는 온다 기술 담당 매니저와 협의합니다. | Method | Endpoint | 설명 | | ------ | ------------------------------------------------------------------- | --------------------- | | GET | [`/sync/properties`](/docs/api/vendor/vendor-changed-property-list) | 변경된 숙소 목록 조회 | | GET | [`/sync/roomtypes`](/docs/api/vendor/vendor-updated-roomtype-list) | 변경된 객실 목록 조회 | | GET | [`/sync/avails`](/docs/api/vendor/get-updated-avails) | 재고 변경분 조회 | | GET | [`/sync/rates`](/docs/api/vendor/get-updated-rates) | 요금 변경분 조회 | ### 예약 API[​](#예약-api "예약 API에 대한 직접 링크") | Method | Endpoint | 설명 | | ------ | ------------------------------------------------------------------------------------- | --------------------------------------- | | GET | [`.../refund_policy`](/docs/api/vendor/cancellation-refund-policy-before-reservation) | 예약 전 환불 정책 체크 | | POST | [`/bookings`](/docs/api/vendor/create-reservation) | 예약 생성 (재고 확보, `pending` 상태) | | PUT | [`/bookings/{vendor_booking_number}/confirm`](/docs/api/vendor/confirm-reservation) | 예약 확정 (15분 내 미확정 시 자동 취소) | | PUT | [`/bookings/{vendor_booking_number}/modify`](/docs/api/vendor/modify-reservation) | 예약 정보 수정 | | POST | [`/bookings/{vendor_booking_number}/cancel`](/docs/api/vendor/cancel-reservation) | 예약 취소 | | GET | [`/bookings/{vendor_booking_number}`](/docs/api/vendor/check-reservation) | 예약 조회 | ## 인증 및 보안[​](#인증-및-보안 "인증 및 보안에 대한 직접 링크") 이 방향(ONDA → Vendor)의 API는 벤더가 자체적으로 구축·호스팅하는 서버에서 동작하므로, 인증 방식이 스펙에 고정되어 있지 않습니다. 벤더 시스템의 인증 방식(API Key, IP 화이트리스트 등)은 온다 기술 담당 매니저와 협의하여 결정합니다. * **HTTPS 필수**: 모든 API 호출은 HTTPS 사용을 권장합니다. ## 응답/에러 포맷[​](#응답에러-포맷 "응답/에러 포맷에 대한 직접 링크") 세 API 모두 공통 `ErrorResponse` 스키마(`{code, error}`)를 사용합니다. | HTTP 상태 | code | 설명 | | --------- | -------------------- | ------------------------------------------------------------- | | 400 | `3000` | Validation Error — 요청 파라미터 확인 필요 | | 403 | `2000` | Access Denied | | 404 | `4004` | Not Found (`check-reservation` 한정) | | 409 | `4000`/`4006`/`4007` | Business Error (예약 API 한정 — 재고 부족, 확정/취소 불가 등) | | 500 | `1000` | System Error | ### 에러 응답 예시[​](#에러-응답-예시 "에러 응답 예시에 대한 직접 링크") ``` { "code": "3000", "error": "Please check your input information" } ``` ## 개발 가이드[​](#개발-가이드 "개발 가이드에 대한 직접 링크") ### 1. API 엔드포인트 구현[​](#1-api-엔드포인트-구현 "1. API 엔드포인트 구현에 대한 직접 링크") 위 엔드포인트 표를 참고하여 벤더 시스템에서 온다가 호출할 API 엔드포인트를 구현해야 합니다. ### 2. 데이터 포맷 준수[​](#2-데이터-포맷-준수 "2. 데이터 포맷 준수에 대한 직접 링크") 온다 시스템과 호환되는 데이터 포맷으로 응답해야 합니다. ### 3. 에러 핸들링[​](#3-에러-핸들링 "3. 에러 핸들링에 대한 직접 링크") 적절한 HTTP 상태 코드와 에러 메시지를 제공해야 합니다. ### 4. 성능 최적화[​](#4-성능-최적화 "4. 성능 최적화에 대한 직접 링크") * 응답 시간 최소화 (권장: 3초 이내) * 캐싱 활용으로 성능 향상 * 대용량 데이터의 경우 페이징 처리 ## 테스트 가이드[​](#테스트-가이드 "테스트 가이드에 대한 직접 링크") ### 1. 개발 환경 테스트[​](#1-개발-환경-테스트 "1. 개발 환경 테스트에 대한 직접 링크") * 온다 테스트 서버에서 벤더 개발 API 호출 * 기본적인 API 응답 확인 * 데이터 포맷 검증 ### 2. 통합 테스트[​](#2-통합-테스트 "2. 통합 테스트에 대한 직접 링크") * 실제 데이터를 사용한 통합 테스트 * 성능 및 안정성 검증 * 에러 시나리오 테스트 ### 3. 운영 전 검증[​](#3-운영-전-검증 "3. 운영 전 검증에 대한 직접 링크") * 운영 환경 설정 확인 * 모니터링 도구 설정 * 장애 대응 절차 확인 ## 모니터링 및 운영[​](#모니터링-및-운영 "모니터링 및 운영에 대한 직접 링크") ### 로그 관리[​](#로그-관리 "로그 관리에 대한 직접 링크") * API 호출 로그 기록 * 에러 로그 모니터링 * 성능 지표 추적 ### 알람 설정[​](#알람-설정 "알람 설정에 대한 직접 링크") * API 응답 시간 지연 알람 * 에러율 증가 알람 * 시스템 장애 알람 *** 다음: [Vendor → ONDA Request](/docs/api/vendor/vendor-to-onda-request) 방식 가이드 --- # 숙소 콘텐츠 특수기호 제한 **숙소소개**, **예약안내**, **공지사항**, **취소환불 규정 안내** 작성시 아래 기호만 작성 가능합니다. `! @ # $ % ^ & * ( ) { } [ ] " ' , . ? / |` ## 콘텐츠 작성 가이드[​](#콘텐츠-작성-가이드 "콘텐츠 작성 가이드에 대한 직접 링크") ### 숙소명[​](#숙소명 "숙소명에 대한 직접 링크") * ✅ 지역명 + 숙소명 **+** 숙소분류 (예시 : 춘천 온다 펜션) * ✅ 18자 이내, 특수기호 허용 불가 ### 숙소소개[​](#숙소소개 "숙소소개에 대한 직접 링크") * ✅ 필수값으로 자세한 정보를 입력해주세요. ### 예약안내[​](#예약안내 "예약안내에 대한 직접 링크") * ✅ 필수값으로 자세한 정보를 입력해주세요. ### 공지사항[​](#공지사항 "공지사항에 대한 직접 링크") * ✅ 해당 항목은 티몬 채널에만 노출됩니다. ### 취소환불 규정 안내[​](#취소환불-규정-안내 "취소환불 규정 안내에 대한 직접 링크") * ✅ 전액 환불 구간은 필수로 설정해야 입점 가능 합니다. --- # 숙소 생성 공급사의 숙소 정보를 받아 온다에 숙소를 생성합니다. 온다가 공급사를 호출해 저장합니다. 이미지 저작권 및 법적 책임 공급사에서 ONDA로 동기화하는 모든 이미지는 온다에 저장되며, 법적 또는 저작권에 문제가 없어야 합니다. 또한, 숙소 및 객실 사진에 인물이 있을 경우 일부 채널에 입점 불가합니다. ## 숙소 생성 프로세스[​](#숙소-생성-프로세스 "숙소 생성 프로세스에 대한 직접 링크") 숙소를 생성하기 위해서는 다음 순서대로 정보를 제공해야 합니다: ### 1. 숙소 불러오기[​](#1-숙소-불러오기 "1. 숙소 불러오기에 대한 직접 링크")
| API | Method | 설명 | | -------------------------------------------------------------- | ------ | ---------------------------- | | [Get Property List](/docs/api/vendor/vendor-property-list) | `GET` | 공급사의 전체 숙소 목록 조회 | | [Get Property Detail](/docs/api/vendor/vendor-property-detail) | `GET` | 특정 숙소의 상세 정보 조회 |
숙소 기본 정보(이름, 주소, 연락처, 편의시설 등)를 온다에 제공합니다. ### 2. 객실 및 요금제 불러오기[​](#2-객실-및-요금제-불러오기 "2. 객실 및 요금제 불러오기에 대한 직접 링크")
| API | Method | 설명 | | -------------------------------------------------------------- | ------ | -------------------------- | | [Get Roomtype List](/docs/api/vendor/vendor-roomtype-list) | `GET` | 숙소의 객실 타입 목록 조회 | | [Get Roomtype Detail](/docs/api/vendor/vendor-roomtype-detail) | `GET` | 특정 객실의 상세 정보 조회 |
객실 타입별 정보(객실명, 최대 인원, 침대 정보, 편의시설 등)와 요금제를 제공합니다. ### 3. 재고 / 가격 불러오기[​](#3-재고--가격-불러오기 "3. 재고 / 가격 불러오기에 대한 직접 링크")
| API | Method | 설명 | | ----------------------------------------- | ------ | --------------------------------- | | [Get Avails](/docs/api/vendor/get-avails) | `GET` | 객실의 예약 가능한 재고 정보 조회 | | [Get Rates](/docs/api/vendor/get-rates) | `GET` | 객실의 가격 정보 조회 |
날짜별 재고 수량과 판매 가격 정보를 제공합니다. ## 연동 흐름[​](#연동-흐름 "연동 흐름에 대한 직접 링크") ## 주요 고려사항[​](#주요-고려사항 "주요 고려사항에 대한 직접 링크") ### 필수 정보[​](#필수-정보 "필수 정보에 대한 직접 링크") 숙소 생성을 위해 반드시 제공해야 하는 정보: * **숙소 기본 정보**: 이름, 주소, 연락처, 체크인/체크아웃 시간 * **객실 정보**: 객실명, 기준/최대 인원, 침대 타입 및 개수 * **요금제**: 최소 1개 이상의 판매 가능한 요금제 * **재고**: 판매 가능한 날짜별 재고 수량 * **가격**: 날짜별 판매 가격 ### 이미지 가이드라인[​](#이미지-가이드라인 "이미지 가이드라인에 대한 직접 링크") * 고해상도 이미지 권장 (최소 800x600px) * 지원 형식: JPG, PNG * 숙소 대표 이미지 최소 10장 이상 권장 * 객실당 이미지 최소 5장 이상 권장 * **인물이 포함된 사진 지양** (일부 채널 입점 제한) ### 데이터 정합성[​](#데이터-정합성 "데이터 정합성에 대한 직접 링크") * 공급사 시스템의 실시간 정보와 동기화 * 재고/가격 정보는 최신 상태 유지 필수 * 객실 및 요금제 변경 시 즉시 반영 ## 다음 단계[​](#다음-단계 "다음 단계에 대한 직접 링크") 숙소 생성이 완료되면 [숙소 관리](/docs/api/vendor/property-management)를 통해 정보를 업데이트하고 관리할 수 있습니다. 예약 연동은 [예약 API](/docs/api/vendor/reservation) 문서를 참조하세요. --- # 정보 최신화 공급사에서 변경한 숙소 정보를 온다에 업데이트합니다. 2가지 방식으로 변경된 숙소 정보를 관리할 수 있습니다. **Sync : 온다가 공급사를 호출** * 정해진 시간마다 온다가 공급사를 호출해 변경된 숙소 정보를 온다에 업데이트합니다. 정해진 시간에 맞춰 Sync를 진행하기 때문에 업데이트가 즉시 반영되지 않습니다. **Push : 공급사가 온다를 호출** * 공급사에서 숙소 정보를 변경할 때마다 온다로 변경된 정보를 보내줍니다. * 숙소/객실 및 요금제의 콘텐츠 정보에 비해 상대적으로 변경 빈도가 잦은 숙소/객실 및 요금제의 상태와 재고/요금/영업일은 Push 방식을 함께 연동하는 것을 권장드립니다. *** ## Sync[​](#sync "Sync에 대한 직접 링크") 정해진 시간마다 온다가 공급사를 호출해 주기적으로 Sync를 진행합니다. 주기는 협의를 통해 결정합니다. 예) 일 1회 새벽 5시, 매 시간 30분 마다 등 파라미터의 lastdate를 기준으로 기존 정보와 비교해 변경된 정보만 응답합니다. 정보 변경 판단 field * 상태 정보 : "status" * 콘텐츠 정보 : "status"이외의 모든 값 * 재고/요금 정보: 모든 값 * (영업일 정보 : Push 방식만 사용합니다.) ### 변경 된 숙소 / 객실 및 요금제 상태 & 콘텐츠 불러오기[​](#변경-된-숙소--객실-및-요금제-상태--콘텐츠-불러오기 "변경 된 숙소 / 객실 및 요금제 상태 & 콘텐츠 불러오기에 대한 직접 링크")
| API | Method | 설명 | | -------------------------------------------------------------------------- | ------ | ------------------------------- | | [Get Updated Property List](/docs/api/vendor/vendor-changed-property-list) | `GET` | 변경된 숙소 목록 조회 | | [Get Updated Roomtype List](/docs/api/vendor/vendor-updated-roomtype-list) | `GET` | 변경된 객실 및 요금제 목록 조회 |
### 변경 된 재고 / 요금 / 영업일 불러오기[​](#변경-된-재고--요금--영업일-불러오기 "변경 된 재고 / 요금 / 영업일 불러오기에 대한 직접 링크")
| API | Method | 설명 | | --------------------------------------------------------- | ------ | --------------------- | | [Get Updated Avails](/docs/api/vendor/get-updated-avails) | `GET` | 변경된 재고 정보 조회 | | [Get Updated Rates](/docs/api/vendor/get-updated-rates) | `GET` | 변경된 요금 정보 조회 |
*** ## Push[​](#push "Push에 대한 직접 링크") 공급사에서 숙소 정보를 변경할 때마다 온다로 변경된 정보를 즉시 Push합니다. \*콘텐츠는 Push 방식을 지원하지 않습니다. 동기화 시점까지 기다리지 않고 변경된 정보를 온다에 반영할 수 있습니다. Push 방식을 연동할 경우 Sync 방식보다 예약 실패 발생률을 낮출 수 있습니다. ### 변경 된 숙소 / 객실 / 요금제 상태 전송[​](#변경-된-숙소--객실--요금제-상태-전송 "변경 된 숙소 / 객실 / 요금제 상태 전송에 대한 직접 링크") 참고 사항 숙소 / 객실 / 요금제가 비활성화 혹은 삭제된 경우 응답 값의 status 항목을 모두 disabled로 응답해주세요.
| API | Method | 설명 | | ----------------------------------------------------------------- | ------- | --------------------- | | [Update Property Status](/docs/api/vendor/update-property-status) | `PATCH` | 숙소 상태 변경 전송 | | [Update Roomtype Status](/docs/api/vendor/update-roomtype-status) | `PATCH` | 객실 상태 변경 전송 | | [Update Rateplan Status](/docs/api/vendor/update-rateplan-status) | `PATCH` | 요금제 상태 변경 전송 |
### 변경 된 재고 / 요금 / 영업일 전송[​](#변경-된-재고--요금--영업일-전송 "변경 된 재고 / 요금 / 영업일 전송에 대한 직접 링크")
| API | Method | 설명 | | -------------------------------------------------------------------- | ------ | ---------------- | | [Push Setting Avails](/docs/api/vendor/setting-avails) | `POST` | 재고 정보 전송 | | [Push Setting Rates](/docs/api/vendor/setting-rates) | `POST` | 요금 정보 전송 | | [Push Setting Business-days](/docs/api/vendor/setting-business-days) | `POST` | 영업일 정보 전송 |
--- # 예약 판매 채널을 통해 생성된 예약을 온다가 공급사로 전달합니다. ## 예약 프로세스[​](#예약-프로세스 "예약 프로세스에 대한 직접 링크") ### 예약 확정 프로세스[​](#예약-확정-프로세스 "예약 확정 프로세스에 대한 직접 링크") 예약전 취소환불 규정 정보 확인 → 예약 생성 (pending) → 예약 확정 (confirm → confirmed) ### 예약 취소 프로세스[​](#예약-취소-프로세스 "예약 취소 프로세스에 대한 직접 링크") 예약 취소 (cancel → canceled) ## ONDA Hub의 예약 상태[​](#onda-hub의-예약-상태 "ONDA Hub의 예약 상태에 대한 직접 링크") **예약 확정** * **pending** : 예약 확정전 재고를 확보하기 위해 생성한 예약 상태 * **confirm** : 생성한 예약의 확정을 대기 중인 예약 상태 * **confirmed** : 예약이 확정된 상태 **예약 취소** * **cancel** : 예약의 취소를 대기 중인 예약 상태 * **canceled** : 예약이 취소된 상태 ## 공급사 - ONDA Hub 예약 프로세스[​](#공급사---onda-hub-예약-프로세스 "공급사 - ONDA Hub 예약 프로세스에 대한 직접 링크") ### 예약 생성/확정 프로세스[​](#예약-생성확정-프로세스 "예약 생성/확정 프로세스에 대한 직접 링크") ### 예약 취소 프로세스[​](#예약-취소-프로세스-1 "예약 취소 프로세스에 대한 직접 링크") ## API 목록[​](#api-목록 "API 목록에 대한 직접 링크") ### 예약 전 실제 취소환불규정 정보 확인[​](#예약-전-실제-취소환불규정-정보-확인 "예약 전 실제 취소환불규정 정보 확인에 대한 직접 링크")
| API | Method | 설명 | | ----------------------------------------------------------------------------------------------------------------- | ------ | ---------------------------------------------------------------------------------- | | [Cancellation & Refund Policy before reservation](/docs/api/vendor/cancellation-refund-policy-before-reservation) | `GET` | 실제 예약 시점의 해당 요금제의 취소 & 환불 정보를 확인하여 판매 채널로 내려줍니다. |
### 예약 생성, 확정[​](#예약-생성-확정 "예약 생성, 확정에 대한 직접 링크")
| API | Method | 설명 | | ----------------------------------------------------------- | ------ | ------------------------------- | | [Create Reservation](/docs/api/vendor/create-reservation) | `POST` | 예약 생성 (pending 상태) | | [Confirm Reservation](/docs/api/vendor/confirm-reservation) | `PUT` | 예약 확정 (confirm → confirmed) |
자동 취소 공급사로부터 예약 생성 요청에 대한 실패 응답을 받거나, 15분 동안 응답을 받지 못할 경우 생성된 pending 예약은 자동 취소 됩니다. ### 예약 취소[​](#예약-취소 "예약 취소에 대한 직접 링크")
| API | Method | 설명 | | --------------------------------------------------------- | ------ | ----------------------------- | | [Cancel Reservation](/docs/api/vendor/cancel-reservation) | `POST` | 예약 취소 (cancel → canceled) |
### 예약 조회[​](#예약-조회 "예약 조회에 대한 직접 링크")
| API | Method | 설명 | | ------------------------------------------------------- | ------ | -------------- | | [Check Reservation](/docs/api/vendor/check-reservation) | `GET` | 예약 정보 조회 |
--- # Check Reservation ``` GET /bookings/:vendor_booking_number ``` * 공급사 > 온다 * 공급사가 예약 정보 확인을 위해 ONDA Hub의 예약건들을 호출합니다. * 아고다 예약건 고객 정보 누락 리스트 확인을 위해 사용할 수 있습니다. ## Request[​](#request "Request에 대한 직접 링크") ## Responsesapplication/json[​](#responses "responses에 대한 직접 링크") * 200 * 400 --- # 객실 콘텐츠 특수기호 제한 **객실소개** 작성시 아래 기호만 작성 가능합니다. `! @ # $ % ^ & * ( ) { } [ ] " ' , . ? / |` ## 콘텐츠 작성 가이드[​](#콘텐츠-작성-가이드 "콘텐츠 작성 가이드에 대한 직접 링크") ### 객실명[​](#객실명 "객실명에 대한 직접 링크") * ✅ 18자 이내, 특수기호 허용 불가, `,` `()`만 가능 ### 객실소개[​](#객실소개 "객실소개에 대한 직접 링크") * ✅ 객실마다 인원추가 요금 정보를 필수 기재합니다. * 기준인원 초과시 현장 결제라면 내용 기재해주세요. #### 기준인원 < 최대인원일 경우[​](#기준인원--최대인원일-경우 "기준인원 < 최대인원일 경우에 대한 직접 링크") 인원추가요금 안내 예시 ㅁ 객실 요금은 기준 인원으로 책정된 금액이며, 초과 인원은 추가 금액 발생합니다. ㅁ 기준 인원을 초과하는 경우, 사전에 숙소로 전화 문의 부탁드립니다. ㅁ 정해진 최대 수용 인원(영유아포함) 초과를 엄격히 금하며, 인원 규정 미준수 시 환불없이 강제퇴실 될 수 있습니다. #### 기준인원 = 최대인원일 경우[​](#기준인원--최대인원일-경우-1 "기준인원 = 최대인원일 경우에 대한 직접 링크") 인원추가불가 안내 예시 ㅁ 해당 객실은 기준 인원 외 인원 추가가 불가합니다. --- # Push Setting Avails ``` POST /properties/:vendor_property_id/roomtypes/:vendor_roomtype_id/rateplans/:vendor_rateplan_id/avails ``` * 공급사 > 온다 * 연동 숙소의 요금제의 재고를 즉시 변경합니다. ## Request[​](#request "Request에 대한 직접 링크") ## Responsesapplication/json[​](#responses "responses에 대한 직접 링크") * 200 * 400 --- # Push Setting Business-days ``` POST /properties/:vendor_property_id/roomtypes/:vendor_roomtype_id/rateplans/:vendor_rateplan_id/business-days ``` * 공급사 > 온다 * 연동 숙소의 요금제의 판매 여부를 즉시 변경합니다. ## Request[​](#request "Request에 대한 직접 링크") ## Responsesapplication/json[​](#responses "responses에 대한 직접 링크") * 200 * 400 --- # Push Setting Rates ``` POST /properties/:vendor_property_id/roomtypes/:vendor_roomtype_id/rateplans/:vendor_rateplan_id/rates ``` * 공급사 > 온다 * 연동 숙소의 요금제의 요금을 즉시 변경합니다. ## Request[​](#request "Request에 대한 직접 링크") ## Responsesapplication/json[​](#responses "responses에 대한 직접 링크") * 200 * 400 --- # Reservation Comparison ``` GET /bookings ``` * 공급사 > 온다 * 공급사의 정산 대사를 위해 ONDA Hub의 예약건들을 호출합니다. ## Request[​](#request "Request에 대한 직접 링크") ## Responsesapplication/json[​](#responses "responses에 대한 직접 링크") * 200 * 400 --- # 특수 기호 허용 가능한 특수 기호 숙소명, 객실명을 제외한 '설명' 항목에 작성 가능한 특수 기호 목록 `! @ # $ % ^ & * ( ) { } [ ] " ' , . ? / |` ## 사용 가이드[​](#사용-가이드 "사용 가이드에 대한 직접 링크") ### 숙소명, 객실명[​](#숙소명-객실명 "숙소명, 객실명에 대한 직접 링크") * 특수기호 사용 불가 (객실명은 `,` `()` 만 예외적으로 허용) ### 설명 항목[​](#설명-항목 "설명 항목에 대한 직접 링크") 다음 항목에서는 위의 특수 기호만 사용 가능합니다: * 숙소소개 * 예약안내 * 공지사항 * 취소환불 규정 안내 * 객실소개 --- # Tags 옥션, G마켓 오픈 시 필수 사항 옥션, G마켓 오픈시에는 ✅ 표시 항목에서 최소 1가지를 필수로 포함해주셔야 합니다. ## Property\_tags[​](#property_tags "Property_tags에 대한 직접 링크") | classifications | property\_tags | facility\_tags | service\_tag | attraction\_tags | | --------------- | -------------- | ---------------- | -------------------- | --------------------- | | HANOK | 가족 | 공용시설 | 서비스 | 주변관광지/체험 | | HOTEL | 고급/럭셔리 | ✅ 스파/월풀 | ✅ WIFI | 계곡 주변 | | MOTEL | 단체/MT/워크샵 | ✅ 노래방 | ✅ 반려동물 동반가능 | ✅ 골프장 주변 | | RESORT | 커플 | ✅ 농구장 | 발렛파킹 | ✅ 낚시장 주변 | | ✅ GLAMPING | ✅ 풀빌라 | ✅ 매점/편의점 | 보드게임 | ✅ 수목원/휴양림 주변 | | ✅ CARAVAN | 한옥 | ✅ 바베큐장 | 셔틀버스 | ✅ 수상레져 | | PENSION | 애견펜션 | ✅ 세미나실 | 영화관람 | ✅ 스키장 주변 | | ✅ POLLVILLA | ✅ 키즈펜션 | ✅ 수영장 | ✅ 자전거대여 | 해수욕장 주변 | | ✅ GUESTHOUSE | 5성 | 워터슬라이드 | ✅ 조식 서비스 | 강/호수 주변 | | CAMPING | 4성 | ✅ 족구장 | ✅ 짐보관 | | | RESIDENCE | 3성 | 찜질방 | ✅ 취사가능 | | | | 2성 | ✅ 축구장/풋살장 | ✅ 캠프파이어 | | | | 1성 | ✅ 카페 | 프로포즈/파티/이벤트 | | | | 특급1급 | 탁구장 | 프린터 사용 | | | | 특급 | ✅ 피트니스 | ✅ 픽업 | | | | 1급 | 공용스파 | 상비약 | | | | 관광 | ✅ 골프장 | ✅ 금연 | | | | 비즈니스 | ✅ 레스토랑 | 객실내흡연 | | | | 레지던스 | ✅ 키즈플레이룸 | 개인사물함 | | | | 부티크 | 공용샤워실 | 무료주차 | | | | | 공용화장실 | 장애인편의시설 | | | | | 공용주방 | ✅ 공항 셔틀 | | | | | ✅ 워터파크 | 바/라운지 | | | | | 온천 | ✅ 마사지 | | | | | ✅ 사우나 | ✅ 주차가능 | | | | | ✅ 연회장 | 기본양념 | | | | | 비즈니스센터 | | | | | | 루프탑 | | | | | | 유아시설 | | | ## Roomtype\_tags[​](#roomtype_tags "Roomtype_tags에 대한 직접 링크") | roomtype\_tags | amenity\_tags | view\_tags | | -------------- | ------------------ | ----------- | | 객실형태 | 객실 내 시설 | 객실 전망 | | 도미토리형 | 가스레인지/인덕션 | 바다 전망 | | 독채형 | 개별/테라스 바베큐 | 산 전망 | | 복층형 | 기본양념 | 도시 전망 | | 원룸형 | 냉장고 | 정원 전망 | | 분리형 | 다리미 | 수영장 전망 | | 싱글룸 | 드라이기 | 강 전망 | | 더블룸 | 미니바 | 창문없음 | | 트윈룸 | 벽난로 | 항구 전망 | | 온돌룸 | 쇼파 | | | 트리플룸 | ✅ 스파/월풀 | | | 패밀리룸 | 식탁 | | | 스위트룸 | 에어컨 | | | 펜트하우스 | 욕실용품 | | | 여성전용 | 욕조 | | | 남성전용 | 전기밥솥 | | | 남녀공용 | 전자레인지 | | | | 취사도구 | | | | 커피포트 | | | | 타월 | | | | TV | | | | 개별 수영장 | | | | 비데 | | | | ✅ 흡연가능 | | | | 파티룸 | | | | 화장실 | | | | VOD | | | | 무료 생수 | | | | Wi-Fi | | --- # Update Property Status ``` PATCH /properties/:vendor_property_id ``` * 공급사 > 온다 * 연동 숙소의 상태를 즉시 변경 합니다. * 비활성화 및 삭제 되었을 경우 disabled로 설정합니다. ## Request[​](#request "Request에 대한 직접 링크") ## Responsesapplication/json[​](#responses "responses에 대한 직접 링크") * 200 * 400 --- # Update Rateplan Status ``` PATCH /properties/:vendor_property_id/roomtypes/:vendor_roomtype_id/rateplans/:vendor_rateplan_id ``` * 공급사 > 온다 * 연동 숙소의 요금제 상태를 즉시 변경 합니다. * 비활성화 및 삭제 되었을 경우 disabled로 설정합니다. ## Request[​](#request "Request에 대한 직접 링크") ## Responsesapplication/json[​](#responses "responses에 대한 직접 링크") * 200 * 400 --- # Update Roomtype Status ``` PATCH /properties/:vendor_property_id/roomtypes/:vendor_roomtype_id ``` * 공급사 > 온다 * 연동 숙소의 객실 상태를 즉시 변경 합니다. * 비활성화 및 삭제 되었을 경우 disabled로 설정합니다. ## Request[​](#request "Request에 대한 직접 링크") ## Responsesapplication/json[​](#responses "responses에 대한 직접 링크") * 200 * 400 --- # Vendor API 최신 버전은 Vendor API 3.0입니다 이 문서는 **Vendor API 1.5**입니다. 기존 연동 파트너를 위해 계속 지원되지만, **신규 연동은 [Vendor API 3.0](/docs/api/vendor-v3/vendor-api-v3)** 을 사용하세요. 온다 Vendor API는 숙박업체(벤더)와 온다 플랫폼 간의 원활한 데이터 연동을 위한 RESTful API입니다. ## 개요[​](#개요 "개요에 대한 직접 링크") Vendor API를 통해 숙박업체는 다음과 같은 작업을 수행할 수 있습니다: * **숙소 정보 동기화**: 온다에서 업데이트된 숙소 정보 확인 * **객실 정보 관리**: 객실 타입 및 상세 정보 동기화 * **요금 정보 연동**: 실시간 요금 정보 업데이트 * **예약 가능 여부**: 재고 및 예약 가능 상태 관리 ## API 연동 방식[​](#api-연동-방식 "API 연동 방식에 대한 직접 링크") Vendor API는 두 가지 주요 연동 방식을 제공합니다: ### 1. ONDA → Vendor (Pull 방식)[​](#1-onda--vendor-pull-방식 "1. ONDA → Vendor (Pull 방식)에 대한 직접 링크") 온다에서 벤더 시스템으로 데이터를 요청하는 방식 * 온다가 벤더 API를 호출하여 최신 정보 획득 * 실시간 데이터 동기화 * 벤더 시스템의 능동적 응답 필요 ### 2. Vendor → ONDA (Push 방식)[​](#2-vendor--onda-push-방식 "2. Vendor → ONDA (Push 방식)에 대한 직접 링크") 벤더에서 온다 시스템으로 데이터를 전송하는 방식 * 벤더가 온다 API를 호출하여 정보 업데이트 * 변경사항 발생 시 즉시 전송 * 온다 시스템의 수동적 수신 ## 시작하기[​](#시작하기 "시작하기에 대한 직접 링크") Vendor API 연동을 시작하려면 다음 단계를 따르세요: 1. **파트너십 협약**: 온다 사업팀과 파트너십 계약 체결 2. **API 인증 정보 발급**: 개발 및 운영 환경용 API 키 발급 3. **기술 문서 검토**: API 명세서 및 연동 가이드 확인 4. **개발 환경 구축**: 테스트 환경에서 API 연동 개발 5. **테스트 및 검증**: 연동 기능 테스트 및 성능 검증 6. **운영 배포**: 운영 환경 배포 및 모니터링 ## 주요 특징[​](#주요-특징 "주요 특징에 대한 직접 링크") * **RESTful API**: 표준 HTTP 메서드 사용 * **JSON 포맷**: 요청/응답 데이터는 JSON 형식 * **인증 보안**: API 키 기반 인증 시스템 * **실시간 동기화**: 실시간 데이터 연동 지원 * **에러 핸들링**: 상세한 에러 코드 및 메시지 제공 *** 다음 단계에서는 구체적인 연동 방식별 가이드를 확인하세요. --- # Get Updated Property List ``` GET /sync/properties ``` * dapi.tport.dev -> 공급사가 지정한 url 위치 입니다. * 온다 > 공급사 (온다가 공급사를 호출해 저장합니다.) * 숙소 목록을 업데이트 합니다. * lastdate 부터 호출 시점까지 컨텐츠 및 상태가 변경 된 숙소 목록을 불러옵니다. * 정해진 주기별로 호출하며, 주기는 온다 기술 담당 매니저와 협의가 필요합니다. (기본 연동 방식 - 숙소 관리 참고) ## Request[​](#request "Request에 대한 직접 링크") ## Responsesapplication/json[​](#responses "responses에 대한 직접 링크") * 200 * 400 * 403 * 500 Validation Error Access Denied System Error --- # Get Property Detail ``` GET /properties/:vendor_property_id ``` * 온다 > 공급사 (온다가 공급사를 호출해 저장합니다.) * 숙소의 상세 정보를 불러옵니다. * ID 및 숙소 이름은 모두 공급사 정보입니다. ## Request[​](#request "Request에 대한 직접 링크") ## Responsesapplication/json[​](#responses "responses에 대한 직접 링크") * 200 * 400 * 403 * 500 Successful operation Validation Error Access Denied System Error --- # Get Property List ``` GET /properties ``` * 온다 > 공급사 (온다가 공급사를 호출해 저장합니다.) * 공급사의 전체 숙소 목록을 불러옵니다. * ID 및 숙소 이름은 모두 공급사 정보입니다. ## Request[​](#request "Request에 대한 직접 링크") ## Responsesapplication/json[​](#responses "responses에 대한 직접 링크") * 200 * 400 * 403 * 500 Successful operation Validation Error Access Denied System Error --- # Get Roomtype Detail ``` GET /properties/:vendor_property_id/roomtypes/:vendor_roomtype_id ``` * 온다 > 공급사 (온다가 공급사를 호출해 저장합니다.) * 객실과 객실 하위 요금제의 상세 정보를 불러옵니다. * ID 및 객실 이름은 모두 공급사 정보입니다. * `standalone` 정보는 숙소당 1개로, rateplan\_id를 제외한 나머지 정보는 전체 객실 모두 동일한 값으로 응답해주셔야 합니다. ## Request[​](#request "Request에 대한 직접 링크") ## Responsesapplication/json[​](#responses "responses에 대한 직접 링크") * 200 * 400 * 403 * 500 Validation Error Access Denied System Error --- # Get Roomtype List ``` GET /properties/:vendor_property_id/roomtypes ``` * 온다 > 공급사 (온다가 공급사를 호출해 저장합니다.) * 숙소의 전체 객실 목록을 불러옵니다. * ID 및 객실 이름은 모두 공급사 정보입니다 ## Request[​](#request "Request에 대한 직접 링크") ## Responsesapplication/json[​](#responses "responses에 대한 직접 링크") * 200 * 400 * 403 * 500 Validation Error Access Denied System Error --- # Vendor → ONDA Request 벤더(숙박업체)에서 온다 시스템으로 데이터를 전송하는 Push 방식의 연동 가이드입니다. ## 개요[​](#개요 "개요에 대한 직접 링크") Vendor → ONDA Request 방식은 벤더 시스템에서 온다 API를 호출하여 데이터를 업데이트하는 연동 방식입니다. ### 특징[​](#특징 "특징에 대한 직접 링크") * **능동적 업데이트**: 벤더가 변경사항 발생시 즉시 온다 시스템에 전송 * **Push 방식**: 벤더가 능동적으로 데이터를 전송 * **실시간 동기화**: 변경사항을 실시간으로 온다에 반영 * **효율성**: 변경된 데이터만 선택적으로 전송 가능 ## 연동 흐름[​](#연동-흐름 "연동 흐름에 대한 직접 링크") ## 주요 API 엔드포인트[​](#주요-api-엔드포인트 "주요 API 엔드포인트에 대한 직접 링크") 벤더에서 호출하는 온다 API들입니다. 서버 주소는 `https://vendor.dapi.tport.dev/gds/vendor`이며, 상세 파라미터와 스키마는 각 링크의 API 레퍼런스에서 확인할 수 있습니다. ### 숙소 정보 관리 (Push)[​](#숙소-정보-관리-push "숙소 정보 관리 (Push)에 대한 직접 링크") | Method | Endpoint | 설명 | | ------ | ------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------- | | PATCH | [`/properties/{vendor_property_id}`](/docs/api/vendor/update-property-status) | 숙소 상태 변경 (`enabled`/`disabled`) | | PATCH | [`/properties/{vendor_property_id}/roomtypes/{vendor_roomtype_id}`](/docs/api/vendor/update-roomtype-status) | 객실 상태 변경 | | PATCH | [`/properties/{vendor_property_id}/roomtypes/{vendor_roomtype_id}/rateplans/{vendor_rateplan_id}`](/docs/api/vendor/update-rateplan-status) | 요금제 상태 변경 | | POST | [`.../rateplans/{vendor_rateplan_id}/avails`](/docs/api/vendor/setting-avails) | 재고(vacancy) 변경 | | POST | [`.../rateplans/{vendor_rateplan_id}/rates`](/docs/api/vendor/setting-rates) | 요금(판매가/입금가 등) 변경 | | POST | [`.../rateplans/{vendor_rateplan_id}/business-days`](/docs/api/vendor/setting-business-days) | 판매 여부(영업일) 변경 | ### 기타 연동[​](#기타-연동 "기타 연동에 대한 직접 링크") | Method | Endpoint | 설명 | | ------ | -------------------------------------------------------------------------------------------- | -------------------------------------------------- | | GET | [`/properties`](/docs/api/vendor/get-property-list-hotelplus) | HotelPlus 숙소 목록 매핑 (Authorization 헤더 필수) | | GET | [`/properties/{vendor_property_id}/roomtypes`](/docs/api/vendor/get-roomtype-list-hotelplus) | HotelPlus 객실 목록 매핑 | | GET | [`/bookings`](/docs/api/vendor/settlement-comparison) | 정산 대사용 예약 목록 조회 | | GET | [`/bookings/{vendor_booking_number}`](/docs/api/vendor/reservation-information) | 예약 정보 확인 | ## 인증 및 보안[​](#인증-및-보안 "인증 및 보안에 대한 직접 링크") ### API 인증[​](#api-인증 "API 인증에 대한 직접 링크") * **방식**: API Key 인증 * **헤더**: `Authorization: {API_KEY}` * ONDA 담당자를 통해 발급받은 API 키를 그대로 헤더 값으로 전달합니다. 별도의 토큰 발급(OAuth2 등) 절차는 없습니다. ### 보안 요구사항[​](#보안-요구사항 "보안 요구사항에 대한 직접 링크") * **HTTPS 필수**: 모든 API 호출은 HTTPS 사용 ## 요청 포맷[​](#요청-포맷 "요청 포맷에 대한 직접 링크") 요청 바디는 엔드포인트마다 다르며, 공통 envelope 없이 필요한 필드만 전달합니다. ### 숙소 상태 변경 예시 (`update-property-status`)[​](#숙소-상태-변경-예시-update-property-status "숙소-상태-변경-예시-update-property-status에 대한 직접 링크") ``` { "status": "enabled" } ``` ### 재고 변경 예시 (`setting-avails`)[​](#재고-변경-예시-setting-avails "재고-변경-예시-setting-avails에 대한 직접 링크") ``` { "from": "2024-09-26", "to": "2024-09-30", "min_los": 1, "max_los": 0, "number_of_rooms": 10, "vacancy": 7 } ``` ## 응답 처리[​](#응답-처리 "응답 처리에 대한 직접 링크") **숙소 정보 관리 (Push) API** 6개 엔드포인트는 모두 `{"error": ""}` 형태의 단일 필드 응답을 사용하며, HTTP 상태 코드가 아니라 이 `error` 필드 값으로 성공/실패를 판단합니다. ### 정상 처리 (200)[​](#정상-처리-200 "정상 처리 (200)에 대한 직접 링크") ``` { "error": "" } ``` `error`가 빈 문자열이면 정상 처리된 것입니다. ### 처리 실패 (200)[​](#처리-실패-200 "처리 실패 (200)에 대한 직접 링크") ``` { "error": "에러 메세지" } ``` 요청은 접수되었으나 처리에 실패한 경우에도 HTTP 상태는 그대로 `200`이며, 실패 사유가 `error` 필드에 담겨 내려옵니다. ### 요청 형식 오류 (400)[​](#요청-형식-오류-400 "요청 형식 오류 (400)에 대한 직접 링크") 파라미터 누락 등 요청 자체가 잘못된 경우 `400`이 반환되며, 스펙상 응답 바디는 별도로 정의되어 있지 않습니다(예시: `{}`). **기타 연동** 4개 엔드포인트는 각자 응답 구조가 다릅니다. `get-roomtype-list-hotelplus`, `reservation-information`은 위와 같이 `error` 필드를 포함하지만, `get-property-list-hotelplus`(배열 그대로 반환)와 `settlement-comparison`(`{count, offset, limit, reservations}`)은 `error` 필드 없이 데이터를 바로 반환합니다. 상세 스키마는 각 레퍼런스 페이지를 참고하세요. ## 개발 가이드[​](#개발-가이드 "개발 가이드에 대한 직접 링크") ### 직접 API 호출[​](#직접-api-호출 "직접 API 호출에 대한 직접 링크") 별도로 제공되는 SDK는 없으며, REST API를 직접 호출합니다. ``` # Python 예시 import requests import json def update_property_status(vendor_property_id, status): headers = { 'Authorization': api_key, 'Content-Type': 'application/json' } response = requests.patch( f'https://vendor.dapi.tport.dev/gds/vendor/properties/{vendor_property_id}', headers=headers, data=json.dumps({'status': status}) ) return response.json() ``` ## 에러 핸들링[​](#에러-핸들링 "에러 핸들링에 대한 직접 링크") ### 재시도 로직[​](#재시도-로직 "재시도 로직에 대한 직접 링크") 네트워크 오류나 일시적 장애에 대비한 재시도 메커니즘: ``` async function retryRequest(requestFn, maxRetries = 3) { for (let i = 0; i < maxRetries; i++) { try { return await requestFn(); } catch (error) { if (i === maxRetries - 1) throw error; await sleep(Math.pow(2, i) * 1000); // 지수 백오프 } } } ``` ### 응답 처리 시 유의사항[​](#응답-처리-시-유의사항 "응답 처리 시 유의사항에 대한 직접 링크") * `error` 필드가 빈 문자열(`""`)이면 성공, 값이 있으면 실패로 간주하고 해당 메세지를 로그에 남깁니다. * HTTP 상태 코드는 `200`(성공) / `400`(요청 오류) 두 가지만 정의되어 있습니다. ## 모니터링 및 로깅[​](#모니터링-및-로깅 "모니터링 및 로깅에 대한 직접 링크") ### 로그 기록[​](#로그-기록 "로그 기록에 대한 직접 링크") ``` // 로그 예시 { "timestamp": "2024-09-26T15:30:00Z", "level": "INFO", "message": "Property updated successfully", "data": { "property_id": "PROP001", "response_time": 245, "status_code": 200 } } ``` ### 메트릭 추적[​](#메트릭-추적 "메트릭 추적에 대한 직접 링크") * API 호출 성공률 * 평균 응답 시간 * 에러율 및 에러 유형 * 데이터 업데이트 빈도 *** 이전: [ONDA → Vendor Request](/docs/api/vendor/onda-to-vendor-request) 방식 가이드 --- # Get Updated Roomtype List ``` GET /sync/roomtypes ``` * dapi.tport.dev -> 공급사가 지정한 url 위치 입니다. * 온다 > 공급사 (온다가 공급사를 호출해 저장합니다.) * 객실 목록을 업데이트 합니다. * lastdate 부터 호출 시점까지 객실과 요금제의 컨텐츠 및 상태가 변경 된 객실 목록을 불러옵니다. * 정해진 주기별로 호출하며, 주기는 온다 기술 담당 매니저와 협의가 필요합니다. (기본 연동 방식 - 숙소 관리 참고) ## Request[​](#request "Request에 대한 직접 링크") ## Responsesapplication/json[​](#responses "responses에 대한 직접 링크") * 200 * 400 * 403 * 500 Validation Error Access Denied System Error --- Version: 1.5 # 기타 API 기타 API ## Authentication[​](#authentication "Authentication에 대한 직접 링크") * API Key: Authorization ONDA 담당자를 통해 발급받은 API 키를 입력하세요. | Security Scheme Type: | apiKey | | ---------------------- | ------------- | | Header parameter name: | Authorization | --- Version: 1.5 # 숙소 생성 API 숙소 생성 API --- Version: 1.5 # 숙소 정보 관리 (Push) API 숙소 정보 관리 (Push) API ## Authentication[​](#authentication "Authentication에 대한 직접 링크") * API Key: Authorization ONDA 담당자를 통해 발급받은 API 키를 입력하세요. | Security Scheme Type: | apiKey | | ---------------------- | ------------- | | Header parameter name: | Authorization | --- Version: 1.5 # 숙소 정보 관리 (Sync) API 숙소 정보 관리 (Sync) API --- Version: 1.5 # 예약 API 예약 API --- # 자주 묻는 질문 (FAQ) ONDA API 연동과 관련하여 자주 묻는 질문들을 정리했습니다. *** ## 기본 정보[​](#기본-정보 "기본 정보에 대한 직접 링크") **Q. ONDA Hub가 무엇인가요?** ONDA Hub는 숙박 상품 공급자와 판매 채널을 연결하는 통합 유통 플랫폼입니다. * **Vendor(공급자)**: 숙박 상품을 ONDA에 공급하고 70+ 채널에 판매 * **Channel(판매자)**: ONDA의 25,000+ 숙박 상품을 판매 RESTful 기반의 API를 통해 실시간 재고/가격 조회, 예약 처리 등을 수행할 수 있습니다. **Q. Vendor와 Channel 파트너의 차이는 무엇인가요?** **Vendor Partner (공급자)** * 호텔, 리조트, 펜션 등 숙박 시설 * PMS 시스템 제공사 * 호텔 체인 및 상품 공급사 * **목적**: 숙박 상품을 ONDA에 공급하고 여러 채널에 판매 **Channel Partner (판매자)** * OTA (Online Travel Agency) * 여행사 및 메타서치 엔진 * 숙박 예약 플랫폼 * **목적**: ONDA의 숙박 상품을 자사 플랫폼에서 판매 **Q. 어떤 파트너 유형을 선택해야 하나요?** 귀사의 비즈니스 모델에 따라 선택하세요: * **숙박 상품을 공급**하시나요? → **Vendor API** 사용 * **숙박 상품을 판매**하시나요? → **Channel API** 사용 자세한 내용은 [시작하기](/docs/getting-started) 페이지를 참고하세요. *** ## 시작하기[​](#시작하기 "시작하기에 대한 직접 링크") **Q. API 연동 개발 기간은 얼마나 걸리나요?** **평균 개발 기간** * **Channel API**: 약 2주 (평균) * **Vendor API**: 약 1개월 (1 M/M) 실제 개발 기간은 구현 범위와 개발 리소스에 따라 달라질 수 있습니다. **Q. API 키는 어떻게 발급받나요?** **발급 절차** 1. ONDA와 파트너 계약 체결 2. 개발 환경용 API 키 발급 3. 개발 및 테스트 진행 4. 운영 환경용 API 키 발급 5. 정식 서비스 시작 **문의** * 파트너 신청: [문의하기](https://onda.me/ko/contact/) * 기술 문의: **Q. 테스트 환경은 어떻게 구성하나요?** ONDA는 개발과 운영 환경을 분리하여 제공합니다: **개발 환경** * URL: `https://dapi.tport.dev` * 용도: API 연동 개발 및 테스트 **운영 환경** * URL: `https://gds.tport.io` * 용도: 실제 서비스 운영 각 환경별로 별도의 API 키가 발급됩니다. *** ## 기술 스펙[​](#기술-스펙 "기술 스펙에 대한 직접 링크") **Q. API 엔드포인트는 어디인가요?** **개발 환경** ``` https://dapi.tport.dev ``` **운영 환경** ``` https://gds.tport.io ``` 모든 API는 HTTPS 프로토콜을 사용합니다. **Q. 어떤 데이터 형식을 사용하나요?** **기본 정보** * **프로토콜**: HTTPS * **데이터 형식**: JSON (UTF-8 인코딩) * **HTTP 메서드**: GET, POST, PUT, PATCH, DELETE * **Content-Type**: `application/json` 모든 요청과 응답은 JSON 형식으로 처리됩니다. **Q. API 인증은 어떻게 하나요?** **Channel API 인증** HTTP 헤더에 다음 두 가지 키를 포함해야 합니다: 1. **Authorization Key** * 헤더: `x-api-key` * ONDA에서 발급한 API 인증 키 2. **Channel Key** * 헤더: `x-channel-key` * 채널사를 구분하는 고유 키 **Vendor API 인증** ONDA에서 제공하는 인증 방식에 따라 진행되며, 계약 시 상세 안내됩니다. *** ## 연동 방식[​](#연동-방식 "연동 방식에 대한 직접 링크") **Q. Real Time Type과 DB Cache Type의 차이는 무엇인가요?** **Real Time Type** * 고객이 검색할 때마다 ONDA API를 실시간으로 호출 * DB에 재고/요금 저장 불필요 * Webhook 개발 불필요 * 구현이 상대적으로 간단 **DB Cache Type** * 모든 상품의 재고/요금을 채널 DB에 저장 * 고객 검색 시 자체 DB 조회 (빠른 응답) * Webhook 개발 필수 (실시간 업데이트) * 대용량 트래픽 처리에 유리 자세한 내용은 다음 문서를 참고하세요: * [Real Time Type](/docs/api/channel/realtime-type) * [DB Cache Type](/docs/api/channel/db-cache-type) **Q. Webhook은 무엇이고 언제 필요한가요?** **Webhook이란?** ONDA에서 변경된 정보를 실시간으로 채널에 알려주는 Push 방식의 API입니다. **Webhook 종류** * `contents_updated`: 숙소/객실/패키지 콘텐츠 변경 알림 * `status_updated`: 상품 추가 또는 판매상태 변경 알림 * `inventory_updated`: 요금/재고 변경 알림 **필요한 경우** * **DB Cache Type 연동 시 필수** * Real Time Type에서는 선택사항 자세한 내용은 [Webhook 개요](/docs/api/channel/webhook-overview)를 참고하세요. **Q. ONDA → Vendor와 Vendor → ONDA 방식의 차이는?** Vendor API는 두 가지 연동 방식을 제공합니다: **ONDA → Vendor (Pull 방식)** * ONDA에서 Vendor 시스템의 API를 호출 * 실시간 데이터 동기화 * Vendor는 API를 제공하고 응답 **Vendor → ONDA (Push 방식)** * Vendor에서 ONDA API를 호출하여 정보 업데이트 * 변경사항 발생 시 즉시 전송 * ONDA가 데이터를 수신하고 저장 대부분의 경우 두 방식을 함께 사용합니다. *** ## 예약 및 테스트[​](#예약-및-테스트 "예약 및 테스트에 대한 직접 링크") **Q. 테스트용 숙소는 어떻게 사용하나요?** **테스트용 Property ID** | Property ID | 분류 | Rateplan 포함 | | ----------- | ---- | ------------- | | 117417 | 호텔 | 포함 | | 120135 | 호텔 | 포함 | **주의사항** * 실제 숙소로는 테스트할 수 없습니다 * 위 테스트 숙소로만 예약 테스트를 진행해야 합니다 * 예약 테스트 후 반드시 취소 처리를 완료해야 합니다 자세한 내용은 [예약 테스트 숙소](/docs/api/channel/test-property)를 참고하세요. **Q. 실제 숙소 콘텐츠는 조회할 수 있나요?** **가능합니다** (단, 조건부) * 담당 매니저와 사전 협의 필요 * 실제 숙소의 **콘텐츠 정보**까지는 조회 가능 * 단, **예약 테스트는 절대 불가** (테스트 숙소만 사용) 실제 숙소로 예약을 생성하면 실제 예약이 발생하므로 주의가 필요합니다. *** ## 기술 지원[​](#기술-지원 "기술 지원에 대한 직접 링크") **Q. 기술 문의는 어디로 하나요?** **문의 채널** * **기술 문의**: * **파트너 신청**: [문의하기](https://onda.me/ko/contact/) **지원 시간** * 평일 10:00 - 18:00 (KST) * 긴급 장애: 24/7 대응 이메일로 문의 시 다음 정보를 포함해주세요: * 파트너사명 * API 유형 (Vendor/Channel) * 환경 (개발/운영) * 구체적인 문의 내용 **Q. API 장애 발생 시 어떻게 대응하나요?** **긴급 장애 대응** * 24/7 긴급 대응 체계 운영 * 로 즉시 문의 **장애 문의 시 포함 정보** * 발생 시간 * 에러 메시지 또는 응답 코드 * 요청 파라미터 (민감 정보 제외) * 재현 가능 여부 빠른 해결을 위해 구체적인 정보를 제공해주세요. *** ## 추가 문서[​](#추가-문서 "추가 문서에 대한 직접 링크") 더 자세한 정보는 다음 문서를 참고하세요: * [ONDA Hub 소개](/docs/introduction) * [시작하기 가이드](/docs/getting-started) * [Vendor API 문서](/docs/api/vendor/vendor-api) * [Channel API 문서](/docs/api/channel/channel-api) * [API 변경 이력](/changelog) --- # ONDA hub 시작하기 ONDA hub와 연동하기 위한 단계별 가이드입니다. 파트너 유형을 파악하고 적절한 API를 선택하여 연동을 시작하세요. ## 연동 타임라인[​](#연동-타임라인 "연동 타임라인에 대한 직접 링크") | 단계 | 1주차 | 2주차 | 3주차 | 4주차 | | ----------------------- | ----- | ----- | ----- | ----- | | 1. 파트너 유형 파악하기 | | | | | | 2. ONDA hub 계약 | | | | | | 3. 연동 개발 | | | | | | 4. 정식 런칭 준비 | | | | | 참고 실제 일정은 파트너사의 상황과 요구사항에 따라 달라질 수 있습니다. ## 1. 파트너 유형 파악하기[​](#1-파트너-유형-파악하기 "1. 파트너 유형 파악하기에 대한 직접 링크") ### 공급자인지? 판매자인지? 스스로 생각해보기[​](#공급자인지-판매자인지-스스로-생각해보기 "공급자인지? 판매자인지? 스스로 생각해보기에 대한 직접 링크") ONDA hub와 연동하기 전에, 먼저 귀사의 비즈니스 모델을 명확히 파악해야 합니다. ONDA hub 와의 더욱 강력한 시너지를 위해 온다와 사전 논의가 필요하다면 아래 경로를 통해 문의해주세요! **온다와 논의하기:** * [문의하기](https://onda.me/ko/contact/) ### 내가 어떤 파트너인지 파악할 수 있는 질문[​](#내가-어떤-파트너인지-파악할-수-있는-질문 "내가 어떤 파트너인지 파악할 수 있는 질문에 대한 직접 링크") 다음 플로우차트를 통해 귀사에 적합한 API 유형을 확인하세요. *** ## 2. ONDA hub 계약[​](#2-onda-hub-계약 "2. ONDA hub 계약에 대한 직접 링크") 파트너 유형을 결정했다면, ONDA hub와 정식 계약을 진행합니다. **계약 절차:** 1. 파트너 신청서 작성 2. 사업자 등록증 및 필요 서류 제출 3. 계약 조건 협의 4. 계약서 체결 5. API 인증 정보 발급 **문의:** * [문의하기](https://onda.me/ko/contact/) * 담당자와의 상담을 통해 계약 조건을 확인하세요 *** ## 3. 연동 개발[​](#3-연동-개발 "3. 연동 개발에 대한 직접 링크") 계약이 완료되면 본격적인 API 연동 개발을 시작합니다. ### API 문서 검토하기[​](#api-문서-검토하기 "API 문서 검토하기에 대한 직접 링크") 연동하고자 하는 API 문서를 면밀히 검토합니다. * **Vendor Partner:** [Vendor API 문서](/docs/api/vendor/vendor-api) * **Channel Partner:** [Channel API 문서](/docs/api/channel/channel-api) ### 개발 요건 체크리스트 작성하기[​](#개발-요건-체크리스트-작성하기 "개발 요건 체크리스트 작성하기에 대한 직접 링크") 파트너사의 연동 컨셉, 서비스 플로우 동기화, 사용 엔드포인트 결정, 정책 확인 등을 하기 위해 연동 개발 전에 반드시 개발 요건 체크리스트를 작성합니다. 이 체크리스트는 계약 협의 이후 ONDA 기술 지원팀을 통해 별도 전달 됩니다. ### 개발 킥오프 미팅[​](#개발-킥오프-미팅 "개발 킥오프 미팅에 대한 직접 링크") ONDA 기술 지원팀과 킥오프 미팅을 진행합니다: * 연동 일정 협의 * 기술적 이슈 확인 * 테스트 계정 발급 * 개발 환경 설정 ### 연동 개발 지원[​](#연동-개발-지원 "연동 개발 지원에 대한 직접 링크") 개발 중 발생하는 문제는 ONDA 기술 지원팀에 문의하세요: * **기술 문의**: * **개발 가이드**: 각 API 문서 참조 * **샘플 코드**: API 문서 내 예제 참조 ### QA (품질 보증)[​](#qa-품질-보증 "QA (품질 보증)에 대한 직접 링크") 개발이 완료되면 QA를 진행합니다: 1. **단위 테스트**: 각 API 엔드포인트 테스트 2. **통합 테스트**: 전체 워크플로우 테스트 3. **성능 테스트**: 부하 테스트 및 응답 시간 확인 4. **보안 테스트**: 인증 및 데이터 보안 확인 *** ## 4. 정식 런칭 준비[​](#4-정식-런칭-준비 "4. 정식 런칭 준비에 대한 직접 링크") QA가 완료되면 정식 운영을 위한 최종 준비를 진행합니다. ### 운영 협의[​](#운영-협의 "운영 협의에 대한 직접 링크") * 운영 시간 및 장애 대응 절차 * 모니터링 및 알림 설정 * 데이터 백업 정책 ### 정산 협의[​](#정산-협의 "정산 협의에 대한 직접 링크") * 수수료 정책 확인 * 정산 주기 및 방식 * 세금계산서 발행 절차 ### CS (고객 지원) 협의[​](#cs-고객-지원-협의 "CS (고객 지원) 협의에 대한 직접 링크") * 고객 문의 처리 프로세스 * 예약 관련 이슈 해결 절차 * 긴급 상황 대응 방안 *** ## 개발 기간 안내[​](#개발-기간-안내 "개발 기간 안내에 대한 직접 링크") API 연동에 걸리는 평균 개발 기간입니다: * **Vendor API**: 평균 한 달 (1 M/M) * **Channel API**: 평균 한 달 (1 M/M) 참고 사항 실제 개발 기간은 귀사의 시스템 환경과 구현 범위에 따라 달라질 수 있습니다. *** ## 다음 단계[​](#다음-단계 "다음 단계에 대한 직접 링크") 파트너 유형에 따라 아래 문서를 참고하여 연동을 시작하세요: ### Vendor Partner (공급자)[​](#vendor-partner-공급자 "Vendor Partner (공급자)에 대한 직접 링크") * [Vendor API 문서](/docs/api/vendor/vendor-api) ### Channel Partner (판매자)[​](#channel-partner-판매자 "Channel Partner (판매자)에 대한 직접 링크") * [Channel API 문서](/docs/api/channel/channel-api) * [DB Cache Type 구현 가이드](/docs/api/channel/db-cache-type) * [Real Time Type 구현 가이드](/docs/api/channel/realtime-type) ### 추가 자료[​](#추가-자료 "추가 자료에 대한 직접 링크") * [용어 정리](/docs/glossary) *** **문의하기:** * 기술 문의: * 파트너 신청: [문의하기](https://onda.me/ko/contact/) AI 개발 도구로 더 빠르게 연동하기 Claude Code, Cursor, Windsurf 등 AI 개발 도구를 사용하신다면, [AI 개발 지원](/ai-tools) 페이지에서 ONDA API 전체 문서를 컨텍스트 파일로 다운로드하세요. AI가 API 구조와 요청/응답 형식을 이해하고 더 정확한 코드를 제안합니다. --- # 용어 정리 ONDA API 문서에서 사용되는 주요 용어들을 정리한 페이지입니다. ## 이해관계자[​](#이해관계자 "이해관계자에 대한 직접 링크") ### ONDA hub[​](#onda-hub "ONDA hub에 대한 직접 링크") 숙박 산업을 위한 통합 온라인 유통 플랫폼으로, 공급자와 판매 채널을 연결하는 중추적인 역할을 수행합니다. ### Vendor (공급자)[​](#vendor-공급자 "Vendor (공급자)에 대한 직접 링크") 숙박 상품을 ONDA hub에 공급하는 파트너사를 의미합니다. * 숙박 시설 (호텔, 리조트, 펜션 등) * 호텔 체인 * PMS(Property Management System) 제공사 * 기타 숙박 상품 공급사 ### Channel (판매자)[​](#channel-판매자 "Channel (판매자)에 대한 직접 링크") ONDA hub의 숙박 상품을 판매하는 파트너사를 의미합니다. * OTA (Online Travel Agency) * 여행사 * 메타서치 엔진 * 기타 숙박 상품 판매 플랫폼 ## 예약 관련 용어[​](#예약-관련-용어 "예약 관련 용어에 대한 직접 링크") ### Booker (예약자)[​](#booker-예약자 "Booker (예약자)에 대한 직접 링크") 숙박 예약을 진행하는 사람을 의미합니다. 실제 투숙자와 동일할 수도 있고 다를 수도 있습니다. 예시: * 본인이 직접 예약하는 경우: 예약자 = 투숙자 * 부모님을 위해 자녀가 예약하는 경우: 예약자 ≠ 투숙자 ### Guest (투숙자)[​](#guest-투숙자 "Guest (투숙자)에 대한 직접 링크") 실제로 숙박 시설에 투숙하는 사람을 의미합니다. ## 시스템 용어[​](#시스템-용어 "시스템 용어에 대한 직접 링크") ### CMS (Channel Management System)[​](#cms-channel-management-system "CMS (Channel Management System)에 대한 직접 링크") 다수의 판매 채널과 숙박 시설을 연결하여 재고, 가격, 예약 정보를 통합 관리하는 시스템입니다. ### PMS (Property Management System)[​](#pms-property-management-system "PMS (Property Management System)에 대한 직접 링크") 숙박 시설의 운영을 관리하는 시스템으로, 예약, 체크인/체크아웃, 객실 관리 등의 기능을 제공합니다. ### OTA (Online Travel Agency)[​](#ota-online-travel-agency "OTA (Online Travel Agency)에 대한 직접 링크") 온라인 여행사를 의미하며, 인터넷을 통해 숙박, 항공권, 패키지 여행 등을 판매하는 플랫폼입니다. ## 숙박 시설 관련 용어[​](#숙박-시설-관련-용어 "숙박 시설 관련 용어에 대한 직접 링크") ### Property (숙소)[​](#property-숙소 "Property (숙소)에 대한 직접 링크") 호텔, 리조트, 펜션, 풀빌라 등 숙박이 가능한 시설 전체를 의미합니다. ### Room Type (객실 타입)[​](#room-type-객실-타입 "Room Type (객실 타입)에 대한 직접 링크") 숙소 내에서 제공하는 객실의 종류를 의미합니다. * 예시: 스탠다드룸, 디럭스룸, 스위트룸, 온돌방, 침대방 등 ### Rate Plan (요금제)[​](#rate-plan-요금제 "Rate Plan (요금제)에 대한 직접 링크") 동일한 객실 타입에 대한 다양한 가격 정책을 의미합니다. * 예시: 조식 포함, 조식 불포함, 환불 가능, 환불 불가 등 ## 재고 및 가격 관련 용어[​](#재고-및-가격-관련-용어 "재고 및 가격 관련 용어에 대한 직접 링크") ### Inventory (재고)[​](#inventory-재고 "Inventory (재고)에 대한 직접 링크") 특정 날짜에 판매 가능한 객실의 수량을 의미합니다. ### Availability (판매 가능 여부)[​](#availability-판매-가능-여부 "Availability (판매 가능 여부)에 대한 직접 링크") 특정 날짜에 객실 판매가 가능한지 여부를 의미합니다. ### Rate (요금)[​](#rate-요금 "Rate (요금)에 대한 직접 링크") 특정 날짜, 특정 객실 타입에 대한 1박 기준 가격을 의미합니다. ### Allotment (할당량)[​](#allotment-할당량 "Allotment (할당량)에 대한 직접 링크") 채널별로 할당된 판매 가능 객실 수량을 의미합니다. ## API 연동 관련 용어[​](#api-연동-관련-용어 "API 연동 관련 용어에 대한 직접 링크") ### Real Time Type (실시간 타입)[​](#real-time-type-실시간-타입 "Real Time Type (실시간 타입)에 대한 직접 링크") 채널 파트너가 자체 DB에 재고/가격을 저장하지 않고, 검색 요청 시마다 ONDA API를 실시간으로 호출하여 데이터를 조회하는 방식입니다. **장점:** * 구현이 비교적 간단함 * 항상 최신 데이터 제공 **단점:** * API 호출 빈도가 높음 * 응답 속도가 DB Cache Type보다 느릴 수 있음 ### DB Cache Type (DB 캐시 타입)[​](#db-cache-type-db-캐시-타입 "DB Cache Type (DB 캐시 타입)에 대한 직접 링크") 채널 파트너가 ONDA의 콘텐츠, 재고, 가격 데이터를 자체 DB에 저장(캐싱)하고, 이를 기반으로 검색 서비스를 제공하는 방식입니다. **장점:** * 빠른 검색 응답 속도 * API 호출 빈도 감소 **단점:** * 초기 구축 복잡도 높음 * 데이터 동기화 로직 필요 ## 예약 상태 관련 용어[​](#예약-상태-관련-용어 "예약 상태 관련 용어에 대한 직접 링크") ### Pending (대기)[​](#pending-대기 "Pending (대기)에 대한 직접 링크") 예약 요청이 접수되었으나 아직 확정되지 않은 상태입니다. ### Confirmed (확정)[​](#confirmed-확정 "Confirmed (확정)에 대한 직접 링크") 예약이 최종 확정된 상태입니다. ### Cancelled (취소)[​](#cancelled-취소 "Cancelled (취소)에 대한 직접 링크") 예약이 취소된 상태입니다. ### No-show (노쇼)[​](#no-show-노쇼 "No-show (노쇼)에 대한 직접 링크") 예약자가 예약 시간에 나타나지 않은 상태입니다. ## 정산 관련 용어[​](#정산-관련-용어 "정산 관련 용어에 대한 직접 링크") ### Commission (수수료)[​](#commission-수수료 "Commission (수수료)에 대한 직접 링크") ONDA hub가 채널 파트너에게 제공하는 판매 수수료입니다. ### Net Rate (순수 요금)[​](#net-rate-순수-요금 "Net Rate (순수 요금)에 대한 직접 링크") 수수료가 제외된 실제 숙소에 지불되는 요금입니다. ### Selling Price (판매가)[​](#selling-price-판매가 "Selling Price (판매가)에 대한 직접 링크") 최종 고객에게 판매되는 가격입니다. *** 용어에 대한 추가 문의사항이 있으시면 로 연락 주시기 바랍니다. --- # ONDA Hub 소개 ONDA Hub 는 **벤더 파트너**와 **채널 파트너**가 ONDA 의 표준 API를 통해 호텔, 리조트, 펜션 등 숙박 판매 비즈니스를 확장할 수 있도록 지원하는 통합 개발자 플랫폼입니다. ## ONDA hub란?[​](#onda-hub란 "ONDA hub란?에 대한 직접 링크") ONDA hub는 숙박 산업을 위한 호텔, 리조트, 펜션, 풀빌라 등의 통합 온라인 유통 플랫폼으로, 공급자와 판매 채널을 연결하는 중추적인 역할을 수행합니다. ONDA hub는 다음과 같은 핵심 기능을 제공합니다: * **통합 연동**: 숙박 시설 공급자와 70여개 이상의 채널을 통합 연결 * **실시간 동기화**: 콘텐츠, 재고, 가격, 예약 정보를 실시간으로 업데이트 * **표준화된 API**: 일관된 인터페이스로 복잡성 감소 * **폭넓은 상품 카테고리**: 국내외 다양한 숙박 카테고리 상품을 대량으로 빠르게 확보 ## 파트너 유형[​](#파트너-유형 "파트너 유형에 대한 직접 링크") ONDA hub 의 파트너는 아래와 같이 크게 2가지로 분류됩니다. ### Vendor Partner (공급자)[​](#vendor-partner-공급자 "Vendor Partner (공급자)에 대한 직접 링크") 숙박 시설, 호텔 체인, PMS 시스템 등 숙박 상품을 공급하는 파트너 **주요 기능:** * 상품 등록 및 관리 * 재고/요금 실시간 업데이트 * 예약 수신 및 확정 * 정산 관리 ### Channel Partner (판매자)[​](#channel-partner-판매자 "Channel Partner (판매자)에 대한 직접 링크") OTA, 여행사, 메타서치 등 숙박 상품을 판매하는 파트너 **주요 기능:** * 최대 25,000+ 숙박 시설 판매 * 실시간 재고/가격 조회 혹은 최신화 * 예약 생성 및 관리 * 통합 콘텐츠 관리 ## 개발 기간[​](#개발-기간 "개발 기간에 대한 직접 링크") 파트너들은 평균 한 달 정도의 개발 기간으로 ONDA Hub API를 연동하고 있습니다. (순수 API 연동개발에 해당하며, 파트너가 구현하고자 하는 서비스에 따라 상이할 수 있습니다.) * **Vendor API**: 평균 한 달 (1 M/M) * **Channel API**: 평균 한 달 (1 M/M) ## 기술 지원[​](#기술-지원 "기술 지원에 대한 직접 링크") * **문서**: 상세한 API 문서 및 가이드 * **기술 지원**: 전담 기술 지원팀 * **기술 문의**: * **파트너 신청**: [문의하기](https://onda.me/ko/contact/) ## 다음 단계[​](#다음-단계 "다음 단계에 대한 직접 링크") * [ONDA hub 시작하기](/docs/getting-started) * [Vendor API 시작하기](/docs/api/vendor/vendor-api) * [Channel API 시작하기](/docs/api/channel/channel-api) * [용어 정리 보기](/docs/glossary) --- # 문서 작성 스타일 가이드 ONDA Partner Developer Center의 일관된 문서 품질을 위한 스타일 가이드입니다. ## 📝 마크다운 기본 요소[​](#-마크다운-기본-요소 "📝 마크다운 기본 요소에 대한 직접 링크") ### 제목 (Headers)[​](#제목-headers "제목 (Headers)에 대한 직접 링크") 제목은 4단계까지 사용하며, 계층 구조를 명확히 합니다. ``` # H1 - 페이지 제목 (한 페이지당 하나만) ## H2 - 주요 섹션 ### H3 - 하위 섹션 #### H4 - 상세 항목 ``` **예시:** # H1 - 페이지 제목 ## H2 - 주요 섹션[​](#h2---주요-섹션 "H2 - 주요 섹션에 대한 직접 링크") ### H3 - 하위 섹션[​](#h3---하위-섹션 "H3 - 하위 섹션에 대한 직접 링크") #### H4 - 상세 항목[​](#h4---상세-항목 "H4 - 상세 항목에 대한 직접 링크") *** ### 단락 (Paragraphs)[​](#단락-paragraphs "단락 (Paragraphs)에 대한 직접 링크") * 단락 사이에는 빈 줄을 하나 삽입합니다. * 한 문장이 끝나면 마침표를 명확히 표시합니다. * 읽기 쉽게 적절한 길이로 구성합니다. ``` 첫 번째 단락입니다. 내용을 작성합니다. 두 번째 단락입니다. 빈 줄로 구분합니다. ``` *** ### 강조 (Emphasis)[​](#강조-emphasis "강조 (Emphasis)에 대한 직접 링크") ``` **굵게 (Bold)** - 중요한 용어나 강조 *기울임 (Italic)* - 부가 설명이나 영문 용어 `코드 (Code)` - API 엔드포인트, 파라미터, 값 ``` **예시:** * **중요한 정보**는 굵게 표시합니다. * *부가 설명*은 기울임체로 표시합니다. * `status` 값은 코드 형식으로 표시합니다. *** ### 목록 (Lists)[​](#목록-lists "목록 (Lists)에 대한 직접 링크") #### 순서 없는 목록[​](#순서-없는-목록 "순서 없는 목록에 대한 직접 링크") ``` - 첫 번째 항목 - 두 번째 항목 - 하위 항목 - 하위 항목 - 세 번째 항목 ``` #### 순서 있는 목록[​](#순서-있는-목록 "순서 있는 목록에 대한 직접 링크") ``` 1. 첫 번째 단계 2. 두 번째 단계 3. 세 번째 단계 ``` *** ## 📊 테이블 (Tables)[​](#-테이블-tables "📊 테이블 (Tables)에 대한 직접 링크") API 목록이나 파라미터 설명에 테이블을 사용합니다. ``` | API | Method | 설명 | |-----|--------|------| | Get Property List | `GET` | 숙소 목록 조회 | | Create Reservation | `POST` | 예약 생성 | ``` **결과:** | API | Method | 설명 | | ------------------ | ------ | -------------- | | Get Property List | `GET` | 숙소 목록 조회 | | Create Reservation | `POST` | 예약 생성 | ### 테이블 작성 규칙[​](#테이블-작성-규칙 "테이블 작성 규칙에 대한 직접 링크") * ✅ 헤더는 명확하게 작성 * ✅ HTTP 메소드는 코드 형식 사용: `` `GET` ``, `` `POST` `` * ✅ API 이름은 일관된 네이밍 사용 * ✅ 설명은 간결하고 명확하게 *** ## 💡 정보 박스 (Admonitions)[​](#-정보-박스-admonitions "💡 정보 박스 (Admonitions)에 대한 직접 링크") 중요한 정보를 강조할 때 사용합니다. ### Caution (주의)[​](#caution-주의 "Caution (주의)에 대한 직접 링크") ``` :::caution[제목] 주의가 필요한 내용을 작성합니다. ::: ``` 이미지 저작권 공급사에서 ONDA로 동기화하는 모든 이미지는 저작권에 문제가 없어야 합니다. ### Note (참고)[​](#note-참고 "Note (참고)에 대한 직접 링크") ``` :::note[제목] 참고 정보를 작성합니다. ::: ``` 참고 사항 해당 항목은 일부 채널에만 적용됩니다. ### Tip (팁)[​](#tip-팁 "Tip (팁)에 대한 직접 링크") ``` :::tip[제목] 유용한 팁을 작성합니다. ::: ``` 개발 팁 SDK를 사용하면 더 쉽게 연동할 수 있습니다. ### Warning (경고)[​](#warning-경고 "Warning (경고)에 대한 직접 링크") ``` :::warning[제목] 경고 메시지를 작성합니다. ::: ``` 필수 요구사항 옥션, G마켓 오픈시에는 체크 표시 항목에서 최소 1가지를 필수로 포함해주셔야 합니다. ### Info (정보)[​](#info-정보 "Info (정보)에 대한 직접 링크") ``` :::info[제목] 일반 정보를 작성합니다. ::: ``` 업데이트 정보 24년 8월 업데이트 *** ## 🔗 링크 (Links)[​](#-링크-links "🔗 링크 (Links)에 대한 직접 링크") ### 내부 문서 링크[​](#내부-문서-링크 "내부 문서 링크에 대한 직접 링크") ``` [링크 텍스트](페이지-id) 예시: [숙소 생성](property-creation) [예약 API](reservation) ``` ### 외부 링크[​](#외부-링크 "외부 링크에 대한 직접 링크") ``` [링크 텍스트](https://example.com) ``` *** ## 💻 코드 블록 (Code Blocks)[​](#-코드-블록-code-blocks "💻 코드 블록 (Code Blocks)에 대한 직접 링크") ### 인라인 코드[​](#인라인-코드 "인라인 코드에 대한 직접 링크") ``` `status`, `property_id`, `GET`, `POST` ``` ### 코드 블록[​](#코드-블록 "코드 블록에 대한 직접 링크") ```` ```json { "status": "success", "data": { "property_id": "PROP001" } } ``` ```` **지원 언어:** * `json` - JSON 데이터 * `javascript` - JavaScript 코드 * `python` - Python 코드 * `http` - HTTP 요청/응답 * `bash` - Shell 명령어 *** ## 📈 다이어그램 (Mermaid)[​](#-다이어그램-mermaid "📈 다이어그램 (Mermaid)에 대한 직접 링크") 시퀀스 다이어그램으로 프로세스를 시각화합니다. ```` ```mermaid sequenceDiagram participant ONDA Hub participant Vendor ONDA Hub->>Vendor: API 요청 Vendor->>ONDA Hub: 응답 ``` ```` **결과:** ### 다이어그램 작성 규칙[​](#다이어그램-작성-규칙 "다이어그램 작성 규칙에 대한 직접 링크") * ✅ Participant 이름은 `ONDA Hub`, `Vendor`, `Channel` 사용 * ✅ 화살표는 명확한 방향 표시: `->>`, `-->` * ✅ Note로 섹션 구분: `Note over ONDA Hub,Vendor: 설명` * ✅ Rect로 그룹화: `rect rgb(240, 240, 255)` *** ## ✅ 체크리스트 표시[​](#-체크리스트-표시 "✅ 체크리스트 표시에 대한 직접 링크") ``` - ✅ 완료된 항목 - ❌ 미완료 항목 ``` *** ## 🎨 용어 통일[​](#-용어-통일 "🎨 용어 통일에 대한 직접 링크") ### API 관련 용어[​](#api-관련-용어 "API 관련 용어에 대한 직접 링크") | 용어 | 올바른 표기 | 잘못된 표기 | | ----------- | --------------------------------------- | -------------------------- | | ONDA Hub | `ONDA Hub` | 온다 시스템, ONDA 시스템 | | Vendor | `Vendor` | 벤더 시스템, 공급사 시스템 | | Channel | `Channel` | 채널 시스템 | | API | `API` | api, Api | | HTTP 메소드 | `GET`, `POST`, `PUT`, `PATCH`, `DELETE` | Get, post | ### 상태값 표기[​](#상태값-표기 "상태값 표기에 대한 직접 링크") ``` `pending`, `confirmed`, `canceled` ``` ### 날짜 형식[​](#날짜-형식 "날짜 형식에 대한 직접 링크") ``` - 문서 날짜: 2024년 8월 (또는 24년 8월) - API 타임스탬프: `2024-09-26T15:30:00Z` ``` *** ## 📐 문서 구조 템플릿[​](#-문서-구조-템플릿 "📐 문서 구조 템플릿에 대한 직접 링크") ### 가이드 문서[​](#가이드-문서 "가이드 문서에 대한 직접 링크") ``` --- id: document-id title: "문서 제목" description: "문서 설명" sidebar_label: "사이드바 레이블" sidebar_position: 1 hide_title: false custom_edit_url: null --- # 문서 제목 간단한 소개를 작성합니다. ## 개요 상세한 설명을 작성합니다. ## 주요 기능 ### 기능 1 설명 ### 기능 2 설명 ## 예시 코드나 다이어그램을 포함합니다. ## 다음 단계 관련 문서 링크를 제공합니다. ``` *** ## 🚫 피해야 할 것들[​](#-피해야-할-것들 "🚫 피해야 할 것들에 대한 직접 링크") ### ❌ 잘못된 예시[​](#-잘못된-예시 "❌ 잘못된 예시에 대한 직접 링크") ``` # 너무 많은!!! 느낌표!! ## 이모지 남용 🎉🎊✨💯 ### 불필요한 **강조** ***남용*** ``` ### ✅ 올바른 예시[​](#-올바른-예시 "✅ 올바른 예시에 대한 직접 링크") ``` # 명확한 제목 ## 적절한 강조 사용 ### 필요한 경우만 **강조** ``` *** ## 📚 참고 자료[​](#-참고-자료 "📚 참고 자료에 대한 직접 링크") * [Docusaurus 마크다운 가이드](https://docusaurus.io/docs/markdown-features) * [Mermaid 문서](https://mermaid.js.org/) * [MDX 문서](https://mdxjs.com/) *** **마지막 업데이트:** 2024년 9월 이 스타일 가이드를 따라 일관성 있고 읽기 쉬운 문서를 작성해 주세요. ---