跳到主要内容

设置 Cloudbeds PMS 集成

快速设置

连接 Cloudbeds 通常需要约 10 分钟。 Cloudbeds 使用 OAuth v3。 如果回调省略版本，AVA 会提供 v3。 Cloudbeds v1 和 v2 已停用。 明确请求 v1 或 v2 会返回不支持该版本的错误。 请移除版本固定值，然后开始新的连接。 Cloudbeds 现在会请求 item 访问权限、只读 add-on 访问权限，以及 hotel、rate 和 taxes/fees 的读取权限。 对于受支持的费率保留更新，它还会请求 adjustment 写入权限。 AVA 会在 OAuth 重定向前保存其他尚未保存的 Essentials 更改。 授权完成后，Cloudbeds 会成为活动 PMS。 完成最终处理后，提供商选择会自动刷新。

本指南帮助你连接 Cloudbeds。 它会同步 reservation、guest、housekeeping、payment、room、currency、hotel、rate 和 tax 数据。 如果 Cloudbeds 拒绝连接，AVA 现在会在错误横幅中显示确切原因。

查找位置​

Settings → Essentials → Property Management System (PMS) Integration

开始之前​

你需要：

  • 拥有管理员访问权限的 Cloudbeds 账号
  • Cloudbeds 登录凭据
  • 授权第三方应用的权限
注意

每个物业同一时间只能连接一个 Cloudbeds 账号。

连接 Cloudbeds​

第 1 步：选择 Cloudbeds 作为 PMS​

  1. 前往 Settings → Essentials
  2. 滚动到 Property Management System (PMS) Integration
  3. 点击 Cloudbeds 卡片
  4. 出现对勾（✓）即表示已选中

选择该卡片会准备连接。 OAuth 授权完成后，AVA 会激活 Cloudbeds。 你无需再次选择 Cloudbeds 并保存。

第 2 步：开始连接​

  1. 点击 Connect to Cloudbeds 按钮
  2. AVA 会先保存其他尚未保存的 Essentials 更改
  3. 浏览器会打开 Cloudbeds 授权页面

第 3 步：授权访问​

  1. 登录 Cloudbeds 账号
  2. 查看 AVA 请求的权限
  3. 点击 Authorize 或 Allow
  4. 授权完成后返回 AVA

AVA 会通过 OAuth 接收 Cloudbeds 的 Property ID 和 API 密钥。 你无需手动输入这些值。

AVA 现在请求以下权限：

权限AVA 的用途
read:hotel查看 hotel 元数据
read:guest查看 guest 详情
write:guest更新 guest 详情
read:housekeeping查看 housekeeping 数据
write:housekeeping更新 housekeeping 数据
read:rate查看 rate plan 数据
read:payment查看 payment 数据
write:payment更新 payment 数据
read:reservation查看 reservation 数据
write:reservation更新 reservation 数据
read:room查看 room 数据
write:room更新 room 数据
read:currency读取物业货币设置
read:taxesAndFees查看 taxes 和 fee 数据
read:item查看 item catalog 数据
write:item更新 item catalog 数据
read:addon查看 add-on catalog 数据
write:adjustment在受支持的 reservation 更新期间保留费率
现有 Cloudbeds 连接

如果你在此修复之前连接了 Cloudbeds，你的 token 会保留现有权限。 请从 Settings → Essentials 重新连接，以获得当前完整的权限集。

第 4 步：验证连接​

  1. 返回 AVA 设置
  2. 等待出现 "Finalizing connection..."（5-10 秒）
  3. 状态显示绿色对勾
  4. 消息显示："Cloudbeds Account Linked"
  5. 确认 Cloudbeds 提供商卡片仍处于选中状态

连接完成！🎉

完成最终处理后，AVA 会刷新提供商选择。 无需手动刷新页面，已选卡片应显示 Cloudbeds。

Cloudbeds OAuth 错误​

当 Cloudbeds 阻止连接时，AVA 会显示易读的消息。 你不再需要从通用失败消息中猜测原因。

你看到的内容含义处理方法
Cloudbeds did not return the OAuth state parameter.Cloudbeds 回调缺少 state 数据。重新开始连接。
Cloudbeds did not return an authorization code.Cloudbeds 未完成授权。从 Settings → Essentials 重新连接。
Cloudbeds OAuth state verification failed.回调 state 无效或已过期。重新连接 Cloudbeds。
Could not identify the merchant for this Cloudbeds link.AVA 无法将回调匹配到你的酒店。确认你登录的是正确的物业。
Version is required.OAuth 回调未完成。开始新的 Cloudbeds 连接。AVA 会自动使用 OAuth v3。
Unsupported Cloudbeds version.请求选择了已停用的 Cloudbeds v1 或 v2。移除版本固定值，然后开始新的连接。
Cloudbeds rejected the authorization code exchange.Cloudbeds 拒绝了一次性授权码。开始新的 Cloudbeds 连接，让 Cloudbeds 生成新代码。
Failed to link Cloudbeds account.AVA 无法映射后端错误。复制完整消息并联系支持人员。

自动同步的内容​

Cloudbeds 使用 webhooks 进行实时更新。当 Cloudbeds 中发生更改时，AVA 会立即收到通知：

事件发生的情况
Reservation createdAVA 收到通知，并可以安排到店前消息
Reservation dates changedAVA 更新已安排的消息
Check-in/out status状态实时同步
Guest profile updatedAVA 刷新最新 guest 详情，包括用于自动补发追赶的邮箱变更

在 AVA 中查看 reservation 时，系统会直接从 Cloudbeds 获取最新数据，确保你始终看到当前信息。

信息

数据主要从 Cloudbeds → AVA 流动。在 AVA 中进行的 guest 更新（例如完成入住）会发送回 Cloudbeds。

Guest 邮箱更新

当 Cloudbeds 发送 guest 更新时，AVA 可以将已错过的到店前邮件重新发送到 guest 最新的 PMS 地址。 这项自动追赶会在下一次同步后运行。

Cloudbeds 读取保护

如果多名员工同时请求相同的 Cloudbeds 数据，AVA 会共享一个读取请求。 如果 Cloudbeds 再次返回相同的访问错误或 success:false 错误，AVA 会短暂暂停重复重试。

Cloudbeds 到达时间更新

当主 guest 同步时，AVA 可以将 reservation 的 estimated arrival time 发送到 Cloudbeds v3。 陪同 guest 不会更新该时间。 无效、缺失或空的时间会被忽略，因此 AVA 不会清除现有 PMS 数据。 如果该可选更新失败，或 Cloudbeds 不支持该功能，guest 同步仍会成功。

Payment 入账行为​

Cloudbeds shared bills 会针对 shared parent reservation 入账一笔合并 payment。 AVA 会保留 room 级别的追踪元数据，以便员工之后审计分配情况。 如果 booking 不使用 shared bill，AVA 会照常逐个 reservation 入账。

AVA 入账 payment 时，Cloudbeds 会在 payment 描述中保存以下详情：

  • Gateway Transaction ID：payment gateway transaction 标识符。
  • Payment Reference：AVA payment reference。

使用任一值，将 Cloudbeds folio 行与 Stripe 中的 payment 匹配。 之后读取 folio 时，Cloudbeds 会保留这两行描述。

如果 AVA 必须恢复缺失的 Cloudbeds payment method，它会使用所需的 method code。 在可能的情况下，AVA 会重新使用匹配的方法，因此重复 payment 不会创建重复项。

对账 Cloudbeds payment​

  1. 在 AVA 中打开 reservation，并记下其 Transaction ID 或 payment reference。

  2. 在 Cloudbeds 中打开同一 reservation 的 folio。

  3. 找到 AVA 入账的 payment。

  4. 将 Gateway Transaction ID 或 Payment Reference 与 AVA payment 进行比较。

    ✓ 金额、payment method 和 reference 应能识别出同一笔 payment。

对于 shared bills，请检查 shared parent reservation 的 folio。 Cloudbeds 会为该 shared bill 显示一笔合并 payment。

对 Guest 和员工的影响​

  • Guest 表单会适配 Cloudbeds 规则。 必填字段和隐藏字段会根据 Cloudbeds 配置变化，因此 guest 只会看到所需内容。
  • Reservation 查找使用 Cloudbeds。 如果 Cloudbeds 未连接，guest 查找步骤会失败。AVA 最多等待 20 秒进行查找，然后显示服务不可用错误。
  • Cloudbeds 备用查找使用准确的 OTA confirmation reference。 这样可以让大型物业的搜索保持响应，并找到第一页结果之外的匹配 reservation。
  • ACI 文档扫描不会更改 Cloudbeds occupancy。 AVA 会在 Registration 期间创建或同步待处理陪同 guest 时检查容量，然后在最终入住前再次检查。
  • Occupancy 更新会保留预先分配的实体房间。 AVA 更改 Cloudbeds Adults 或 Children 时，现有房间分配保持不变。
  • Occupancy 编辑会在来源处保留已预订费率。 更改 Cloudbeds Adults 或 Children 时，AVA 会按房间发送不重新定价设置。
  • 仍提供修正保护。 如果 Cloudbeds 意外重新计算住宿价格，AVA 会验证日期费率，并可以发布备用修正。
  • 受支持的来源规则使用来源感知计算。 单个不含税百分比费用使用精确到分的税前修正。完全含税的百分比费用（包括多个费用）使用精确的总额修正。
  • Cloudbeds 完成更新后才会检查日期费率。 Cloudbeds 异步应用费率更改。AVA 会等待费率任务完成，然后检查按日期的每晚费率，而不是依赖滞后的计划摘要。
  • 不受支持的来源规则会安全停止。 混合、固定、缺失、不可读取或多个不含税费用会在 occupancy 更改前返回 PMS_RATE_PRESERVATION_SOURCE_TAX_UNSUPPORTED。
  • 仍提供物业级备用方案。 仅当准确来源没有适用费用时，AVA 才会使用该方案。
  • Cloudbeds 的小额四舍五入差异不会阻止验证。 如果只有小计和税额在 10 分以内以相等的相反金额产生差异，AVA 会接受未改变的面向 guest 的总额。
  • 也可以接受较小的总额残差。 最终验证重试后，来源感知更新可以接受最高 5 分且前后一致的总额差异。AVA 会添加包含结算总额和预订总额的备注。不要发布手动修正。
  • Shared bills 显示一笔 PMS payment。 你可能会在 shared parent folio 中看到该 payment，而不是在每个房间中看到。
  • Guest 邮箱变更可能触发补发追赶。 Cloudbeds 发送 guest 更新时，AVA 可以将已错过的到店前邮件重新发送到最新地址。
  • Booking 来源标签可以使用 Cloudbeds 来源元数据。 如果 reservation 缺少 sourceName，AVA 会回退到关联的 Cloudbeds 来源名称。
  • Source collect 在可用时来自关联的来源记录。 这样可以使酒店和渠道来源行为与 Cloudbeds 设置保持一致。
  • Channel-collect 发票仍保持 waived。 当 Cloudbeds v3 将 channel-collect 发票标记为 waived 时，AVA 会将应付总额清零，并在 Streamliner 中显示豁免。
  • 房间状态设置只影响 housekeeping 同步。 房间在 AVA 中被标记为 clean 时，该设置控制 AVA 向 Cloudbeds 发送 Clean 还是 Inspected 状态。它不会更改 guest UI。
  • 预估到达时间同步仅使用主 guest。 陪同 guest 和无效时间会被忽略，因此 AVA 会保持 PMS 值不变。
  • AVA 请求 item 访问权限和只读 add-on 访问权限。 write:addon 会被有意排除。
  • 备用费率修正使用 adjustment 访问权限。 如果 Cloudbeds 意外重新计算价格，AVA 会请求 write:adjustment 以执行安全网修正。
  • Cloudbeds OAuth 作用域会在重新连接时刷新。 重新连接在此修复之前创建的连接，以获得当前完整的权限集。
缺少 adjustment 权限

Cloudbeds 必须授予 write:adjustment，这样 AVA 才能在 occupancy 编辑期间修正意外的重新定价。 如果 AVA 报告 PMS_RATE_PRESERVATION_ADJUSTMENT_SCOPE_MISSING，请停止重试编辑。 使用管理员账号重新连接 Cloudbeds，并批准 adjustment 权限。 AVA 会在写入 occupancy 前阻止编辑，因此通常不需要进行 folio 对账。

断开 Cloudbeds​

仅在以下情况下断开：

  • 切换到其他 PMS
  • 更换 Cloudbeds 账号
  • 排查同步问题

断开方法：

  1. 前往 Settings → Essentials
  2. 点击 Disconnect from Cloudbeds
  3. 按提示确认
警告

断开会立即停止所有同步。现有数据会保留，但不会更新。

故障排查​

一直停在 "Connecting..."​

  1. 等待 30 秒
  2. 刷新页面
  3. 检查网络连接
  4. 尝试使用其他浏览器

Cloudbeds 连接前保存出错​

你看到的内容： "Failed to save settings before connecting: ..."

原因： AVA 在离开并前往 Cloudbeds 前，会保存其他尚未保存的 Essentials 更改。 消息会指出需要处理的设置。

解决方法：

  1. 阅读错误横幅中显示的完整消息。

  2. 修复消息中指出的设置。

  3. 如果页面显示有未保存的更改，请选择 Save。

  4. 再次选择 Connect to Cloudbeds。

    ✓ 保存成功后，AVA 会将你重定向到 Cloudbeds。

Cloudbeds OAuth 错误消息​

你看到的内容： 横幅中出现 Cloudbeds OAuth 消息。

解决方法：

  1. 先阅读消息。
  2. 将其与上方表格匹配。
  3. 如果消息提到 state、code、version 或 token exchange，请开始新的 Cloudbeds 连接。
  4. 确认使用的是 Cloudbeds 管理员账号。
  5. 不要重复使用失败的授权回调。Cloudbeds 授权码只能使用一次。
  6. 如果新的连接仍然失败，请联系支持人员。
信息

如果可用，横幅现在会显示 Cloudbeds 自己的错误详情。 这会为支持排查提供更清晰的起点。 如果省略 Cloudbeds OAuth 版本，AVA 会默认为 v3。 Cloudbeds v1 和 v2 已不再受支持。 请使用无版本路由，让 AVA 选择 v3。

Reservation 未同步​

  1. 等待 15 分钟完成初始同步
  2. 检查连接状态（应显示绿色）
  3. 尝试断开后重新连接
  4. 确认 Cloudbeds 中存在 reservation

Cloudbeds 访问或物业错误​

你看到的内容： 类似 You don't have access to property ID 的消息，或相同的 Cloudbeds 错误立即再次出现。

原因： 已连接的 Cloudbeds 账号无法读取该物业。AVA 也会短暂暂停重复重试。

解决方法：

  1. 确认登录的是正确的 Cloudbeds 物业。

  2. 请 Cloudbeds 管理员确认物业访问权限和授权。

  3. 再次点击 Refresh 前等待一分钟。

  4. 如果消息持续出现，请联系支持人员。

    ✓ 修复 Cloudbeds 访问问题后，下次刷新应该可以成功。

缺少 Cloudbeds adjustment 权限​

你看到的内容： occupancy 编辑返回 PMS_RATE_PRESERVATION_ADJUSTMENT_SCOPE_MISSING。

原因： 你的 Cloudbeds 物业没有授予 AVA write:adjustment 访问权限。

解决方法：

  1. 停止重试 occupancy 编辑。

  2. 前往 Settings → Essentials。

  3. 使用管理员账号重新连接 Cloudbeds。

  4. 批准 write:adjustment 权限。

  5. 等待连接完成，然后仅重试编辑一次。

    ✓ 权限生效后，AVA 应能接受新的 occupancy 编辑。

缓存的权限检查

首次拒绝后，AVA 可能会继续阻止该物业最多六小时。 如果重新连接并等待后仍然出现相同代码，请联系支持人员。

Cloudbeds 来源税费设置需要检查​

你看到的内容： occupancy 编辑返回 PMS_RATE_PRESERVATION_SOURCE_TAX_UNSUPPORTED。 消息会说明 Cloudbeds occupancy 未被更改。

原因： reservation 的来源税费或费用规则不受支持。 为防止无法恢复的重新定价，AVA 会在写入 occupancy 前停止。

解决方法：

  1. 在 Cloudbeds 中打开 reservation。

  2. 确认 reservation 的 booking 来源和目标房型。

  3. 查看来源的税费和费用。

  4. 请 Cloudbeds 管理员修正不受支持的来源规则。 这可能涉及混合、非百分比、不可读取或多个不含税费用。

  5. 刷新 AVA，并仅重试 occupancy 编辑一次。

    ✓ Cloudbeds 显示受支持的来源政策后，编辑应该可以继续。

不要绕过来源检查

在确认 Cloudbeds 中的预订总额之前，不要手动更改 occupancy。 如果来源规则看起来受支持，但 AVA 仍返回此代码，请联系支持人员。

Cloudbeds 已关联但未激活​

你看到的内容： Cloudbeds 已成功关联，但仍选中了另一个 PMS。 你可能会看到："Cloudbeds is linked, but it could not be set as the active PMS. Select Cloudbeds above and save to finish."

解决方法：

  1. 前往 Settings → Essentials。

  2. 选择 Cloudbeds 提供商卡片。

  3. 点击 Save。

  4. 保存后确认 Cloudbeds 卡片仍处于选中状态。

    ✓ Cloudbeds 现在是活动 PMS。

如果警告再次出现，请重新运行 Cloudbeds 连接流程。 重复运行该流程会重试已关联账号的激活。

Catalog 标签页不显示​

你看到的内容： 缺少 Items 或 Add-ons 标签页。

解决方法：

  1. 重新打开 Rooms 页面。
  2. 检查 Cloudbeds 权限提示。
  3. 确认提示包含 read:item、write:item 和 read:addon。
  4. 如果 catalog 标签页仍不显示，请联系支持人员。

你看到的内容： 选择 Connect to Cloudbeds 后没有任何反应。

解决方法：

  1. 刷新 Settings → Essentials。
  2. 再次选择 Connect to Cloudbeds。
  3. 检查网络连接。
  4. 尝试使用其他浏览器或隐私窗口。

安全性​

  • 连接使用安全的 OAuth 2.0
  • AVA 永远不会存储你的密码
  • 可随时从 Cloudbeds 撤销访问权限
  • 连接在 90 天无活动后过期

常见问题​

我可以连接多个 Cloudbeds 物业吗？ 不可以，每个 AVA 账号只能连接一个物业。

断开连接会删除我的数据吗？ 不会，现有数据会保留，但不会更新。

员工可以连接 Cloudbeds 吗？ 不可以，只有管理员可以管理 PMS 连接。

仍然无法解决？​

如果出现以下情况，请联系 success@vouch-technologies.com：

  • ❌ 重新连接后仍出现相同的 OAuth 错误。
  • ❌ Cloudbeds 持续拒绝授权码交换。
  • ❌ 无法确认正确的 Cloudbeds 账号或物业。

建议提供：

  • 错误横幅截图
  • 问题开始的时间
  • AVA 中显示的确切消息