コンテンツにスキップ

クイックスタート

このガイドでは、約30分で何もない状態から動作する統合までを案内します。最後には以下が手に入ります:

  • Partner APIから都市のホテルのライブ価格、
  • あなたのアカウントに予約がクレジットされる予約リンク、
  • テスト予約とその発生を知らせるWebhook。

すべてステージング、つまりテスト環境で行います。アクセス申請は不要で、本番環境への移行も承認は必要ありません。

このガイドはあなたに合っていますか?

Section titled “このガイドはあなたに合っていますか?”
あなたがしたいことここから始める
アプリ、サイト、AI製品でホテルを表示し、旅行者を予約に誘導してコミッションを得たいこのガイド
ライセンスを持つ旅行代理店としてクライアントの代わりに予約したいこのガイドのステップ5まで、その後は旅行代理店としての予約
統合を書かずに予約可能なホテルを埋め込みたいWeb Components
AIエージェントに検索と予約をさせたいMCP Servers と Agentic Payments
チャネルマネージャーやPMSを接続したいチャネルマネージャーを追加する

Partner APIを使ってホテルとそのライブ価格を検索します。各ホテルには安定したurlNameが付いています。これを使って、あなたのIDを含むリンクをWink Booking Engineのbook.wink.travelに作成します。旅行者はそこで予約・支払いを行い、その予約はあなたのアカウントにクレジットされます。

必要なもの:

  • grpcurl、またはPostmanやInsomnia。Partner APIはgRPCで、RESTではありません。
  • curl

ステップ1:ステージングアカウントを作成する

Section titled “ステップ1:ステージングアカウントを作成する”

ステージングは本番環境と完全に分離されており、ログインやアカウントも別です。

  1. staging-app.wink.travelにアクセスし、Sign-In / Registerをクリックして登録します。

  2. 左サイドバーのAccountsをクリックし、Createを選択してI am an Affiliateを選びます。あなたが送る予約はこのアカウントにクレジットされます。アカウント作成を参照してください。

ステップ2:アプリケーションを作成する

Section titled “ステップ2:アプリケーションを作成する”

アプリケーションはあなたのコードに認証情報を与えます。

  1. アカウントカードでActions > Manage accountをクリックし、Applicationsタブを開きます。

  2. Create new applicationをクリックし、名前を付けてクライアントタイプにMachine-to-machineを選択します。

  3. スコープでInventory & rates(読み取り)を選択します。Partner APIはinventory.readをチェックします。

  4. Create applicationをクリックし、Client IDとClient secretをコピーします。シークレットは一度だけ表示され、後で取得できません。

他のクライアントタイプやスコープはApplicationsを参照してください。

ステップ3:アクセストークンを取得する

Section titled “ステップ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ライブラリを使って取得・更新してください。認証を参照。

トークンリクエストが拒否されると、レスポンスはerrorコードを含むJSONになります:

errorHTTPステータス主な原因
invalid_client401クライアントIDまたはシークレットが間違っている、または本番認証情報をstaging-iamで使った
invalid_scope400アプリケーションに登録されていないスコープを要求した
unauthorized_client400アプリケーションがclient_credentialsグラントを使う許可がない
invalid_request400必須パラメータが欠けている(例:ボディがJSONでフォームでない)

ステップ4:アカウントIDを調べる

Section titled “ステップ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:都市のホテルを検索する

Section titled “ステップ5:都市のホテルを検索する”

ステージングにはバンコクのテストホテルがあるため、スラッグ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
rc1部屋あたりの人数rc=a2(大人2名)
l表示言語l=en
c表示通貨c=USD
pプロモーションコードp=ABC123

これらのパラメータはカスタマイズで設定したデフォルトを上書きします。Book Nowボタンガイドには子供や複数部屋を含むrcの完全な形式が載っています。

リンクはホテルページを開きますが、部屋や料金の事前選択はできません。旅行者はホテルページで部屋を選び、ライブ価格で予約します。

単一ホテルではなく予約エンジンのホームページにリンクする方法は直接リンクを参照してください。

リンクを開き、日付と部屋を選び、Stripeのテストカード(例:4242 4242 4242 4242、有効期限は未来の日付、CVCは任意)で決済してください。ステージングでは実際のカードは課金されません。確認ページに表示される予約コードを控えてください。WNKで始まります。

ステップ8:予約通知を受け取る

Section titled “ステップ8:予約通知を受け取る”
  1. PortalでApplications > Webhooksに行き、POSTリクエストを受け取るエンドポイントを追加します。

  2. booking.createにサブスクライブするか、開発中はイベントリストを空にしてすべて受け取ります。

  3. テストイベントを送信し、もう一度テスト予約をして通知が届くことを確認します。

配信の署名を必ず検証してから信頼してください。Webhook統合とWebhookイベントカタログを参照。

ステップ9:本番環境へ移行する

Section titled “ステップ9:本番環境へ移行する”

開発者向けの承認ステップはありません。(旅行代理店アカウントは認証が必要です。詳細は以下参照。)ステージングで統合が動作したら:

  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リファレンスを参照してください。