快速入门
本指南将带您在约 30 分钟内完成从无到有的集成。完成后,您将拥有:
- 来自 Partner API 的某城市酒店实时价格,
- 一个将预订计入您账户的预订链接,
- 一次测试预订及其发生的 webhook 通知。
所有操作均在 staging(我们的测试环境)中进行。您无需申请访问权限,后续切换到生产环境也无需审批。
这份指南适合您吗?
Section titled “这份指南适合您吗?”| 您想要… | 从这里开始 |
|---|---|
| 在您的应用、网站或 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 步:创建测试账户
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 作为客户端类型。 -
在 scopes 中选择 Inventory & rates(只读)。Partner API 会检查
inventory.read权限。 -
点击
Create application,复制 Client ID 和 Client secret。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 步:搜索某城市的酒店”测试环境中,曼谷有测试酒店可用,因此此处使用其 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 参考 详细说明了所有调用。
第 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 | 每间房人数 | rc=a2(2 位成人) |
l | 显示语言 | l=en |
c | 显示货币 | c=USD |
p | 促销代码 | p=ABC123 |
这些参数会覆盖定制中设置的默认值。立即预订按钮指南 介绍了完整的 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 参考。
