跳到主要内容

设置 Cloudbeds PMS 集成

快速设置

连接 Cloudbeds 通常只需约 10 分钟。 Cloudbeds 现在会请求项目访问权限、只读加购项访问权限，以及酒店、房价和税费的只读权限。

本指南帮助你连接 Cloudbeds。 它会保持预订、住客、客房清洁、支付、房间、货币、酒店、房价以及税费数据同步。 如果 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. 出现对勾 (✓) 即表示已选中

第 2 步：开始连接​

  1. 点击 Connect to Cloudbeds 按钮
  2. 会打开一个新的 Cloudbeds 窗口

第 3 步：授权访问​

  1. 登录你的 Cloudbeds 账号
  2. 查看 AVA 请求的权限
  3. 点击 Authorize 或 Allow
  4. 窗口会自动关闭

AVA 现在请求的权限如下：

权限AVA 的用途
read:hotel查看酒店元数据
read:guest查看住客详情
write:guest更新住客详情
read:housekeeping查看客房清洁数据
write:housekeeping更新客房清洁数据
read:rate查看房价方案数据
read:payment查看支付数据
write:payment更新支付数据
read:reservation查看预订数据
write:reservation更新预订数据
read:room查看房间数据
write:room更新房间数据
read:currency读取物业货币设置
read:taxesAndFees查看税费数据
read:item查看项目目录数据
write:item更新项目目录数据
read:addon查看加购项目录数据
旧连接

如果你是在这次更新之前连接的 Cloudbeds，请重新连接以刷新已授予的只读权限。

第 4 步：验证连接​

  1. 返回 AVA 设置页面
  2. 等待 "Finalizing connection..." 完成（5-10 秒）
  3. 状态会显示绿色对勾
  4. 页面会显示："Cloudbeds Account Linked"

连接完成。

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 无法将回调匹配到你的酒店。确认你登录的是正确的物业账号。
Cloudbeds rejected the authorization code exchange.Cloudbeds 阻止了令牌交换。检查 scope 和 redirect URI，然后重试。
Failed to link Cloudbeds account.AVA 无法映射后端错误。复制完整信息并联系支持。

会自动同步什么​

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

事件发生内容
Reservation createdAVA 会收到通知，并可安排到店前消息
Reservation dates changedAVA 会更新任何已安排的消息
Check-in/out status状态会实时同步

当你在 AVA 中查看预订时，系统会直接从 Cloudbeds 获取最新数据。这样你始终能看到当前信息。

信息

数据主要从 Cloudbeds → AVA 流动。AVA 中的住客更新（例如完成入住）会回传到 Cloudbeds。

Cloudbeds 读取保护

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

Cloudbeds 到店时间更新

当主客人同步时，AVA 可以把预订的 estimated arrival time 发送到 Cloudbeds v3。 同行客人不会更新该时间。 无效、缺失或空值会被忽略，因此 AVA 不会清空已有的 PMS 数据。 如果这项可选更新失败，或者 Cloudbeds 不支持它，客人同步仍会成功。

对住客与员工的影响​

  • 住客表单会根据 Cloudbeds 规则自适应。 必填字段和隐藏字段会随着 Cloudbeds 配置变化，因此住客只会看到需要填写的内容。
  • 预订查询依赖 Cloudbeds。 如果 Cloudbeds 未连接，住客查询步骤会失败。
  • 预订来源标签可以使用 Cloudbeds 来源元数据。 如果预订缺少 sourceName，AVA 会回退到关联的 Cloudbeds 来源名称。
  • 来源采集会在可用时使用关联来源记录。 这样可让酒店来源与渠道来源行为保持一致。
  • 渠道采集发票会保持免收。 当 Cloudbeds v3 将渠道采集发票标记为免收时，AVA 会把应付总额清零，并在 Streamliner 中显示免收状态。
  • 房间状态设置只影响客房清洁同步。 当房间在 AVA 中标记为已清洁时，此设置控制 AVA 向 Cloudbeds 发送 Clean 还是 Inspected。它不会改变住客界面。
  • 估计到店时间同步只使用主客人。 同行客人和无效时间会被忽略，因此 AVA 会保持 PMS 值不变。
  • AVA 请求项目访问和只读加购项访问。 write:addon 是有意不包含的。
  • Cloudbeds 只读范围会在重新连接时刷新。 如果旧授权里没有酒店、房价或税费数据，请重新连接。

断开 Cloudbeds​

仅在以下情况断开连接：

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

断开方法：

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

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

故障排查​

卡在 "Connecting..."​

  1. 等待 30 秒
  2. 刷新页面
  3. 检查互联网连接
  4. 尝试其他浏览器
  5. 关闭弹窗拦截器

Cloudbeds OAuth 错误消息​

你看到的内容： 横幅中显示 Cloudbeds OAuth 提示。

处理方式：

  1. 先阅读提示。
  2. 将提示与上方表格匹配。
  3. 如果提示提到 state、code 或 token exchange，请重新连接 Cloudbeds。
  4. 确认你使用的是 Cloudbeds 管理员账号。
  5. 如果 token exchange 仍失败，请检查 redirect URI。
信息

如果可用，横幅现在会显示 Cloudbeds 自己返回的错误详情。 这样可以为支持团队提供更清晰的起点。

预订未同步​

  1. 等待初始同步 15 分钟
  2. 检查连接状态（应显示绿色）
  3. 尝试断开后重新连接
  4. 验证 Cloudbeds 中是否存在预订

Cloudbeds 访问或物业错误​

你看到的内容： 出现类似 You don't have access to property ID 的提示，或者同一个 Cloudbeds 错误立即再次返回。

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

处理方式：

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

  2. 请 Cloudbeds 管理员检查物业访问权限和权限配置。

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

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

    ✓ 在 Cloudbeds 访问问题修复后，下一次刷新应当成功。

目录标签未出现​

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

处理方法：

  1. 重新打开 Rooms 页面。
  2. 检查 Cloudbeds 权限提示。
  3. 确认提示中包含 read:item、write:item 和 read:addon。
  4. 如果目录标签仍未出现，请联系支持。

弹窗无法打开​

  1. 检查浏览器的弹窗拦截设置
  2. 允许来自 AVA 域名的弹窗
  3. 尝试其他浏览器或隐身模式

安全性​

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

常见问题​

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

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

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

仍然卡住？​

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

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

请附上：

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

相关指南​