クイックスタート
このガイドでは、約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に作成します。旅行者はそこで予約・支払いを行い、その予約はあなたのアカウントにクレジットされます。
はじめる前に
Section titled “はじめる前に”必要なもの:
grpcurl、またはPostmanやInsomnia。Partner APIはgRPCで、RESTではありません。curl
ステップ1:ステージングアカウントを作成する
Section titled “ステップ1:ステージングアカウントを作成する”ステージングは本番環境と完全に分離されており、ログインやアカウントも別です。
-
staging-app.wink.travelにアクセスし、
Sign-In / Registerをクリックして登録します。 -
左サイドバーの
Accountsをクリックし、Createを選択してI am an Affiliateを選びます。あなたが送る予約はこのアカウントにクレジットされます。アカウント作成を参照してください。
ステップ2:アプリケーションを作成する
Section titled “ステップ2:アプリケーションを作成する”アプリケーションはあなたのコードに認証情報を与えます。
-
アカウントカードで
Actions>Manage accountをクリックし、Applicationsタブを開きます。 -
Create new applicationをクリックし、名前を付けてクライアントタイプにMachine-to-machineを選択します。 -
スコープでInventory & rates(読み取り)を選択します。Partner APIは
inventory.readをチェックします。 -
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になります:
error | HTTPステータス | 主な原因 |
|---|---|---|
invalid_client | 401 | クライアントIDまたはシークレットが間違っている、または本番認証情報をstaging-iamで使った |
invalid_scope | 400 | アプリケーションに登録されていないスコープを要求した |
unauthorized_client | 400 | アプリケーションがclient_credentialsグラントを使う許可がない |
invalid_request | 400 | 必須パラメータが欠けている(例:ボディが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リファレンスにすべての呼び出しが記載されています。
ステップ6:予約リンクを作る
Section titled “ステップ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で確認。カスタマイズは予約ページのブランディング、デフォルト言語、通貨も設定します。
旅行者の検索条件を渡す
Section titled “旅行者の検索条件を渡す”旅行者の滞在日、人数、言語、通貨を同じリンクに追加すると、ホテルページがそれらを反映して開きます:
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 | 1部屋あたりの人数 | rc=a2(大人2名) |
l | 表示言語 | l=en |
c | 表示通貨 | c=USD |
p | プロモーションコード | p=ABC123 |
これらのパラメータはカスタマイズで設定したデフォルトを上書きします。Book Nowボタンガイドには子供や複数部屋を含むrcの完全な形式が載っています。
リンクはホテルページを開きますが、部屋や料金の事前選択はできません。旅行者はホテルページで部屋を選び、ライブ価格で予約します。
単一ホテルではなく予約エンジンのホームページにリンクする方法は直接リンクを参照してください。
ステップ7:テスト予約をする
Section titled “ステップ7:テスト予約をする”リンクを開き、日付と部屋を選び、Stripeのテストカード(例:4242 4242 4242 4242、有効期限は未来の日付、CVCは任意)で決済してください。ステージングでは実際のカードは課金されません。確認ページに表示される予約コードを控えてください。WNKで始まります。
ステップ8:予約通知を受け取る
Section titled “ステップ8:予約通知を受け取る”-
Portalで
Applications > Webhooksに行き、POSTリクエストを受け取るエンドポイントを追加します。 -
booking.createにサブスクライブするか、開発中はイベントリストを空にしてすべて受け取ります。 -
テストイベントを送信し、もう一度テスト予約をして通知が届くことを確認します。
配信の署名を必ず検証してから信頼してください。Webhook統合とWebhookイベントカタログを参照。
ステップ9:本番環境へ移行する
Section titled “ステップ9:本番環境へ移行する”開発者向けの承認ステップはありません。(旅行代理店アカウントは認証が必要です。詳細は以下参照。)ステージングで統合が動作したら:
-
app.wink.travelでアカウントとアプリケーションを作成します(ステップ1と2と同様)。認証情報は環境間で引き継がれません。
-
すべてのホストから
staging-を外します:ステージング 本番 https://staging-iam.wink.travelhttps://iam.wink.travelstaging-partner.wink.travel:443partner.wink.travel:443https://staging-book.wink.travelhttps://book.wink.travel -
本番のアカウントID(ステップ4)とカスタマイズID(ステップ6)を再度調べます。ステージングとは異なります。
Partner APIの利用はホテル泊数単位で計測され、月間無料枠があります。Partner APIで料金と制限を確認してください。
旅行代理店としての予約
Section titled “旅行代理店としての予約”アカウントがライセンスを持つ旅行代理店の場合、旅行者をbook.wink.travelに送る必要はありません。wink.partner.v1.Booking/CreateBookingで直接予約を作成し、他のBooking呼び出しで管理できます。その他のアカウントは旅行者を予約リンクに送ります。
旅行代理店アカウントは認証済みです:Winkはすべての代理店登録を審査してから予約可能にします。クライアントからの支払いを代理店自身が受け取る場合は、Partner API経由で予約し、Winkの書面による承認が必要です。旅行代理店としての始め方とPartner APIリファレンスを参照してください。
次のステップ
Section titled “次のステップ”.protoスキーマから型付きクライアントを生成し、手動でgrpcurlを呼ぶ代わりに使う。- MCPサーバーを接続し、AIスキルを使ってコーディングアシスタントにライブAPI向け統合を書かせる。
- 環境とホストの完全リストを読む。
