첫 API 호출

OAuth 인증 후 첫 번째 API를 호출해보세요.

ONDA Platform Engineering 관리

첫 API 호출

발급받은 API 자격 증명을 사용하여 첫 번째 API를 호출해보겠습니다.

Step 1: Access Token 발급

OAuth 2.0 Client Credentials 플로우를 사용하여 Access Token을 발급받습니다.

응답 예시:

Access Token은 oat_ 접두사를 가진 불투명(opaque) 토큰입니다.

{
  "access_token": "oat_3f9a2c5e8b1d4f7a9c0e2b6d8f1a3c5e7b9d0f2a4c6e8b0d1f3a5c7e9b1d3f5a",
  "token_type": "bearer",
  "expires_in": 1800,
  "scope": "properties:read reservations:write"
}

Step 2: 숙소 목록 조회

발급받은 Access Token을 사용하여 숙소 목록을 조회합니다.

Step 3: 응답 확인

API 호출이 성공하면 다음과 같은 응답을 받습니다:

{
  "data": [
    {
      "id": "prop_123456",
      "name": "서울 센트럴 호텔",
      "type": "hotel",
      "star_rating": 5,
      "city": "서울",
      "district": "강남구",
      "address": "서울특별시 강남구 테헤란로 123",
      "latitude": 37.5012,
      "longitude": 127.0396,
      "description": "강남 중심부에 위치한 5성급 비즈니스 호텔",
      "amenities": ["wifi", "parking", "breakfast", "gym", "pool"],
      "images": [
        {
          "url": "https://cdn.onda.me/properties/prop_123456/main.jpg",
          "type": "main",
          "caption": "호텔 전경"
        }
      ],
      "check_in_time": "15:00",
      "check_out_time": "11:00"
    }
    // ... 더 많은 숙소
  ],
  "meta": {
    "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "timestamp": "2026-05-31T09:00:00.000Z"
  }
}

에러 처리 기본

API 호출 시 발생할 수 있는 주요 에러:

401 Unauthorized

{
  "error": "invalid_client",
  "error_description": "Invalid client credentials"
}

해결 방법: Client ID/Secret을 확인하거나, 만료된 Access Token이면 다시 발급받으세요.

400 Bad Request

{
  "error": "invalid_request",
  "error_description": "client_id and client_secret are required"
}

해결 방법: 요청 파라미터를 확인하고 누락된 필수 값을 추가하세요.

429 Too Many Requests

토큰 발급 엔드포인트는 IP당 60초에 20회로 제한됩니다. API 호출은 등급(tier)별 분당 요청 한도가 적용됩니다 (sandbox 60건/분).

{
  "error": "rate_limit_exceeded",
  "error_description": "Too many requests"
}

해결 방법: 잠시 후 재시도하세요.

다음 단계

축하합니다! 첫 API 호출에 성공하셨습니다. 이제 다음 내용을 학습해보세요:

• OAuth 2.0 인증 - 토큰 발급 및 보안 가이드
• 콘텐츠 연동 - 숙소, 객실, 패키지 정보 동기화
• 실시간 검색 - 빈방 및 가격 검색
• 예약 관리 - 예약 생성 및 관리

전체 예제 코드

전체 플로우를 구현한 예제 코드:

전체 예제 (Python)

import requests

class OndaAPI:
    def __init__(self, client_id, client_secret,
                 base_url="https://sandbox.api.tport.dev/channel/v1"):
        self.client_id = client_id
        self.client_secret = client_secret
        self.base_url = base_url
        self.access_token = None

    def get_access_token(self):
        """Access Token 발급"""
        response = requests.post(
            f"{self.base_url}/oauth/token",
            data={
                "grant_type": "client_credentials",
                "client_id": self.client_id,
                "client_secret": self.client_secret,
            },
        )
        response.raise_for_status()
        self.access_token = response.json()["access_token"]
        return self.access_token

    def get_properties(self):
        """숙소 목록 조회"""
        if not self.access_token:
            self.get_access_token()

        headers = {
            "Authorization": f"Bearer {self.access_token}",
            "Accept": "application/json",
        }

        response = requests.get(
            f"{self.base_url}/properties",
            headers=headers,
        )
        response.raise_for_status()
        return response.json()

# 사용 예시
api = OndaAPI(
    client_id="YOUR_CLIENT_ID",
    client_secret="YOUR_CLIENT_SECRET"
)

properties = api.get_properties()
print(f"총 {len(properties['data'])}개 숙소 조회됨")
for prop in properties['data']:
    print(f"- {prop['name']} (⭐ {prop['star_rating']}성급)")