跳到內容

快速入門

本指南將帶您在約 30 分鐘內完成從無到有的整合。結束時您將擁有:

  • 來自 Partner API 的城市飯店即時價格,
  • 可將訂單計入您帳戶的訂房連結,
  • 一筆測試訂單,以及通知您訂單發生的 webhook。

所有操作皆在 測試環境 進行。我們不需您申請存取權,日後切換到正式環境也不需審核。

您想要…從這裡開始
在您的應用程式、網站或 AI 產品中顯示飯店並將旅客導向訂房,賺取佣金本指南
以持牌旅行社身份為客戶代訂本指南至第 5 步,接著參考 以旅行社身份訂房
嵌入可訂房的飯店,且不需撰寫整合程式碼Web Components
讓 AI 代理搜尋並訂房MCP Servers 與 Agentic Payments
連接頻道管理系統或 PMS新增您的頻道管理系統

您使用 Partner API 查找飯店及其即時價格。每間飯店都有穩定的 urlName。您將它轉成指向 Wink 訂房引擎 book.wink.travel 的連結,並帶上您的 ID。旅客在該處訂房付款,訂單會計入您的帳戶。

您需要:

  • grpcurl,或 Postman 或 Insomnia。Partner API 是 gRPC,不是 REST。
  • 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。密鑰只顯示一次,之後無法取回。

其他客戶端類型與 scopes 請參考 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請求了應用程式未註冊的 scope
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>

測試環境有曼谷的測試飯店可訂,因此此搜尋使用其 slug 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,訂房連結所需的 slug。

價格為以最小單位表示的整數:除以回應中的 currencyExponent 次方(美元為 2,因此 12500 表示 $125.00)。

不知道城市 slug?可用 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. 在 Portal 中,前往 Applications > Webhooks,新增可接受 POST 請求的端點。

  2. 訂閱 booking.create,或開發期間可留空事件列表以接收所有事件。

  3. 傳送測試事件給自己,再進行另一筆測試訂單並觀察通知是否送達。

收到通知前請驗證簽章。詳見 Webhook 整合 與 Webhook 事件目錄。

開發者無需審核步驟。(旅行社帳戶需先通過認證,詳見下方 以旅行社身份訂房。)當您的整合在測試環境運作正常:

  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 參考。