본문으로 건너뛰기

Vendor → ONDA Request

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

개요​

Vendor → ONDA Request 방식은 벤더 시스템에서 온다 API를 호출하여 데이터를 업데이트하는 연동 방식입니다.

특징​

  • 능동적 업데이트: 벤더가 변경사항 발생시 즉시 온다 시스템에 전송
  • Push 방식: 벤더가 능동적으로 데이터를 전송
  • 실시간 동기화: 변경사항을 실시간으로 온다에 반영
  • 효율성: 변경된 데이터만 선택적으로 전송 가능

연동 흐름​

주요 API 엔드포인트​

벤더에서 호출하는 온다 API들입니다. 서버 주소는 https://vendor.dapi.tport.dev/gds/vendor이며, 상세 파라미터와 스키마는 각 링크의 API 레퍼런스에서 확인할 수 있습니다.

숙소 정보 관리 (Push)​

MethodEndpoint설명
PATCH/properties/{vendor_property_id}숙소 상태 변경 (enabled/disabled)
PATCH/properties/{vendor_property_id}/roomtypes/{vendor_roomtype_id}객실 상태 변경
PATCH/properties/{vendor_property_id}/roomtypes/{vendor_roomtype_id}/rateplans/{vendor_rateplan_id}요금제 상태 변경
POST.../rateplans/{vendor_rateplan_id}/avails재고(vacancy) 변경
POST.../rateplans/{vendor_rateplan_id}/rates요금(판매가/입금가 등) 변경
POST.../rateplans/{vendor_rateplan_id}/business-days판매 여부(영업일) 변경

기타 연동​

MethodEndpoint설명
GET/propertiesHotelPlus 숙소 목록 매핑 (Authorization 헤더 필수)
GET/properties/{vendor_property_id}/roomtypesHotelPlus 객실 목록 매핑
GET/bookings정산 대사용 예약 목록 조회
GET/bookings/{vendor_booking_number}예약 정보 확인

인증 및 보안​

API 인증​

  • 방식: API Key 인증
  • 헤더: Authorization: {API_KEY}
  • ONDA 담당자를 통해 발급받은 API 키를 그대로 헤더 값으로 전달합니다. 별도의 토큰 발급(OAuth2 등) 절차는 없습니다.

보안 요구사항​

  • HTTPS 필수: 모든 API 호출은 HTTPS 사용

요청 포맷​

요청 바디는 엔드포인트마다 다르며, 공통 envelope 없이 필요한 필드만 전달합니다.

숙소 상태 변경 예시 (update-property-status)​

{
  "status": "enabled"
}

재고 변경 예시 (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)​

{
  "error": ""
}

error가 빈 문자열이면 정상 처리된 것입니다.

처리 실패 (200)​

{
  "error": "에러 메세지"
}

요청은 접수되었으나 처리에 실패한 경우에도 HTTP 상태는 그대로 200이며, 실패 사유가 error 필드에 담겨 내려옵니다.

요청 형식 오류 (400)​

파라미터 누락 등 요청 자체가 잘못된 경우 400이 반환되며, 스펙상 응답 바디는 별도로 정의되어 있지 않습니다(예시: {}).

기타 연동 4개 엔드포인트는 각자 응답 구조가 다릅니다. get-roomtype-list-hotelplus, reservation-information은 위와 같이 error 필드를 포함하지만, get-property-list-hotelplus(배열 그대로 반환)와 settlement-comparison({count, offset, limit, reservations})은 error 필드 없이 데이터를 바로 반환합니다. 상세 스키마는 각 레퍼런스 페이지를 참고하세요.

개발 가이드​

직접 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 방식 가이드