본문으로 건너뛰기

공통 · 개요

Vendor API 3.0 연동을 시작하기 전에 전체 구조와 준비 항목을 확인합니다.

엔드포인트 총괄

HUB API 38개 + 공급사 API(Webhook) 5개 = 총 43개

HUB API 메서드 규칙: 생성 POST · 수정 PATCH · 조회 GET, 성공 응답 200 OK

공급사 API는 동작에 따라 메서드가 다릅니다. 예약 확정·변경은 PUT, 예약 생성·취소는 POST, 정책 조회는 GET입니다.

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_typehubcms
한 줄 정의ONDA와 한 번 계약하면 ONDA에 연결된 채널 전체에 판매숙소가 OTA와 직접 계약하고 채널을 직접 운영
채널 등록·운영·정산ONDA가 대행숙소가 직접

단계별로 누가 처리하나요?​

처리 항목플러스 채널직연동 채널
요금 · 재고 동기화ONDAONDA
채널 계약ONDA숙소가 직접
입점 · 정보 배포ONDA숙소가 직접
정산 · 회계ONDA숙소가 직접
예약 확정 방식ONDA가 유효성 검사 후 확정검사 없이 즉시 생성

요금·재고 동기화는 두 유형 모두 ONDA를 거칩니다. 공급사가 구현할 콘텐츠·ARI 전송 코드는 채널 유형과 무관하게 동일합니다.

플러스 채널 — 계약부터 정산까지 ONDA를 거칩니다.

직연동 채널 — 요금·재고만 ONDA를 거치고, 계약·정산은 숙소가 채널과 직접 진행합니다.

API에서는 무엇이 달라지나요?​

항목플러스 채널직연동 채널
채널 오픈신청만 하면 됨 — 플러스 채널 오픈매핑 사전 단계 · 채널 설정 · 매핑이 필요 — 직연동 레거시 채널 오픈
매핑 API사용하지 않음 (ONDA가 관리)PATCH .../mappings 필수
채널별 부가 설정사용하지 않음PATCH .../settings 사용
예약 유효성 검사ONDA · 공급사 각자 수행없음 — 무조건 수용
예약 변경(modify)Soft Change만 허용Soft · Hard Change 모두
상품 typeovernightovernight (대실을 지원하는 채널은 dayuse 추가)
채널 유형은 채널마다 다릅니다

숙소 단위가 아니라 채널 단위로 정해집니다. 한 숙소가 어떤 채널은 플러스로, 어떤 채널은 직연동으로 운영할 수 있습니다. GET /gds/vendor/channels 응답의 channel_type으로 확인하세요.

숙소 운영자 관점의 설명은 ONDA Plus 채널 매니저 소개에서 볼 수 있습니다.

연동 라이프사이클​

연동 준비 체크리스트​

  • HUB API 호출용 베이스 URL 확정 및 환경(스테이징·운영) 분리
  • 공급사 API(Webhook) 수신 서버 엔드포인트 및 베이스 URL 제공
  • 인증: HUB API 호출 시 Authorization 헤더에 Vendor access token 적용
  • 인증: 공급사 API 수신 시 ONDA 요청에 대한 토큰·서명 검증 로직 구현
  • 코드 카탈로그 조회 후 코드 매핑 테이블 내재화

출시 전 통합 검증​

  • 최초 동기화 E2E: 숙소 → 객실타입 → 요금제 모델 → 요금제 생성 후 요금·영업일·재고 Push까지 채널 반영 확인
  • 플러스 채널 오픈 → 예약 발생 → 확정 → 취소 전체 플로우 검증
  • 직연동 채널(레거시·OAuth) 매핑 → ON 신청 → 예약 플로우 검증
  • 인증 토큰 만료·갱신 및 오류 응답(4xx·5xx) 처리 검증
  • 멱등성·재시도 정책(중복 예약·중복 취소 방지) 검증
  • 스테이징 검증 완료 후 운영 전환 사인오프

운영 · 비즈니스 로직 확인​

API 구현과 별개로, 라이브 전 ONDA와 협의·확인해야 하는 항목입니다. 📘 표기 항목은 별도 가이드로 정리돼 있습니다.

분류항목확인 내용
콘텐츠·언어다국어 콘텐츠 사용 여부한국어 외 언어 사용 여부. 사용 시 전송 방법 협의
콘텐츠·언어숙소명·숙소 소개 특수문자표기 불가 특수문자 제외 처리
콘텐츠·언어객실명·객실 설명 특수문자표기 불가 특수문자 제외 처리
판매범위·상품판매 숙소 범위해외 숙소 판매 / 국내만 판매 여부
판매범위·상품상품 구성객실 단위 vs 객실별 패키지(요금제) 판매 여부
요금·재고추가인원 요금추가인원 요금 전송 가능 여부
요금·재고요금재고 전송 기간몇 개월치 전송 가능한지
예약구조·유효성예약 번호 구조 인지 📘1 gds_booking_number : N gds_sub_booking_number. 공급사 예약은 gds_sub_booking_number 기준 생성
예약구조·유효성플러스 채널 예약 유효성 검사재고·요금 일치·판매상태 활성 등 검사 수행
취소·환불일자별 취소환불 정책 📘날짜별 정책 상이 여부 확인 (취소환불 정책)
바우처예약 바우처 발송확정·취소 바우처를 공급사가 숙소에 직접 발송

예약 번호 구조​

필드설명
gds_booking_numberONDA Hub 예약 번호
gds_sub_booking_numberONDA Hub 서브 예약 번호. 공급사 예약은 이 값 기준으로 생성
channel_booking_number판매 채널 예약 번호

gds_booking_number 1건에 gds_sub_booking_number N건이 대응하며, 공급사의 booking_number와 gds_sub_booking_number는 1:1입니다.