跳转到内容

添加您的渠道管理器

本指南引导渠道管理器和PMS开发者完成与Wink的完整集成流程——从创建账户到映射库存,再到运行首次端到端测试。

渠道管理器(集成)API 提供两个环境。所有开发和认证均使用staging环境;上线时切换到生产环境。

环境基础URL
生产https://integrations.wink.travel
测试(staging)https://staging-integrations.wink.travel

渠道管理器API遵循OTA协议标准(SOAP/XML),以兼容现有酒店系统。请先查看合作伙伴端点文档:

渠道管理器API — 合作伙伴端点

  1. 创建Wink用户账户

    在 staging-app.wink.travel 注册。以下所有步骤均使用staging环境——上线前您需要在生产环境重复完整流程。

  2. 创建您的Affiliate / 渠道管理器账户

    在新用户下创建账户,选择 Affiliate / Channel Manager 账户类型。您的集成将以此账户进行身份验证。

  3. 注册应用并生成第一个令牌

    创建一个 Application,并绑定到步骤2中的渠道管理器账户。选择 MACHINE_2_MACHINE 作为客户端类型——这是无终端用户重定向的服务器间集成。立即复制 Client ID 和 Secret Key;Secret Key只显示一次,无法再次获取。

    应用负责生成本指南中每次调用所需的Bearer令牌,格式为 Authorization: Bearer <access_token>。使用 client_credentials 授权类型向 https://staging-iam.wink.travel/oauth2/token 交换凭证,申请 integrations.read integrations.write 权限。请先完成此步骤——没有令牌无法查询账户标识或访问任何渠道管理器端点。详见 认证 了解完整流程、生产环境地址及权限目录。

  4. 创建酒店账户

    在同一用户下创建第二个账户,选择 Hotel 账户类型。这样您将拥有一个可用于测试的物业,无需涉及真实酒店。

  5. 确认两个账户均已批准

    未批准的账户不可使用:未批准的渠道管理器账户不会出现在任何酒店的渠道管理器列表中,未批准的酒店不会被API返回。

    • 测试环境(staging) — 自动批准。账户创建后即可使用,无需申请。
    • 生产环境 — 手动批准。将两个账户名称及所属用户发送给Wink集成联系人,等待确认后继续。
  6. 连接两个账户

    登录酒店账户,导航至 渠道 → 渠道管理器。从列表中选择您的渠道管理器账户——这将物业与您的集成关联。如果账户未出现在列表中,说明尚未批准;请参见步骤5。

  7. 创建基础房型和价格计划

    在酒店账户内,至少创建一个房型和一个价格计划。推送价格和可用性或拉取预订前必须完成此步骤。

  8. 映射并测试

    在您自己的系统中映射API返回的房型和价格计划标识符。推送价格更新和可用性更新,进行测试预订,并验证预订查询端点能正确返回预订信息。

每个渠道管理器API路径均限定在您自己的账户范围内:

/api/managing-entity/{managingEntityIdentifier}/channel-manager/...

{managingEntityIdentifier} 是 您的渠道管理器账户 的账户ID(UUID),不是酒店的。您可以通过平台API获取该ID及您用户拥有的其他账户的ID和当前状态:

终端窗口
curl -s -X GET \
"https://staging-api.wink.travel/api/managing-entity/list" \
-H "Authorization: Bearer <access_token>" \
-H "Wink-Version: 2.0" \
-H "Accept: application/json"

响应是您拥有账户的数组:

[
{
"id": "3f1c8e42-7b90-4d55-a1e2-6c8d09b4f731",
"type": "CHANNEL_MANAGER",
"name": "您的渠道管理器",
"status": "ACTIVE"
},
{
"id": "d5b8a3c2-9e6f-4a1b-8d34-7c2e1f0a5b69",
"type": "HOTEL",
"name": "您的测试物业",
"urlName": "your-test-property",
"status": "ACTIVE"
}
]
  • 渠道管理器条目的 id 是您的 {managingEntityIdentifier}。
  • HOTEL 条目的 id 是您的 {propertyIdentifier}。
  • status 用于确认账户是否已批准——在生产环境尤为重要,因批准为手动。酒店必须显示为 ACTIVE 才能被预订或被渠道管理器API识别。您的渠道管理器账户在通过认证前会显示 PENDING_APPROVAL,这是正常且不影响开发。

认证是您向Wink证明集成正确映射库存、推送价格和可用性、并端到端接收预订的过程。认证设计为自助式:您从自己的系统驱动每一步,最后提交一份证据包。Wink审核通过后,将您的Affiliate / 渠道管理器账户状态从 PENDING_APPROVAL 变更为 ACTIVE。

认证完全在测试环境运行(https://staging-integrations.wink.travel),本节内容不涉及生产环境。

  1. 认证。 您的OAuth2客户端能获取访问令牌,并成功调用 /ping 端点,针对您的Affiliate / 渠道管理器账户。

  2. 库存映射。 您能列出连接的酒店,获取您配置的主价格(房型 × 价格计划),并正确识别系统将操作的 masterRateIdentifier。

  3. 价格和可用性推送。 您能独立更新认证周内的七天价格——每天的金额、数量、入住/离店关闭标志、最短/最长入住天数均不同——并能从Wink读取准确值。

  4. 预订拉取。 您能检索针对测试物业的真实测试预订,在自己的PMS/渠道管理器界面正确显示房间住宿、客人和总价,并在Wink标记预订取消后反映取消状态。

开始认证前,请完成集成步骤的第1–7步,确保您拥有:

  • 一个测试环境的Wink用户,包含一个 Affiliate / 渠道管理器 账户和一个连接的 酒店 账户(渠道 → 渠道管理器)。测试环境账户自动批准,无需申请。
  • 酒店账户内至少创建一个 房型 和一个 价格计划。发布酒店,使其可在 https://staging-book.wink.travel/hotel/<your-slug> 预订。
  • 在Affiliate / 渠道管理器账户下注册的应用,拥有 Client ID、Secret Key 和 integrations.read integrations.write 权限(详见 认证)。
  • 您的Affiliate / 渠道管理器账户的 managingEntityIdentifier 和酒店账户的 propertyIdentifier(均为UUID,详见查找账户标识符)。

本节所有请求均使用以下请求头:

Authorization: Bearer <access_token>
Wink-Version: 2.0
Accept: application/json
  • <access_token> 来自针对 https://staging-iam.wink.travel/oauth2/token 的 client_credentials 授权——详见 认证。
  • Wink-Version 头必填,缺失将无法路由至v2 JSON API。
  • PUT 请求携带请求体时,自动添加 Content-Type: application/json。

以下示例中的占位符对应您在前置条件中收集的值:

占位符含义
{managingEntityIdentifier}您的Affiliate / 渠道管理器账户ID(UUID)——详见查找账户标识符。
{propertyIdentifier}您连接到渠道管理器账户的酒店账户(物业)ID。
{masterRateIdentifier}您将认证的主价格(房型 × 价格计划)。
{bookingIdentifier}预订列表调用返回的测试环境预订ID。

确认您的凭证对应预期的Affiliate / 渠道管理器账户。

终端窗口
curl -s -X GET \
"https://staging-integrations.wink.travel/api/managing-entity/{managingEntityIdentifier}/channel-manager/ping" \
-H "Authorization: Bearer <access_token>" \
-H "Wink-Version: 2.0" \
-H "Accept: application/json"

预期响应:

{
"apiVersion": "2.0",
"name": "您的渠道管理器账户名称",
"status": "PENDING_APPROVAL"
}

返回 200 且 name 匹配即表示认证和账户解析正确。status 在Wink认证前会显示 PENDING_APPROVAL。

获取分页的酒店列表,确认测试物业存在。

终端窗口
curl -s -X GET \
"https://staging-integrations.wink.travel/api/managing-entity/{managingEntityIdentifier}/channel-manager/property/list?page=0&size=25" \
-H "Authorization: Bearer <access_token>" \
-H "Wink-Version: 2.0" \
-H "Accept: application/json"

响应是Spring的 Page 类型,包含多个 ChannelManagerProperty 条目。找到 identifier 与 {propertyIdentifier} 匹配的条目,并记录其 currencyCode,后续推送价格时需要用到(见步骤D)。

获取物业及其所有主价格(房型 × 价格计划组合)。选择您将认证的主价格,记录其 identifier 作为 {masterRateIdentifier}。

终端窗口
curl -s -X GET \
"https://staging-integrations.wink.travel/api/managing-entity/{managingEntityIdentifier}/channel-manager/property/{propertyIdentifier}" \
-H "Authorization: Bearer <access_token>" \
-H "Wink-Version: 2.0" \
-H "Accept: application/json"

响应为 PropertyWithRoomRateList,包含 property 块和 rooms 数组,每个元素为 PropertyRoomRate,展示房型、价格计划、入住限制、基础价格及推送时需保留的价格修饰符。

加载覆盖您开始认证月份后一个月的前七天的七天价格日历。例如,若您8月21日开始认证,则目标日期为9月1日至9月7日。

您将发送七个独立的PUT请求,每天一个,startDate == endDate。每天的金额、数量、限制标志和入住天数限制均不同,确保每个可写字段至少被测试一次。金额单位为物业货币(步骤B记录),可省略 currencyCode,系统会自动默认。

天数金额数量closedOnArrivalclosedOnDepartureminLengthOfStaymaxLengthOfStay说明
1100.005falsefalse130基准日
2125.004falsefalse114金额+数量+最长入住天数变更
3150.003truefalse130入住关闭标志切换
4175.002falsetrue27离店关闭标志切换+更严格入住天数
5200.000falsefalse130售罄数量
6225.005falsefalse35限制入住天数窗口
7250.001falsefalse130最后剩余房间

第1天的请求体示例如下。请根据表格调整日期和值,重复发送第2至第7天的请求。

终端窗口
curl -s -X PUT \
"https://staging-integrations.wink.travel/api/managing-entity/{managingEntityIdentifier}/channel-manager/property/{propertyIdentifier}/master-rate/{masterRateIdentifier}" \
-H "Authorization: Bearer <access_token>" \
-H "Wink-Version: 2.0" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
"startDate": "2026-09-01",
"endDate": "2026-09-01",
"amount": 100.00,
"master": true,
"closedOnArrival": false,
"closedOnDeparture": false,
"quantity": 5,
"minLengthOfStay": 1,
"maxLengthOfStay": 30
}'

每个 PUT 请求返回状态码 200,响应体为您更新日期范围内的 PropertyRate 条目数组(startDate == endDate 时为单条)。请保存响应,作为认证证据。

一次调用获取整周价格,确认每天存储的值与步骤D发送的完全一致,包括布尔标志和入住天数限制。

终端窗口
curl -s -X GET \
"https://staging-integrations.wink.travel/api/managing-entity/{managingEntityIdentifier}/channel-manager/property/{propertyIdentifier}/master-rate/{masterRateIdentifier}?startDate=2026-09-01&endDate=2026-09-07" \
-H "Authorization: Bearer <access_token>" \
-H "Wink-Version: 2.0" \
-H "Accept: application/json"

响应为 PropertyRoomRateWithRateList,其 rates 数组应包含七条记录,每条对应一天,且字段 amount、quantity、closedOnArrival、closedOnDeparture、minLengthOfStay、maxLengthOfStay 均与发送值匹配。若有不符,说明步骤D的对应PUT请求未生效,请修正后重新验证。

在浏览器打开以下URL,将 <your-slug> 替换为您在前置条件中发布的酒店slug:

https://staging-book.wink.travel/hotel/<your-slug>

选择完全落在认证周内的入住和离店日期,选择您认证的房型+价格计划组合,完成预订。测试环境使用测试支付路径,无实际扣款。

确认页显示后,记录显示给客人的 预订代码(格式为 WNKxxxxx)。

检索测试物业在包含预订时间戳的时间窗口内的所有预订。

终端窗口
curl -s -X GET \
"https://staging-integrations.wink.travel/api/managing-entity/{managingEntityIdentifier}/channel-manager/property/{propertyIdentifier}/booking/list?startDate=2026-09-01T00:00:00&endDate=2026-09-08T00:00:00" \
-H "Authorization: Bearer <access_token>" \
-H "Wink-Version: 2.0" \
-H "Accept: application/json"

找到 bookingCode 与步骤F记录的代码匹配的条目,记录其 bookingIdentifier。然后获取该单个预订:

终端窗口
curl -s -X GET \
"https://staging-integrations.wink.travel/api/managing-entity/{managingEntityIdentifier}/channel-manager/property/{propertyIdentifier}/booking/{bookingIdentifier}" \
-H "Authorization: Bearer <access_token>" \
-H "Wink-Version: 2.0" \
-H "Accept: application/json"

响应为 PropertyBooking。导入至您自己的PMS/渠道管理器界面,确认以下信息正确显示给操作员:

  • bookingCode、bookingIdentifier、createdDate
  • 客人信息:firstName、lastName、email
  • totalAmount + currencyCode(酒店所有房间的净收入)
  • paymentMethodType、paymentMethodStatus、salesChannelName
  • roomStays 中每条记录的 guestRoomName、ratePlanName、adults、children、startDate、endDate 及每间房的 amount

截取预订在您界面中的截图,该截图为认证所需证据之一。

请Wink团队代为取消认证预订(或若您有权限,可在酒店账户的Extranet自行取消)。然后用步骤G的调用重新获取该预订。

确认响应显示:

  • cancelled: true
  • 填充的 cancelDate 时间戳
  • 反映取消状态的 paymentMethodStatus(根据退款政策为 CANCELLED、PARTIALLY_REFUNDED 或 FULLY_REFUNDED)

将更新后的预订导入您界面,确认取消状态、取消时间戳及退款指示对操作员可见。截取取消后的预订截图,作为最终证据。

将以下内容打包成一个名为 wink-cert-<your-channel-manager-name>-<yyyy-mm-dd>.zip 的压缩包:

  1. API调用记录。 捕获步骤A至H中每个请求的完整HTTP请求(方法、URL、请求头,Authorization值需脱敏,PUT请求的JSON体)及完整HTTP响应(状态码、响应头、JSON体)。按步骤清晰命名文件(如 step-a-ping.json、step-d-day-3-put.json、step-g-list-bookings.json 等)。纯文本 .http 文件或单一 .har 导出均可。

  2. 界面截图:有效预订。 步骤G中显示认证预订的PMS/渠道管理器界面截图,客人信息、日期、房型、价格计划和总价清晰可见。

  3. 界面截图:取消预订。 步骤H中取消后的预订界面截图,取消状态和时间戳清晰可见。

  4. 认证总结。 压缩包内的简短 README.md,列出:

    • 您的渠道管理器/PMS名称及版本。
    • 使用的 managingEntityIdentifier、propertyIdentifier、masterRateIdentifier 和 bookingIdentifier。
    • 测试酒店slug(即 https://staging-book.wink.travel/hotel/<your-slug> 中的 <your-slug>)。
    • 认证周日期范围(第1天至第7天,ISO-8601格式)。
    • 负责认证的工程师姓名和邮箱。

将压缩包发送给您的Wink集成联系人。Wink将审核,针对任何差异进行跟进,审核通过后将您的Affiliate / 渠道管理器账户状态从 PENDING_APPROVAL 变更为 ACTIVE。您的集成即可进入生产上线流程。

您可以订阅渠道管理器Webhook事件,实时接收通知:

  • channel-manager.update.rate — 收到价格更新。
  • channel-manager.update.availability — 收到可用性更新。
  • channel-manager.update — 一般渠道管理器更新。

详情见 Webhook事件目录。