跳转到内容

快速入门

本指南将带您在约 30 分钟内完成从无到有的集成。完成后,您将拥有:

  • 来自 Partner API 的某城市酒店实时价格,
  • 一个将预订计入您账户的预订链接,
  • 一次测试预订及其发生的 webhook 通知。

所有操作均在 staging(我们的测试环境)中进行。您无需申请访问权限,后续切换到生产环境也无需审批。

您想要…从这里开始
在您的应用、网站或 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。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>

测试环境中,曼谷有测试酒店可用,因此此处使用其 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 的 10 次方(美元为 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 参考。