ONDA → Vendor Request

온다에서 벤더(숙박업체) 시스템으로 데이터를 요청하는 Pull 방식의 연동 가이드입니다.

개요

ONDA → Vendor Request 방식은 온다 시스템이 벤더의 API를 직접 호출하여 최신 정보를 획득하는 연동 방식입니다.

특징

• 실시간 데이터 획득: 온다가 필요한 시점에 벤더 시스템에서 최신 데이터 조회
• Pull 방식: 온다가 능동적으로 데이터를 요청
• 즉시성: 실시간으로 최신 정보 확인 가능
• 신뢰성: 벤더 시스템을 직접 조회하여 정확한 정보 획득

연동 흐름

주요 API 엔드포인트

벤더 시스템(공급사가 직접 구축·호스팅하는 서버)에서 구현해야 하는 API들입니다. 스펙상 서버 주소는 https://vendor.dapi.tport.dev로 표기되어 있으나, 이는 실제로는 공급사가 지정한 자체 서버 URL을 나타내는 placeholder입니다. 상세 파라미터와 스키마는 각 링크의 API 레퍼런스에서 확인할 수 있습니다.

숙소 생성 API

Method	Endpoint	설명
GET	/properties	공급사 전체 숙소 목록 조회
GET	/properties/{vendor_property_id}	숙소 상세 정보 조회
GET	/properties/{vendor_property_id}/roomtypes	객실 목록 조회
GET	.../roomtypes/{vendor_roomtype_id}	객실 상세(+요금제) 조회
GET	.../rateplans/{vendor_rateplan_id}/avails	일자별 재고 조회
GET	.../rateplans/{vendor_rateplan_id}/rates	일자별 요금 조회

숙소 정보 관리 (Sync) API

lastdate 쿼리 파라미터를 기준으로 변경분만 주기적으로 조회합니다. 호출 주기는 온다 기술 담당 매니저와 협의합니다.

Method	Endpoint	설명
GET	/sync/properties	변경된 숙소 목록 조회
GET	/sync/roomtypes	변경된 객실 목록 조회
GET	/sync/avails	재고 변경분 조회
GET	/sync/rates	요금 변경분 조회

예약 API

Method	Endpoint	설명
GET	.../refund_policy	예약 전 환불 정책 체크
POST	/bookings	예약 생성 (재고 확보, pending 상태)
PUT	/bookings/{vendor_booking_number}/confirm	예약 확정 (15분 내 미확정 시 자동 취소)
PUT	/bookings/{vendor_booking_number}/modify	예약 정보 수정
POST	/bookings/{vendor_booking_number}/cancel	예약 취소
GET	/bookings/{vendor_booking_number}	예약 조회

인증 및 보안

이 방향(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 엔드포인트 구현

위 엔드포인트 표를 참고하여 벤더 시스템에서 온다가 호출할 API 엔드포인트를 구현해야 합니다.

2. 데이터 포맷 준수

온다 시스템과 호환되는 데이터 포맷으로 응답해야 합니다.

3. 에러 핸들링

적절한 HTTP 상태 코드와 에러 메시지를 제공해야 합니다.

4. 성능 최적화

• 응답 시간 최소화 (권장: 3초 이내)
• 캐싱 활용으로 성능 향상
• 대용량 데이터의 경우 페이징 처리

테스트 가이드

1. 개발 환경 테스트

• 온다 테스트 서버에서 벤더 개발 API 호출
• 기본적인 API 응답 확인
• 데이터 포맷 검증

2. 통합 테스트

• 실제 데이터를 사용한 통합 테스트
• 성능 및 안정성 검증
• 에러 시나리오 테스트

3. 운영 전 검증

• 운영 환경 설정 확인
• 모니터링 도구 설정
• 장애 대응 절차 확인

모니터링 및 운영

로그 관리

• API 호출 로그 기록
• 에러 로그 모니터링
• 성능 지표 추적

알람 설정

• API 응답 시간 지연 알람
• 에러율 증가 알람
• 시스템 장애 알람

---

다음: Vendor → ONDA Request 방식 가이드