ONDA Developers

SDK

다양한 언어의 공식 SDK를 제공합니다.

SDK#

ONDA API를 쉽게 사용할 수 있도록 다양한 프로그래밍 언어의 공식 SDK를 제공합니다.

Python SDK#

설치

pip install onda-python

빠른 시작#

from onda import OndaClient

# 클라이언트 초기화
client = OndaClient(
    client_id="YOUR_CLIENT_ID",
    client_secret="YOUR_CLIENT_SECRET",
    environment="production"  # 또는 "sandbox"
)

# 숙소 검색
properties = client.properties.list(
    city="서울",
    star_rating_min=4,
    limit=10
)

for prop in properties:
    print(f"{prop.name} - {prop.star_rating}성급")

# 빈방 검색
availability = client.search.availability(
    check_in="2026-02-15",
    check_out="2026-02-16",
    adults=2,
    city="서울"
)

for result in availability:
    print(f"{result.property_name}: {result.lowest_rate.amount:,}원")

# 예약 생성
reservation = client.reservations.create(
    property_id="prop_123456",
    roomtype_id="room_123",
    rateplan_id="plan_789",
    check_in="2026-02-15",
    check_out="2026-02-16",
    adults=2,
    guest={
        "first_name": "홍",
        "last_name": "길동",
        "email": "hong@example.com",
        "phone": "+82-10-1234-5678",
        "country": "KR"
    }
)

print(f"예약 번호: {reservation.confirmation_number}")

고급 사용법#

# 자동 재시도 및 백오프
client = OndaClient(
    client_id="YOUR_CLIENT_ID",
    client_secret="YOUR_CLIENT_SECRET",
    max_retries=3,
    timeout=30
)

# 비동기 지원
import asyncio
from onda import AsyncOndaClient

async def search_properties():
    async with AsyncOndaClient(
        client_id="YOUR_CLIENT_ID",
        client_secret="YOUR_CLIENT_SECRET"
    ) as client:
        properties = await client.properties.list(city="서울")
        return properties

properties = asyncio.run(search_properties())

# 웹훅 서명 검증
from onda.webhooks import verify_signature

is_valid = verify_signature(
    payload=request.body,
    signature=request.headers["X-ONDA-Signature"],
    secret="YOUR_WEBHOOK_SECRET"
)

문서: https://github.com/onda-me/onda-python

Node.js SDK#

설치

npm install @onda/node-sdk
# 또는
yarn add @onda/node-sdk

빠른 시작#

const { OndaClient } = require("@onda/node-sdk");

// 클라이언트 초기화
const client = new OndaClient({
  clientId: "YOUR_CLIENT_ID",
  clientSecret: "YOUR_CLIENT_SECRET",
  environment: "production", // 또는 "sandbox"
});

// 숙소 검색
const properties = await client.properties.list({
  city: "서울",
  starRatingMin: 4,
  limit: 10,
});

properties.forEach((prop) => {
  console.log(`${prop.name} - ${prop.starRating}성급`);
});

// 빈방 검색
const availability = await client.search.availability({
  checkIn: "2026-02-15",
  checkOut: "2026-02-16",
  adults: 2,
  city: "서울",
});

availability.forEach((result) => {
  console.log(
    `${result.propertyName}: ${result.lowestRate.amount.toLocaleString()}원`
  );
});

// 예약 생성
const reservation = await client.reservations.create({
  propertyId: "prop_123456",
  roomtypeId: "room_123",
  rateplanId: "plan_789",
  checkIn: "2026-02-15",
  checkOut: "2026-02-16",
  adults: 2,
  guest: {
    firstName: "홍",
    lastName: "길동",
    email: "hong@example.com",
    phone: "+82-10-1234-5678",
    country: "KR",
  },
});

console.log(`예약 번호: ${reservation.confirmationNumber}`);

TypeScript 지원#

import { OndaClient, Property, Reservation } from "@onda/node-sdk";

const client = new OndaClient({
  clientId: process.env.ONDA_CLIENT_ID!,
  clientSecret: process.env.ONDA_CLIENT_SECRET!,
});

const properties: Property[] = await client.properties.list({ city: "서울" });

const reservation: Reservation = await client.reservations.create({
  propertyId: "prop_123456",
  roomtypeId: "room_123",
  rateplanId: "plan_789",
  checkIn: "2026-02-15",
  checkOut: "2026-02-16",
  adults: 2,
  guest: {
    firstName: "홍",
    lastName: "길동",
    email: "hong@example.com",
    phone: "+82-10-1234-5678",
    country: "KR",
  },
});

웹훅 미들웨어 (Express)#

const { webhookMiddleware } = require("@onda/node-sdk");

app.post(
  "/webhooks/onda",
  webhookMiddleware({ secret: process.env.WEBHOOK_SECRET }),
  (req, res) => {
    const event = req.body;

    switch (event.event) {
      case "reservation.created":
        handleReservationCreated(event.data);
        break;
      case "reservation.cancelled":
        handleReservationCancelled(event.data);
        break;
    }

    res.json({ status: "ok" });
  }
);

문서: https://github.com/onda-me/onda-node

Java SDK#

설치 (Maven)#

<dependency>
    <groupId>me.onda</groupId>
    <artifactId>onda-java-sdk</artifactId>
    <version>1.0.0</version>
</dependency>

설치 (Gradle)#

implementation 'me.onda:onda-java-sdk:1.0.0'

빠른 시작#

import me.onda.OndaClient;
import me.onda.models.*;
import java.util.List;

// 클라이언트 초기화
OndaClient client = new OndaClient.Builder()
    .clientId("YOUR_CLIENT_ID")
    .clientSecret("YOUR_CLIENT_SECRET")
    .environment(Environment.PRODUCTION)
    .build();

// 숙소 검색
ListPropertiesRequest request = ListPropertiesRequest.builder()
    .city("서울")
    .starRatingMin(4)
    .limit(10)
    .build();

List<Property> properties = client.properties().list(request);

for (Property prop : properties) {
    System.out.printf("%s - %d성급%n", prop.getName(), prop.getStarRating());
}

// 예약 생성
CreateReservationRequest reservationRequest = CreateReservationRequest.builder()
    .propertyId("prop_123456")
    .roomtypeId("room_123")
    .rateplanId("plan_789")
    .checkIn(LocalDate.of(2026, 2, 15))
    .checkOut(LocalDate.of(2026, 2, 16))
    .adults(2)
    .guest(Guest.builder()
        .firstName("홍")
        .lastName("길동")
        .email("hong@example.com")
        .phone("+82-10-1234-5678")
        .country("KR")
        .build())
    .build();

Reservation reservation = client.reservations().create(reservationRequest);

System.out.printf("예약 번호: %s%n", reservation.getConfirmationNumber());

비동기 지원#

import me.onda.AsyncOndaClient;
import java.util.concurrent.CompletableFuture;

AsyncOndaClient asyncClient = new AsyncOndaClient.Builder()
    .clientId("YOUR_CLIENT_ID")
    .clientSecret("YOUR_CLIENT_SECRET")
    .build();

CompletableFuture<List<Property>> future = asyncClient.properties()
    .listAsync(request);

future.thenAccept(properties -> {
    properties.forEach(prop -> {
        System.out.println(prop.getName());
    });
});

문서: https://github.com/onda-me/onda-java

PHP SDK#

설치 (Composer)#

composer require onda/onda-php

빠른 시작#

<?php

require_once 'vendor/autoload.php';

use Onda\OndaClient;

// 클라이언트 초기화
$client = new OndaClient([
    'client_id' => 'YOUR_CLIENT_ID',
    'client_secret' => 'YOUR_CLIENT_SECRET',
    'environment' => 'production' // 또는 'sandbox'
]);

// 숙소 검색
$properties = $client->properties->list([
    'city' => '서울',
    'star_rating_min' => 4,
    'limit' => 10
]);

foreach ($properties as $prop) {
    echo "{$prop->name} - {$prop->star_rating}성급\n";
}

// 예약 생성
$reservation = $client->reservations->create([
    'property_id' => 'prop_123456',
    'roomtype_id' => 'room_123',
    'rateplan_id' => 'plan_789',
    'check_in' => '2026-02-15',
    'check_out' => '2026-02-16',
    'adults' => 2,
    'guest' => [
        'first_name' => '홍',
        'last_name' => '길동',
        'email' => 'hong@example.com',
        'phone' => '+82-10-1234-5678',
        'country' => 'KR'
    ]
]);

echo "예약 번호: {$reservation->confirmation_number}\n";

웹훅 처리#

<?php

use Onda\Webhook;

$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_ONDA_SIGNATURE'];
$secret = 'YOUR_WEBHOOK_SECRET';

if (!Webhook::verify($payload, $signature, $secret)) {
    http_response_code(401);
    exit('Invalid signature');
}

$event = json_decode($payload);

switch ($event->event) {
    case 'reservation.created':
        handleReservationCreated($event->data);
        break;
    case 'reservation.cancelled':
        handleReservationCancelled($event->data);
        break;
}

http_response_code(200);
echo json_encode(['status' => 'ok']);

문서: https://github.com/onda-me/onda-php

공통 기능#

모든 SDK는 다음 기능을 지원합니다:

  • ✅ 자동 OAuth 2.0 토큰 관리
  • ✅ 자동 토큰 갱신
  • ✅ 재시도 및 지수 백오프
  • ✅ Rate limiting 처리
  • ✅ 웹훅 서명 검증
  • ✅ 타입 안전성 (TypeScript, Java)
  • ✅ 에러 처리 및 커스텀 예외
  • ✅ 로깅 및 디버깅 모드

지원 및 기여#

SDK에 대한 문의사항이나 버그 리포트는 각 SDK의 GitHub 저장소에 이슈를 등록해주세요.

커뮤니티 기여를 환영합니다! Pull Request를 보내주시면 검토 후 반영하겠습니다.

다음 단계#