跳到主要内容

手动编码房卡

快速编码

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

本指南帮助你手动编码房卡，并选择新卡片如何影响现有卡片。

前往： 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 提供两种房卡编码方式。了解它们的区别，有助于你在不更改设置的情况下发放重复卡或额外卡。

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

需要额外卡片时，请选择 Encode DUPLICATE keycards。现有卡片会继续有效。

额外客人入住

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

编码前解析预订房间​

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

这适用于预订房间访问、入住和钥匙管理。 你的 NEW 或 DUPLICATE 选择不会改变。

无需更改房间映射

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

选择新卡或重复卡​

当 AVA 找到现有的手动房卡组时，会显示两个上下排列的选项。

选项使用时机结果
Encode DUPLICATE keycards需要额外卡片时当前卡片继续有效。
Encode NEW keycards必须替换现有卡片组时之前的卡片失效。
替换卡片会使之前的卡片失效

仅在确实要替换时使用 Encode NEW keycards。请立即将新卡片交给客人。

AVA 会在显示这些选项前检查房间、客人和入住日期。 它会将新请求与现有卡片组保持关联。

开始新的手动房卡组​

对于没有现有手动卡片组的房间，首次编码卡片时请选择 Encode NEW keycards。 AVA 会在首次成功编码时创建新的卡片组。 之后每次请求 Encode DUPLICATE keycards 时，AVA 都会重复使用该卡片组。

新卡片组不需要预订编号

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

只有在希望之前的卡片失效时，才再次使用 Encode NEW keycards。

快速参考​

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

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

房号显示

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

编码器可用性

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

GreatLocks 编码器选择

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

Valid Until 默认值

AVA 使用 Settings → Room Access → Keycard Expiration Time 作为默认的 Valid Until 时间。 如果此设置缺失或无效，AVA 会使用 11:00 AM。 如果预订没有退房日期，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 找到现有卡片组，请选择 Encode DUPLICATE keycards 或 Encode NEW keycards。

✓ 房卡编码流程会按照你选择的操作打开。 11. 将每张空白卡放在编码器上，并按照屏幕提示操作。

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

从预订编码​

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

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

  3. 如果存在现有卡片，请选择 Encode DUPLICATE keycards 或 Encode NEW keycards。

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

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

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

    ✓ 重复卡可以与现有卡片组同时使用。 ✓ 新卡片会替换现有卡片组。

故障排查​

未显示重复卡选项​

你会看到： 你打开预订，但 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 显示无法检查房间是否已有现有卡片。

修复：

  1. 点击 Try again。
  2. 如果查询仍然失败，仅当确实要替换时才选择 Start a new set。
  3. 告知客人之前的卡片可能会失效。

匹配到多个现有卡片组​

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

修复：

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

缺少入住日期​

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

修复：

  1. 刷新预订或等待 PMS 同步。
  2. 再次尝试编码流程。
  3. 仅当之前的卡片应当失效时，才选择 Start a new set。

缺少 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. 如果需要手动选择，请让另一个编码器上线。

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 时区不匹配​

你会看到： 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：

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

建议提供：

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