콘텐츠로 이동

빠른 시작

이 가이드는 약 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를 클릭해 등록하세요.

  2. 왼쪽 사이드바에서 Accounts를 클릭한 후 Create를 클릭하고 I am an Affiliate를 선택하세요. 귀하가 보내는 예약은 이 계정에 적립됩니다. 자세한 내용은 계정 만들기를 참조하세요.

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

  1. 계정 카드에서 Actions > Manage account를 클릭한 후 Applications 탭으로 이동하세요.

  2. Create new application을 클릭하고 이름을 지정한 뒤 클라이언트 유형으로 Machine-to-machine을 선택하세요.

  3. 권한 범위(scopes)에서 Inventory & rates (읽기)를 선택하세요. Partner API는 inventory.read를 확인합니다.

  4. Create application을 클릭하고 Client ID와 Client secret을 복사하세요. 비밀 키는 한 번만 표시되며 나중에 다시 볼 수 없습니다.

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

터미널 창
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 라이브러리를 사용해 토큰을 가져오고 갱신하세요. 자세한 내용은 인증을 참조하세요.

토큰 요청이 거부되면 응답은 error 코드가 포함된 JSON 본문입니다:

errorHTTP 상태일반 원인
invalid_client401잘못된 클라이언트 ID 또는 비밀 키, 또는 프로덕션 자격 증명을 staging-iam에서 사용함
invalid_scope400애플리케이션에 등록되지 않은 권한 범위를 요청함
unauthorized_client400애플리케이션이 client_credentials 권한을 사용할 수 없음
invalid_request400필수 매개변수가 누락됨, 예를 들어 본문이 폼이 아닌 JSON일 때

모든 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>

스테이징에는 방콕에 테스트 호텔이 있어, 이 검색은 슬러그 bangkok-thailand를 사용합니다:

터미널 창
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 참조에 문서화되어 있습니다.

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에서 확인하세요. 커스터마이징은 예약 페이지의 브랜딩, 기본 언어 및 통화를 설정합니다.

여행자의 날짜, 인원, 언어, 통화를 같은 링크에 추가해 호텔 페이지가 해당 정보로 열리도록 하세요:

https://staging-book.wink.travel/hotel/<urlName>?client-id=<YOUR_CLIENT_ID>&configuration-id=<YOUR_CUSTOMIZATION_ID>&sd=2027-03-14&n=2&rc=a2&l=en&c=USD
매개변수의미예시
sd체크인 날짜sd=2027-03-14
n 또는 ed숙박 일수 또는 체크아웃 날짜n=2 또는 ed=2027-03-16
rc객실당 인원rc=a2 (성인 2명)
l표시 언어l=en
c표시 통화c=USD
p프로모션 코드p=ABC123

이 매개변수들은 커스터마이징에서 설정한 기본값을 덮어씁니다. 지금 예약 버튼 가이드에서 어린이 및 여러 객실을 포함한 전체 rc 형식을 확인하세요.

링크는 호텔 페이지를 엽니다; 객실이나 요금을 미리 선택할 수는 없습니다. 여행자가 호텔 페이지에서 객실을 선택하고 실시간 가격으로 예약합니다.

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

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

  1. 포털에서 Applications > Webhooks로 가서 POST 요청을 받는 엔드포인트를 추가하세요.

  2. booking.create 이벤트를 구독하거나, 개발 중에는 이벤트 목록을 비워 모든 이벤트를 받으세요.

  3. 테스트 이벤트를 보내고, 다시 테스트 예약을 만들어 알림이 도착하는지 확인하세요.

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

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

  1. app.wink.travel에서 계정과 애플리케이션을 1, 2단계와 같이 만드세요. 자격 증명은 환경 간에 이전되지 않습니다.

  2. 모든 호스트에서 staging- 접두사를 제거하세요:

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

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

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

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