본문으로 건너뛰기

Vendor → ONDA Request

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

개요​

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

특징​

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

연동 흐름​

주요 API 엔드포인트​

벤더에서 호출하는 온다 API들:

1. 숙소 정보 업데이트​

  • 엔드포인트: PUT /api/v1/properties/{property_id}
  • 목적: 숙소 기본 정보, 편의시설, 이미지 업데이트
  • 호출 시점: 숙소 정보 변경시
  • 요청 데이터: 변경된 숙소 정보

2. 객실 정보 업데이트​

  • 엔드포인트: PUT /api/v1/properties/{property_id}/rooms/{room_id}
  • 목적: 객실 타입, 상세 정보, 편의시설 업데이트
  • 호출 시점: 객실 정보 변경시
  • 요청 데이터: 변경된 객실 정보

3. 요금 정보 업데이트​

  • 엔드포인트: POST /api/v1/rates/bulk-update
  • 목적: 객실별 요금, 할인 정보, 취소 정책 업데이트
  • 호출 시점: 요금 변경시 또는 주기적
  • 요청 데이터: 기간별 요금 정보

4. 재고 정보 업데이트​

  • 엔드포인트: POST /api/v1/inventory/bulk-update
  • 목적: 객실별 재고, 예약 제한 정보 업데이트
  • 호출 시점: 재고 변경시 또는 실시간
  • 요청 데이터: 일자별 재고 정보

인증 및 보안​

API 인증​

  • 방식: Bearer Token 인증
  • 헤더: Authorization: Bearer {ACCESS_TOKEN}
  • 토큰 갱신: 만료 전 자동 갱신 필요

토큰 획득​

POST /api/v1/auth/token
Content-Type: application/json

{
  "client_id": "your_client_id",
  "client_secret": "your_client_secret",
  "grant_type": "client_credentials"
}

보안 요구사항​

  • HTTPS 필수: 모든 API 호출은 HTTPS 사용
  • 토큰 관리: 토큰 안전한 저장 및 주기적 갱신
  • 요청 제한: Rate limiting 준수 (시간당 1000회)

요청 포맷​

모든 API 요청은 JSON 형식을 사용합니다:

{
  "timestamp": "2024-09-26T15:30:00Z",
  "data": {
    // 실제 업데이트 데이터
  },
  "metadata": {
    "source": "vendor_system",
    "version": "1.0"
  }
}

숙소 정보 업데이트 예시​

{
  "timestamp": "2024-09-26T15:30:00Z",
  "data": {
    "property_id": "PROP001",
    "name": "호텔 온다",
    "description": "서울 중심가에 위치한 비즈니스 호텔",
    "amenities": ["wifi", "parking", "breakfast"],
    "images": [
      {
        "url": "https://example.com/image1.jpg",
        "type": "exterior",
        "order": 1
      }
    ]
  }
}

응답 처리​

성공 응답​

{
  "status": "success",
  "message": "데이터가 성공적으로 업데이트되었습니다",
  "data": {
    "updated_at": "2024-09-26T15:30:05Z",
    "affected_records": 1
  }
}

에러 응답​

{
  "status": "error",
  "error_code": "VALIDATION_ERROR",
  "message": "요청 데이터 검증에 실패했습니다",
  "details": [
    {
      "field": "property_id",
      "error": "필수 필드입니다"
    }
  ]
}

개발 가이드​

1. SDK 사용 (권장)​

온다에서 제공하는 SDK를 사용하여 쉽게 연동할 수 있습니다:

// Node.js SDK 예시
const OndaSDK = require('@onda/vendor-sdk');

const client = new OndaSDK({
  clientId: 'your_client_id',
  clientSecret: 'your_client_secret',
  environment: 'production' // or 'sandbox'
});

// 숙소 정보 업데이트
await client.properties.update('PROP001', {
  name: '호텔 온다',
  description: '업데이트된 설명'
});

2. 직접 API 호출​

SDK를 사용할 수 없는 경우 직접 HTTP 요청:

# Python 예시
import requests
import json

def update_property(property_id, data):
    headers = {
        'Authorization': f'Bearer {access_token}',
        'Content-Type': 'application/json'
    }

    response = requests.put(
        f'https://api.onda.kr/v1/properties/{property_id}',
        headers=headers,
        data=json.dumps(data)
    )

    return response.json()

3. 배치 처리​

대량의 데이터를 효율적으로 처리하기 위한 배치 API 사용:

{
  "batch_id": "BATCH001",
  "operations": [
    {
      "operation": "update",
      "resource": "property",
      "id": "PROP001",
      "data": { /* 업데이트 데이터 */ }
    },
    {
      "operation": "update",
      "resource": "room",
      "id": "ROOM001",
      "data": { /* 업데이트 데이터 */ }
    }
  ]
}

에러 핸들링​

재시도 로직​

네트워크 오류나 일시적 장애에 대비한 재시도 메커니즘:

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); // 지수 백오프
    }
  }
}

에러 코드별 처리​

  • 401 Unauthorized: 토큰 재발급 필요
  • 429 Too Many Requests: 요청 제한 초과, 잠시 대기
  • 422 Unprocessable Entity: 데이터 유효성 검사 실패
  • 500 Internal Server Error: 서버 오류, 재시도 후 지원팀 연락

모니터링 및 로깅​

로그 기록​

// 로그 예시
{
  "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 방식 가이드