跳到主要内容

设置 Cloudbeds PMS 集成

快速设置

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

本指南帮助你连接 Cloudbeds。 它会同步预订、客人、客房清洁、付款、房间、货币、酒店、费率和税费数据。 如果 Cloudbeds 拒绝连接，AVA 现在会在错误横幅中显示确切原因。

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查看酒店元数据
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查看附加项目录数据
write:adjustment在受支持的预订更新期间保留费率
现有 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。

客人邮箱更新

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

Cloudbeds 读取保护

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

Cloudbeds 到达时间更新

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

在 ACI 中使用 Cloudbeds 房间选项​

Cloudbeds 支持受保护的 ACI 可入住客房搜索、同类型换房和免费升级。 连接 Cloudbeds 后，不会自动启用任何商户设置。

要启用此功能，请在 Settings → Check-In → Check-In Policy 中打开 Allow ACI room swaps。 如需升级，还要启用 Offer room type upgrades in Assisted Check-In。 保存升级政策前，请先添加已排序的房型组。

Cloudbeds 支持覆盖整个住宿期间的可入住客房，包括需要清洁的房间。 它可以显示已保留房间的详情、同类型换房，以及最多移动两笔预订的方案。 AVA 最多显示三个房间选项。

Cloudbeds 房间选项限制

Cloudbeds 没有经过验证的原子换房操作。 AVA 会执行受保护的移动，并验证房间、房型、费率、总额、客人、日期和关联预订。 未分配房间的客人只能获得同类型选项。 Cloudbeds 不支持编码的房间阻塞提醒策略、VIP 排名或礼遇收回。

如果分配结果未知，请不要立即重试。 先在 Cloudbeds 中核实每笔受影响的预订和费率。 然后使用 AVA 中明确的房间刷新功能。 在刷新成功前，AVA 会继续将房间和访问状态标记为未验证。 在确认房间和费率之前，不要交付钥匙。

现有 Cloudbeds 客人​

当扫描结果没有 Cloudbeds 客人 ID 时，AVA 会检查完整的预订客人列表。 这包括尚未分配房间的客人。

只有在大小写和空格规范化后全名完全匹配时，AVA 才会重新使用现有 Cloudbeds 个人资料。 AVA 还会在重新使用前检查最新的出生日期和证件详情。

匹配结果AVA 的处理
一个完全匹配的姓名，且没有冲突的身份数据重新使用现有 Cloudbeds 客人个人资料
没有完全匹配项像以前一样创建新的客人个人资料
姓名重复或身份数据冲突停止操作并要求员工审核客人
Cloudbeds 预订或个人资料数据不完整停止操作，不创建或更改客人

空白扫描字段不会擦除现有的可选 Cloudbeds 值。 这也包括没有证件的扫描结果。

检查有歧义的匹配

当 AVA 要求审核客人时，不要再创建另一个个人资料。 请先在 Cloudbeds 中确认客人及其身份详情。

费率和可用性​

AVA 会读取 Cloudbeds 的详细每日费率，用于 Operations → Rates & Availability 日历。 日历可以显示价格、房间数量、CTA、CTD 以及最短或最长入住限制。 缺失的房间或费率行仍会显示，便于你识别 Cloudbeds 中不完整的数据。

Cloudbeds 费率计划目录管理与每日费率日历分开。 如果你的物业已启用相关功能，你可能会看到列表、编辑、激活、停用或删除操作。 由于仅包含元数据的计划可能无法销售，AVA 不会创建公开的 Cloudbeds 费率计划。

Cloudbeds 写入操作为异步处理

受支持的 ARI 更改会在 Cloudbeds 处理任务期间返回已接受状态。 AVA 会在显示成功前检查已发布的日历值。 在第一次更改仍处于待处理状态时，不要重复进行相同更改。

Cloudbeds 的能力会分别控制每项操作。 你的物业可能可以编辑限制条件，但价格更改、清除价格或停售仍不可用。 即使可以编辑限制条件，派生价格仍可能是只读的。

对于受支持的写入操作，AVA 会显示 Queued、Failed、Verified 或 Verification timeout 结果。 AVA 检查 PMS 任务和日历读回结果时，验证最多可能需要七分钟。 验证超时时请手动刷新。

自动分配期间的当前房间入住情况​

Cloudbeds 的 housekeeping 状态并不总能显示当前预订的入住情况。 超过离店日期仍处于已入住状态的预订，可能会显示为空房。

自动分配前，AVA 会检查两个来源：

  • Cloudbeds housekeeping 状态
  • 候选房间中实时的已入住预订

对于包含多个房间的 Cloudbeds 预订，AVA 会检查每个匹配的房间和入住日期区段。 重复的预订详情不会让空房显示为已入住。 无需额外的 Cloudbeds 设置。

如果另一笔已入住预订占用了该房间，AVA 会跳过该候选房间。 在店内换房时，该检查也会保护所选目标房间。

必须验证空房状态

Cloudbeds 中缺失、不完整或不可靠的入住数据不能证明房间为空。 在 Cloudbeds 返回完整证据前，AVA 会继续将该房间视为不可用。

明确的手动房间分配会保留现有的 Cloudbeds 行为。 房间锁定和严格的房间目标也会保留。

如果 AVA 无法分配房间，请在 Cloudbeds 中检查预订和 housekeeping 状态。 然后刷新 AVA，并仅重试一次分配。

付款入账行为​

Cloudbeds 的共享账单会针对共享父预订入账一笔合并付款。 AVA 会保留房间级别的追踪元数据，以便员工之后审计分配情况。 如果预订不使用共享账单，AVA 会照常逐个预订入账。

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

  • Gateway Transaction ID：支付网关交易标识符。
  • Payment Reference：AVA 付款参考号。

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

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

对 Cloudbeds 付款进行对账​

  1. 在 AVA 中打开预订，并记下其 Transaction ID 或付款参考号。

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

  3. 找到 AVA 入账的付款。

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

    ✓ 金额、付款方式和参考号应能识别出同一笔付款。

对于共享账单，请检查共享父预订的 folio。 Cloudbeds 会为该共享账单显示一笔合并付款。

对客人和员工的影响​

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

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

断开 Cloudbeds 连接​

仅在以下情况下断开连接：

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

断开连接：

  1. 前往 设置 → Essentials
  2. 点击 Disconnect from Cloudbeds
  3. 出现提示时确认
警告

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

故障排除​

连接卡在“正在连接……”​

  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。

预订未同步​

  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 访问问题后，下一次刷新应能正常工作。

需要审核客人身份​

**你看到的内容：**AVA 要求员工在登记或入住期间审核客人。 消息可能包含 GUEST_BOOKING_MATCH_REVIEW_REQUIRED。

**原因：**Cloudbeds 发现姓名重复或身份详情冲突。 AVA 会在创建或更改客人个人资料前停止操作。 AVA 将此视为身份审核，而不是一般同步或容量失败。 受影响的客人会保持待处理状态，AVA 不会根据这次失败的同步分配房间。

解决方法：

  1. 在 Cloudbeds 中打开预订。

  2. 检查客人的全名、出生日期和证件详情。

  3. 根据酒店政策更正重复或错误的预订客人记录。

  4. 在 AVA 中刷新预订。

  5. 仅重试一次客人登记。

    ✓ AVA 应能安全地重新使用正确的个人资料或创建新的个人资料。

如果预订详情正确但仍要求审核，请联系支持人员。

缺少 Cloudbeds adjustment 权限​

**你看到的内容：**入住人数编辑返回 PMS_RATE_PRESERVATION_ADJUSTMENT_SCOPE_MISSING。

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

解决方法：

  1. 停止重试入住人数编辑。

  2. 前往 设置 → Essentials。

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

  4. 批准 write:adjustment 权限。

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

    ✓ 权限启用后，AVA 应能接受新的入住人数编辑。

缓存的权限检查

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

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

**你看到的内容：**入住人数编辑返回 PMS_RATE_PRESERVATION_SOURCE_TAX_UNSUPPORTED。 消息表示 Cloudbeds 的入住人数未更改。

**原因：**该预订的来源税费规则不受支持。 AVA 会在写入入住人数前停止，以防止无法恢复的重新定价。

解决方法：

  1. 在 Cloudbeds 中打开预订。

  2. 确认预订来源和目标房型。

  3. 查看来源的税费。

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

  5. 刷新 AVA，然后只重试一次入住人数编辑。

    ✓ Cloudbeds 提供受支持的来源策略后，编辑应会继续。

不要绕过来源检查

在确认 Cloudbeds 中的预订总额之前，不要手动更改入住人数。 如果来源规则看起来受支持，但 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. 前往 设置 → Essentials。

  2. 选择 Cloudbeds 提供商卡片。

  3. 点击 Save。

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

    ✓ Cloudbeds 现在是活动 PMS。

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

目录标签页不显示​

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

解决方法：

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

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

解决方法：

  1. 刷新 设置 → 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 中显示的确切消息