빠른 시작

이 가이드는 약 30분 만에 아무것도 없는 상태에서 작동하는 통합까지 안내합니다. 완료하면 다음을 갖게 됩니다:

Partner API를 통해 도시 내 호텔의 실시간 가격,
예약을 귀하의 계정에 적립하는 예약 링크,
테스트 예약 및 예약 발생을 알려주는 웹훅.

모든 작업은 스테이징인 테스트 환경에서 이루어집니다. 별도의 접근 권한 요청이 필요 없으며, 나중에 프로덕션으로 전환할 때도 승인 절차가 필요 없습니다.

이 가이드가 적합한가요?

하고 싶은 일	시작하기
앱, 사이트 또는 AI 제품에 호텔을 보여주고 여행자를 예약 페이지로 보내 수수료를 벌고 싶다	이 가이드
라이선스가 있는 여행사로서 고객을 대신해 예약하고 싶다	5단계까지 이 가이드, 이후 여행사로서 예약하기
통합 코딩 없이 예약 가능한 호텔을 임베드하고 싶다	웹 컴포넌트
AI 에이전트가 검색하고 예약하게 하고 싶다	MCP 서버 및 Agentic Payments
채널 매니저 또는 PMS를 연결하고 싶다	채널 매니저 추가하기

작동 방식

Partner API를 사용해 호텔과 실시간 가격을 찾습니다. 각 호텔에는 안정적인 urlName이 있습니다. 이를 Wink 예약 엔진인 book.wink.travel로 연결하는 링크로 변환하며, 귀하의 ID가 포함됩니다. 여행자가 그곳에서 예약하고 결제하면 예약이 귀하의 계정에 적립됩니다.

시작 전에

필요한 것:

grpcurl 또는 Postman, Insomnia. Partner API는 REST가 아닌 gRPC입니다.
curl.

1단계: 스테이징 계정 만들기

스테이징은 프로덕션과 완전히 분리되어 있으며, 별도의 로그인과 계정을 사용합니다.

staging-app.wink.travel로 가서 Sign-In / Register를 클릭해 등록하세요.
왼쪽 사이드바에서 Accounts를 클릭한 후 Create를 클릭하고 I am an Affiliate를 선택하세요. 귀하가 보내는 예약은 이 계정에 적립됩니다. 자세한 내용은 계정 만들기를 참조하세요.

2단계: 애플리케이션 만들기

애플리케이션은 귀하의 코드에 자격 증명을 제공합니다.

계정 카드에서 Actions > Manage account를 클릭한 후 Applications 탭으로 이동하세요.
Create new application을 클릭하고 이름을 지정한 뒤 클라이언트 유형으로 Machine-to-machine을 선택하세요.
권한 범위(scopes)에서 Inventory & rates (읽기)를 선택하세요. Partner API는 inventory.read를 확인합니다.
Create application을 클릭하고 Client ID와 Client secret을 복사하세요. 비밀 키는 한 번만 표시되며 나중에 다시 볼 수 없습니다.

다른 클라이언트 유형과 권한 범위는 Applications를 참조하세요.

3단계: 액세스 토큰 받기

curl -X POST https://staging-iam.wink.travel/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=<YOUR_CLIENT_ID>" \
  -d "client_secret=<YOUR_CLIENT_SECRET>" \
  -d "scope=inventory.read"

응답에서 access_token을 저장하세요:

export WINK_TOKEN=<access_token>

토큰은 만료됩니다. 자체 코드에서는 OAuth2 라이브러리를 사용해 토큰을 가져오고 갱신하세요. 자세한 내용은 인증을 참조하세요.

4단계: 계정 ID 찾기

모든 Partner API 호출은 managing-entity-id 헤더에 귀하가 대행하는 계정을 명시합니다. 토큰으로 액세스 가능한 계정 목록을 조회하세요:

grpcurl -H "authorization: Bearer $WINK_TOKEN" \
  -d '{}' \
  staging-partner.wink.travel:443 wink.partner.v1.Accounts/ListAccounts

1단계에서 만든 제휴 계정의 accountId를 복사하세요:

export WINK_ACCOUNT_ID=<accountId>

5단계: 도시 내 호텔 검색

grpcurl -H "authorization: Bearer $WINK_TOKEN" \
  -H "managing-entity-id: $WINK_ACCOUNT_ID" \
  -d '{
    "urlName": "bangkok-thailand",
    "userSession": {
      "itinerary": {
        "startDate": "2026-12-01",
        "nights": 2,
        "room": { "adults": 2 }
      },
      "currencyCode": "USD",
      "languageCode": "en"
    }
  }' \
  staging-partner.wink.travel:443 wink.partner.v1.Search/SearchByCity

체크인 날짜는 미래 날짜를 사용하세요; 과거 날짜는 거부됩니다. 각 결과에는 다음이 포함됩니다:

결과 행을 표시하기에 충분한 name, starRating 및 heroImageUrl,
실시간 제공 상품인 roomTypes, 가장 저렴한 방부터,
예약 링크에 필요한 슬러그인 urlName.

가격은 소수 단위가 아닌 정수로 표시됩니다: 응답의 currencyExponent(USD는 2)만큼 10의 거듭제곱으로 나누세요 (12500은 $125.00).

도시의 슬러그를 모르면 wink.partner.v1.Lookup/Search로 확인하세요. 숙소의 전체 콘텐츠는 Content 서비스를 사용하세요. 모든 호출은 Partner API 참조에 문서화되어 있습니다.

6단계: 예약 링크 만들기

https://staging-book.wink.travel/hotel/<urlName>?client-id=<YOUR_CLIENT_ID>&configuration-id=<YOUR_CUSTOMIZATION_ID>

<urlName>은 5단계에서 얻은 호텔의 urlName입니다.
client-id는 2단계에서 생성한 애플리케이션의 Client ID입니다.
configuration-id는 사용자 지정 ID입니다: Manage account > Customizations에서 확인하세요. 사용자 지정은 예약 페이지의 브랜딩, 기본 언어 및 통화도 설정합니다.

단일 호텔 대신 예약 엔진 홈 페이지로 연결하려면 직접 링크하기를 참조하세요.

7단계: 테스트 예약하기

링크를 열고 날짜와 객실을 선택한 후 Stripe 테스트 카드를 사용해 결제하세요. 예: 4242 4242 4242 4242에 미래 만료일과 아무 CVC를 입력하세요. 스테이징에서는 실제 카드가 청구되지 않습니다. 확인 페이지에서 예약 코드를 확인하세요; WNK로 시작합니다.

8단계: 예약 알림 받기

포털에서 Applications > Webhooks로 가서 POST 요청을 받는 엔드포인트를 추가하세요.
booking.create 이벤트를 구독하거나, 개발 중에는 이벤트 목록을 비워 모든 이벤트를 받으세요.
테스트 이벤트를 보내고, 다시 테스트 예약을 만들어 알림이 도착하는지 확인하세요.

모든 전달의 서명을 검증한 후 신뢰하세요. 자세한 내용은 웹훅 통합 및 웹훅 이벤트 카탈로그를 참조하세요.

9단계: 프로덕션으로 전환하기

개발자에게는 승인 절차가 없습니다. (여행사 계정은 먼저 인증됩니다; 아래 여행사로서 예약하기 참조.) 스테이징에서 통합이 작동하면:

app.wink.travel에서 1단계와 2단계처럼 계정과 애플리케이션을 만드세요. 자격 증명은 환경 간에 이전되지 않습니다.
모든 호스트에서 staging- 접두사를 제거하세요:

스테이징 프로덕션
https://staging-iam.wink.travel https://iam.wink.travel
staging-partner.wink.travel:443 partner.wink.travel:443
https://staging-book.wink.travel https://book.wink.travel
프로덕션 계정 ID(4단계)와 사용자 지정 ID(6단계)를 다시 조회하세요. 스테이징과 다릅니다.

스테이징	프로덕션
`https://staging-iam.wink.travel`	`https://iam.wink.travel`
`staging-partner.wink.travel:443`	`partner.wink.travel:443`
`https://staging-book.wink.travel`	`https://book.wink.travel`

Partner API 사용량은 호텔-박 단위로 측정되며, 월별 무료 할당량이 있습니다. 가격 및 한도는 Partner API를 참조하세요.

여행사로서 예약하기

귀하의 계정이 라이선스가 있는 여행사인 경우, 여행자를 book.wink.travel로 보내지 않고 wink.partner.v1.Booking/CreateBooking을 통해 직접 예약을 생성할 수 있으며, 다른 Booking 호출로 관리할 수 있습니다. 다른 계정은 여행자를 예약 링크로 보냅니다.

여행사 계정은 인증을 받습니다: Wink는 모든 여행사 등록을 검토한 후 예약 권한을 부여합니다. 고객으로부터 직접 결제를 수취하는 상인으로서 예약하려면 Partner API를 통해 예약하고 Wink의 서면 승인을 받아야 합니다. 자세한 내용은 여행사 시작하기 및 Partner API 참조를 참조하세요.

다음 단계

.proto 스키마에서 타입이 지정된 클라이언트 생성하기로 grpcurl을 수동 호출하는 대신 사용하세요.
MCP 서버를 연결하고 AI Skills를 사용해 코딩 어시스턴트가 실시간 API에 맞는 통합 코드를 작성하게 하세요.
전체 환경 및 호스트 목록을 읽어보세요.