跳到主要内容

手动编码房卡

快速编码

编码器上线后，大多数手动房卡约需 2 分钟即可完成。

本指南帮助你手动编码房卡，并了解 AVA 如何保护现有卡片。

前往： Operations View → Encode Keycard

Operations View 标题栏中的 Encode Keycard 按钮

可用性

只有当 Settings → Room Access 设置为 Keycard Encoding 时，你才会看到 Encode Keycard。

编码权限

能够编码房卡的员工可以使用现有卡片检查功能。 他们不需要浏览 Access Codes 的权限。

Opera 确认

如果你通过 PMS 集成的编码器使用 Opera，AVA 会将单独的 201 视为接受。 随后 AVA 会等待五秒让编码器完成处理，再交还控制权。 它不会使用预订的 roomKeys 元数据来证明一次实体编码已经完成。 明确的终止成功或失败状态仍会原样传递。 如果 Opera 未发送终止结果，请将同一请求重试一次。 AVA 在发送给 Opera 前，会将 Valid From 和 Valid Until 格式化为酒店本地的挂钟时间。 这依赖有效的酒店时区。 如果酒店时区无效，或请求中的时区数据冲突，AVA 会在编码前停止。

确认诊断信息

如果确认失败，支持人员可以查看经过清理的房间快照、预期值、等待延迟、轮询次数和匹配结果。 AVA 不会在此流程中记录客人数据或房卡 PIN 值。

标题级与预订级编码​

AVA 提供两种房卡编码方式。了解它们的区别，有助于你在不更改设置的情况下发放重复卡或额外卡。

方式查找位置房卡数量
标题级（绿色按钮）Operations View 顶部、Help 旁边始终为 1-10，不受设置影响
预订级预订卡片或行上的卡片图标按钮由 Room Access 设置控制
  • 标题级按钮会在不打开预订的情况下启动手动流程。
  • 预订级按钮会为所选预订或房间启动编码。
  • 两种流程都可以在编码前查找现有的手动房卡组。
额外卡片无需重新编码

需要另一张卡时，请使用额外卡片流程。AVA 会自动保护现有卡片。

额外客人入住

如果房间已经办理入住，之后额外入住的客人可以重新打开重复房卡流程。 AVA 会为额外客人的卡片编码，而不会替换现有卡片组。

编码前解析预订房间​

选择编码器后，AVA 会通过经过身份验证的 PMS 查询确认分配的房间。 如果预订卡片没有可用的房间值，AVA 会自动使用该查询。 AVA 接受任何非空的 PMS 房间标识，包括较长的 AVA PMS 标识符。 随后它会使用解析出的房间标识和房号进行房卡查询与编码。

这适用于预订房间访问、入住和钥匙管理。 AVA 会在编码前再次检查房间，并判断实体卡片应为新卡还是重复卡。

编码关联预订的房间​

当关联预订包含多个房间时，AVA 会先检查父级 PMS 响应。 如果该响应未标识所选房间，AVA 会读取所选预订。

  1. 选择要办理入住或编码的房间。

  2. 选择 Manage Pin / Encode Keycard，或继续办理入住。

  3. 等待 AVA 验证所选预订的确认信息和房间。

    ✓ 只有在确认信息和房间严格匹配后，AVA 才会编码。

你不需要输入同一关联预订中其他房间的房号，也不需要更改账单详情。 如果无法验证所选预订，AVA 会出于安全考虑阻止编码。 父级预订已办理入住，不会覆盖所选房间的当前状态。

PMS 房间变更后编码​

如果发放房卡后 PMS 更改了客人的房间，请在再次编码前刷新预订。 AVA 会在联系编码器前读取 PMS 中当前的房间分配。

  1. 在 PMS 中确认新房间。

  2. 在 AVA 中刷新预订或 Operations View。

  3. 打开该预订的 Manage Pin / Encode Keycard。

  4. 为新房间启动房卡流程。

  5. 按照每张卡的编码器提示操作。

    ✓ AVA 会在编码前再次检查房间分配。

房间变更后，AVA 会保留客人验证信息和房卡历史记录。 旧房间已完成的房卡操作不会完成新房间的操作。 如果 PMS 暂时未显示房间，请等待重新分配、刷新后重试。

为今天退房的客人编码​

标记为 DUE_OUT 或 Due Out 的客人，在退房前仍占用该房间。 只要客人仍在房间内，你就可以为其编码房卡。

  1. 在 PMS 中确认客人尚未退房。
  2. 在 AVA 中刷新预订或 Operations View。
  3. 打开 Manage Pin / Encode Keycard。
  4. 启动房卡流程。
  5. 完成编码器提示。

✓ AVA 会在编码前重新执行 PMS 房间和入住状态检查。

退房、取消、尚未到店或房间状态未知后，AVA 会阻止编码。

无需更改房间映射

你不需要缩短或编辑有效的 PMS 房间标识。 只有当编码器房间名称与 PMS 房号不同时，才仍需要房间映射。

AVA 如何选择卡片类型​

AVA 会在每次编码请求期间于服务器端决定有效的卡片类型。 界面上请求的选项不会覆盖房间的当前状态。

房间状态AVA 使用的卡片类型结果
此房间分配不存在卡片NEWAVA 为该房间启动卡片组。
其他客人已持有此房间的卡片DUPLICATE现有卡片继续有效。
此预订已持有此房间的卡片DUPLICATEAVA 安全地添加或重试卡片。
此预订持有其他房间的卡片后发生了房间变更NEW新房间需要新的卡片组。
新卡可能会使之前的卡片失效

某些门锁系统会在 AVA 发送 NEW 时使之前的卡片失效。 请立即将替换卡交给客人。

在共享房间首次编码卡片前，AVA 会向 PMS 查询是否有其他在住客人。 如果 PMS 无法完成该检查，AVA 会保留现有的 NEW 回退逻辑。

开始新的手动房卡组​

对于没有现有手动卡片组的房间，AVA 会为第一张成功编码的卡片使用 NEW。 之后，对于该房间分配的后续卡片，它会使用 DUPLICATE。

新卡片组不需要预订编号

你不需要为新的手动卡片组输入或创建预订编号。 AVA 会在第一张卡片成功编码后自动分配卡片组。

只有在希望之前的卡片停止工作时，才使用替换流程。

快速参考​

字段必填默认值或说明
Select Keycard Encoder是系统会自动选择一个在线编码器。有多个编码器可用时，请选择指定的在线编码器。
Room Number是选择 PMS 房号。编码器房间名称会作为辅助文本显示。AVA 会将此房号发送到 Opera 的 external-room-key 流程。
Guest Name否可选。
Valid From是默认为当前时间。
Valid Until是默认为酒店时区中、按你配置的房卡过期时间计算的明天时间。必须配置有效的酒店时区。
Number of Keycards否默认为 2。可选择 1-10 张整数卡片。

AVA 会拒绝非整数的卡片数量。

房号显示

房间列表会首先显示面向 PMS 的房号。 如果两者不同，AVA 会在括号中显示编码器房间名称。

编码器可用性

动态编码器列表以实时 agent 连接作为事实来源。 如果编码器的 agent 已连接且隧道可访问，AVA 会将其显示为 Online。 静态或直接编码器列表会保留现有行为。

GreatLocks 编码器选择

每一行 GreatLocks 都代表一个实体编码器及其连接的 Windows PC。 有多个编码器在线时，请选择对应所需 PC 的编码器。 所选编码器会处理本次房卡请求。

Kiosk 上下文恢复

从 Kiosk 启动编码时，AVA 会先恢复已保存的 Kiosk 目标和员工验证信息。 发送房卡请求前，它还会重新加载 Kiosk 设置。 如果目标或验证状态发生变化，AVA 会停止请求，并要求你验证设备。

Valid Until 默认值

AVA 使用 Settings → Room Access → Keycard Expiration Time 作为默认的 Valid Until 时间。 酒店保存的 Timezone 也必须有效。 如果无法确定时区，AVA 会在编码前停止。 如果预订没有退房日期，AVA 仍会使用明天该配置时间。

启动编码流程​

  1. 前往 Operations View。

  2. 选择 Encode Keycard。

    ✓ Manual Keycard Encoding 模态框会打开。

  3. 如果只有一个编码器在线，AVA 会自动选择它。

  4. 如果有多个编码器在线，请选择状态为 Online 的目标编码器。 该状态取决于实时 agent 连接。 对于 GreatLocks，请选择连接到所需 Windows PC 的编码器。

  5. 从下拉列表中选择 Room Number。

    ✓ 你会看到 PMS 房号作为主标签。 如果已配置映射，还会看到 (Encoder: ...) 作为辅助文本。

  6. 可选：输入 Guest Name。

  7. 设置 Valid From 和 Valid Until。

  8. 选择 Number of Keycards。

  9. 点击 Encode Keycard。

    ✓ AVA 会检查房间是否已有现有的手动房卡。

  10. 如果 AVA 找到现有卡片组，请继续完成房卡提示。

✓ AVA 会在检查房间后决定安全的卡片类型。 11. 将每张空白卡放在编码器上，并按照屏幕提示操作。

✓ AVA 会显示每张卡片的编码结果。

从预订编码​

  1. 打开 Operations View → Check-ins 或 Operations View → Stay-overs。

  2. 为该预订选择 Manage Pin / Encode Keycard。

  3. 继续完成房卡提示。

  4. AVA 提示时选择一个在线编码器。

    ✓ AVA 会在打开编码模态框前确认分配的 PMS 房间。 较长或看起来像内部标识的 PMS 房间标识仍然有效。

  5. 将每张空白卡放在编码器上，并完成提示。

    ✓ AVA 会尽可能使用房间状态保护现有卡片。

故障排查​

未显示重复卡选项​

你会看到： 你打开预订，但 AVA 没有显示重复卡和新卡选项。

原因： AVA 只有在找到现有手动房卡组时才会显示这些选项。 新房间可以直接打开编码流程。

修复：

  1. 确认预订中的房间和客人正确。
  2. 在 Operations View 中点击 Refresh。
  3. 再次尝试 Manage Pin / Encode Keycard。
  4. 如果需要添加客人姓名用于匹配，请使用手动流程。

无法确定预订房间​

你会看到： 选择编码器后，AVA 显示“我们无法确定此预订的房间”。

修复：

  1. 刷新预订或 Operations View。
  2. 确认 PMS 中已为预订分配房间。
  3. 再次启动预订级编码流程。
  4. AVA 提示时选择一个在线编码器。
  5. 如果 PMS 已分配房间后仍出现此消息，请联系支持人员。

AVA 接受有效的 PMS 房间标识，即使它们看起来很长或像内部标识。 不要手动更改房间标识。

退房客人无法编码​

你会看到： 今天退房的客人无法获得房卡。

原因： AVA 需要当前的 PMS 房间和入住状态结果。 PMS 可能仍在刷新客人的 DUE_OUT 状态。

修复：

  1. 确认客人仍在住且尚未退房。
  2. 在 PMS 中确认预订已分配正确的房间。
  3. 在 AVA 中刷新预订或 Operations View。
  4. 再次打开 Manage Pin / Encode Keycard。
  5. 如果刷新一次后房间状态仍未知，请联系支持人员。

无法检查现有卡片​

你会看到： AVA 显示无法检查房间是否已有现有卡片。

修复：

  1. 点击 Try again。
  2. 房间查询成功后，重试编码流程。
  3. 在使用任何替换流程前，提醒客人之前的卡片可能会停止工作。

匹配到多个现有卡片组​

你会看到： AVA 显示有多个现有手动房卡组与该房间匹配。

修复：

  1. 关闭模态框。
  2. 重新打开手动流程，并输入客人姓名。
  3. 如果仍无法明确匹配，请使用 Access Codes 选择正确的卡片组。

缺少入住日期​

你会看到： AVA 显示缺少入住日期，因此无法重复使用现有卡片组。

修复：

  1. 刷新预订或等待 PMS 同步。
  2. 再次尝试编码流程。
  3. 重试编码流程，并允许 AVA 重新检查房间状态。

缺少 Encode Keycard 按钮​

你会看到： Operations View 中没有 Encode Keycard 按钮。

修复：

  1. 前往 Settings → Room Access。
  2. 将 Room Access Method 设置为 Keycard Encoding。
  3. 返回 Operations View。

Encode Keycard 按钮被禁用​

你会看到： 按钮为灰色，或显示 “Missing merchant ID. Configure your account in Settings.”。

修复：

  1. 在 Settings 中完成账号设置。
  2. 刷新页面。

“No encoders found”​

你会看到： 编码器列表显示 “No encoders found.”。

原因： AVA 只会列出状态实时在线的动态编码器。 该状态来自已连接的 agent 和可访问的隧道。

修复：

  1. 前往 Settings → Room Access。
  2. 添加或启用编码器。
  3. 返回 Encode Keycard。

跳过编码器选择器​

你会看到： AVA 打开编码界面时没有显示编码器选项。

修复：

  1. 确认只有一个编码器在线。
  2. 继续编码。这是预期行为。
  3. 如果需要手动选择，请让另一个编码器上线。

无法验证 Kiosk 设备或编码器​

你会看到： AVA 在编码前停止，并要求你验证 Kiosk 或编码器。

原因： AVA 无法安全恢复 Kiosk 目标、员工验证或编码器设置。

修复：

  1. 关闭编码模态框。

  2. 前往 Settings → Kiosk。

  3. 确认实体 Kiosk 使用的是目标设备行。

  4. 如果该行要求验证，请选择 Re-verify staff device。

  5. 前往 Settings → Kiosk → Device Routing。

  6. 确认 Kiosk 指向目标编码器。

  7. 前往 Settings → Room Access → Keycard Encoding。

  8. 确认目标编码器为 Active 且可用。

  9. 返回 Kiosk，重试一张卡片。

    ✓ AVA 应在发送请求前恢复当前 Kiosk 上下文。

不要依靠已配置编码器的数量来识别目标。 当存在多个可用目标时，请使用明确的 Kiosk 路由或编码器选择。

GreatLocks 需要选择编码器​

你会看到： 因为有多个编码器可用，AVA 无法继续处理 GreatLocks 房卡请求。

原因： 每个 GreatLocks agent 服务一个编码器。 当多个已配置的编码器可以处理请求时，AVA 需要你进行选择。

修复：

  1. 打开编码器列表。
  2. 选择连接到目标 Windows PC 的 GreatLocks 编码器。
  3. 确认其状态显示为 Online。
  4. 继续房卡请求。

如果缺少正确的编码器，请在 Settings → Room Access 中检查其 Encoder ID 和 agent 状态。 如果两行 GreatLocks 使用相同 ID，请编辑这些行并保存唯一 ID。

模态框中的编码器显示为离线​

你会看到： 预订房卡模态框显示编码器离线，但 Settings → Room Access 显示它已连接。

原因： 模态框现在使用与设置页面相同的 agent 连接状态。 如果 agent 已连接且隧道可访问，两个视图应当一致。

修复：

  1. 刷新 Settings → Room Access 和预订模态框。
  2. 在编码器卡片中检查 Registered Agents。
  3. 如果任一视图仍显示离线，请修复 agent 连接或隧道。
  4. 再次尝试编码。

Encode Keycard 返回失败​

你会看到： 模态框关闭并显示请求失败，或你看到 KEYCARD_ENCODE_FAILED。

原因： 编码器返回了 false，因此 AVA 将其视为实际失败。 对于这种情况，它不再显示软成功响应。

修复：

  1. 检查编码器电源、会话和连接状态。
  2. 将同一编码请求重试一次。
  3. 如果再次失败，切换到另一个在线编码器。
  4. 查看编码器日志，或携带完整错误文本联系支持人员。

Opera 中共享客人先于主客人到店​

你会看到： 主客人在 Opera 中仍显示待到店时，共享客人的房卡编码失败。

原因： AVA 必须确认共享客人已实时到店并分配了房间。 在拒绝共享客人先于主客人办理入住的请求前，它会刷新 Opera 的入住状态。

修复：

  1. 确认共享客人在 AVA 或 Opera 中已标记为已到店。

  2. 确认共享客人与主客人使用同一房间。

  3. 刷新预订或 Operations View。

  4. 重试 Manage Pin / Encode Keycard。

  5. 如果共享客人已退房或更换房间，请让其前往前台。

    ✓ Opera 确认共享客人已在该房间到店后，AVA 应会编码房卡。

当共享客人位于其他房间时，此回退流程不适用。 它也不会更改主客人的预订状态。

Opera 时区不匹配​

你会看到： PMS 返回房间钥匙前，模态框就失败了。 你可能会看到时区不匹配或时区无效错误。

原因： AVA 使用酒店配置的时区处理 Opera 房卡。 它会在编码前拒绝无效的酒店时区设置和冲突的请求时区数据。

修复：

  1. 前往 Settings → Essentials → Hotel Basic Details。
  2. 确认 Timezone 设置为酒店实际所在时区。
  3. 如果更改了设置，请保存。
  4. 刷新预订或重新打开手动流程。
  5. 再次尝试 Encode Keycard。

房号看起来正确，但编码使用了其他房间代码​

你会看到： 你选择了房间 101，但编码器日志显示了其他房间值。

修复：

  1. 前往 Settings → Room Access → Keycard Encoder Room Mapping。
  2. 找到所选 PMS 房间。
  3. 确认映射的 Encoder Room Name 正确。
  4. 保存映射，然后再次尝试编码。

Opera 房卡请求超时​

你会看到： 编码流程一直打开，随后显示失败或超时。

原因： AVA 将单独的 Opera 201 视为接受，然后等待五秒让编码器完成处理。 它不会将预订的 roomKeys 元数据视为一次实体编码已完成的证明。 明确的终止成功或失败状态仍会原样传递。 只有在等待窗口结束前未出现终止结果时，请求才会超时。

修复：

  1. 确认房号、卡片数量和有效期仍然正确。
  2. 向 PMS 管理员确认 external room key 流程已启用。
  3. 如果房间已经完成编码，请勿误创建重复卡片。
  4. 从同一预订或手动流程中将同一请求重试一次。
  5. 如果仍然失败，请携带房号、时间和错误消息联系支持人员。

仍然无法解决？​

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

  • ❌ 无法打开手动编码模态框
  • ❌ 每次尝试编码都失败
  • ❌ 完成设置后仍未显示编码器

建议提供：

  • 编码器类型和位置
  • 使用的房号和日期
  • 错误截图