연동 아키텍처

ONDA API 시스템 구조와 데이터 흐름을 설명합니다

ONDA Platform Engineering 관리

연동 아키텍처

ONDA Channel API의 전체 시스템 구조, 계층, 데이터 흐름, 인증 방식을 이해하면 효율적인 연동 설계가 가능합니다.

시스템 구조 개요

계층 구조

ONDA 개발자 포털은 다음 계층으로 관리됩니다:

Developer Account (개발자 계정 / 조직)
    └── App (등록된 앱)
        ├── API Key (X-Api-Key 인증)
        └── Client ID / Secret (OAuth 2.0 인증)

1. Developer Account

• 개발자 포털에 가입한 계정
• 여러 앱을 등록하고 관리할 수 있습니다
• 보증금·정산·사용량을 계정 단위로 관리합니다

2. App

• 자격 증명과 권한(scope)의 단위입니다
• 환경(Sandbox/Production)별로 구분하여 사용합니다

3. 등급 (Tier)

• Sandbox: 개발/테스트 전용, 무료, Mock 데이터, 60 req/min
• Starter: 운영 환경, 보증금 + 월 구독, 600 req/min

자세한 조건은 채널 등급을 참고하세요.

데이터 흐름

콘텐츠 데이터 (캐싱 가능)

숙소/객실/요금제 메타데이터는 변경 빈도가 낮아 로컬 캐싱(권장 TTL 24시간)이 가능합니다.

• GET /properties, GET /properties/{id} - 숙소 목록/상세
• GET /properties/{id}/roomtypes - 객실 타입
• GET /properties/{id}/rateplans - 요금제
• GET /content/files/content, GET /content/files/catalog - 콘텐츠 파일 다운로드 URL 발급 (벌크 동기화용)

트랜잭션 데이터 (실시간 API)

가격·재고·예약은 사용자 요청 시마다 실시간으로 조회합니다:

1. 사용자가 검색 조건 입력 (날짜, 인원)
2. GET /search/availability → 가용 숙소 목록
3. GET /search/availability/{propertyId} → 객실·요금 + price_check_token
4. GET /search/price-check?token=... → 실시간 가격 재확인 + book_token
5. POST /bookings (book_token) → 예약 확정

인증 흐름

ONDA Channel API는 두 가지 인증 방식을 지원합니다:

API Key 인증

개발자 포털에서 발급받은 API 키를 매 요청의 X-Api-Key 헤더에 포함합니다. 별도의 토큰 발급 절차가 없어 가장 간단합니다.

OAuth 2.0 Client Credentials

POST /oauth/token으로 Access Token을 발급받아 사용합니다.

응답 (Access Token은 JWT가 아닌 불투명 토큰입니다):

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

두 방식 모두 scope 기반 접근 제어(deny-by-default)가 적용됩니다. 필요한 scope가 없으면 403 SCOPE_DENIED가 반환됩니다.

API 호출 흐름 (전체)

사용자가 숙소를 검색하고 예약하는 전체 플로우입니다:

예약 상태 변경(생성/수정/취소/노쇼)은 웹훅 4종(reservation.created/modified/cancelled/no_show)으로 실시간 수신할 수 있습니다.

환경 구분

ONDA는 개발과 운영 환경을 분리하여 안전한 테스트를 지원합니다.

Sandbox 특징

• 무료 사용, 과금 없음
• Mock 숙소·예약 데이터
• Rate Limit: 60 req/min

Production 특징

• 실제 숙소 데이터 (54,000+ 숙박 상품)
• 실시간 재고/가격 확인
• 실제 예약 처리 및 정산
• Rate Limit: 600 req/min (Starter)

보안 고려사항

1. 자격 증명 관리

• client_secret과 API Key는 서버 사이드에서만 사용
• 프론트엔드(JavaScript)에 노출 금지
• 환경 변수로 관리 (.env 파일)

2. HTTPS 통신

• 모든 API 호출은 HTTPS로만 가능
• HTTP 요청은 거부됩니다

3. Rate Limiting

• Sandbox: 60 req/min · Starter(운영): 600 req/min
• 응답 헤더 X-RateLimit-Limit / X-RateLimit-Remaining / X-RateLimit-Reset으로 잔여량 확인
• 초과 시 429 RATE_LIMIT_EXCEEDED

4. 웹훅 서명 검증

• 모든 웹훅 요청은 HMAC-SHA256 서명(X-ONDA-Signature)을 포함합니다 — 반드시 검증하세요

다음 단계