房卡编码器故障排查

快速修复

先检查网络和电源，然后重新尝试编码一张卡。这大约需要 2 分钟。

本指南帮助你解决常见的房卡编码器问题。

快速参考

你看到的情况	原因	处理方式
编码器无响应	电源或网络问题	检查连接
“We could not determine the room for this reservation.”	PMS 房间查询没有返回可用房间	重试房间解析
房间入住状态显示 Unknown 或房卡编码被阻止	AVA 无法验证准确分配房间的入住状态	刷新分配房间状态
关联预订仍无法编码	所选确认号缺失、不明确，或未通过 PMS 验证	验证所选预订
卡片无法编码	卡片类型或设备问题	验证卡片和设备
有些卡成功、有些失败	手动编码会分别返回每张卡的结果	查看每张卡的结果
简明房卡失败	AVA 已规范化供应商或会话错误	阅读消息
Adem 提示卡片不是空白卡	卡片中已经包含数据	使用空白 Adem 卡
房卡超时指引	供应商服务器或软件未及时响应	检查供应商服务
“Invalid Saflok configuration” 或 “UserCredentialsNotProvided.NotApplicable”	Saflok 凭据缺失、不完整或已禁用	修复 Saflok 配置
Saflok/Ambiance 编码失败或超时	Windows Agent、Ambiance 编码器服务或设备离线	重启 Saflok/Ambiance 编码器
“Please create a new keycard first, then use Duplicate for any extra cards.”	Saflok 找不到该预订的现有活动注册	修复缺失的第一张房卡
晚到的共享住客收到 DUPLICATE 第一张卡	房间内已有另一位住客	保持现有住客的房卡有效
多房间 Saflok/Ambiance 卡需要房间级 ID	所选房间尚无自己的子预订	检查所选房间
“The keycard encoder is temporarily offline. Please approach the Front Desk for assistance.”	编码器没有活动会话	检查编码器会话
PMS 搬房后编码停止	房卡会话打开后房间发生变化	刷新并重启编码
出现原始 DoorLock generate fail 或 internal error	技术房间访问载荷泄露到弹窗	使用通用重试路径
“Request timezone does not match the hotel timezone” 或 “Hotel timezone configuration is invalid”	酒店时区缺失、无效或与请求元数据冲突	检查 Opera 时区设置
编码器类型更改不生效	保存留下混合状态	重新保存类型
“Test Connection” 失败（Be-Tech）或 agent 保持离线	Base URL、adapter 或服务问题	修复 Be-Tech 连接
Be-Tech 客户端或服务在重启或手动停止后停止	agent 正在恢复本地供应商客户端	等待 Be-Tech 恢复
“Make sure the Be-Tech client program is running on the encoder computer.”	Windows Agent 返回 502 供应商不可用响应	检查 Be-Tech 客户端程序
“Test Connection” 失败（GreatLocks）	已保存的 GreatLocks 服务器详情缺失或过期	修复 GreatLocks 连接
GreatLocks 要求选择编码器	有多个服务器或 agent	选择编码器
GreatLocks 清单无法加载	agent 隧道、服务器记录或清单来源问题	检查 GreatLocks 清单同步
PMS 编码器发现无结果	供应商错误或无终端	检查 PMS 发现
Opera 路由不明确或不完整	Opera 返回了重复或缺失的 Door Lock 路由详情	修复 Opera 路由详情
读卡时出现 “OPERAWS-FOF01920”	发送给 Opera 的接口值过期或无效	刷新 Opera 路由
读卡时出现 “OPERAWS-FOF00199”	Opera 无法连接配置的 Door Lock System	检查 Door Lock 连接
PMS 读卡不可用	设置、能力或编码器问题	检查 PMS 读卡
未检测到卡片	读卡器未找到卡	重新插卡
卡片类型不支持	编码器无法识别类型	使用受支持卡片
卡片无法读取	编码器无法读取数据	尝试其他卡
Opera 读卡一般性失败	响应为空或无效	检查响应
PMS kiosk 无法解析编码器	Device Model 与旧版 kiosk 映射使用不同标签	检查 PMS kiosk 映射
请求验证 kiosk 或编码器	已保存的 kiosk 上下文、员工验证或目标设置已改变	验证 kiosk 目标
Adem 设置无法保存	供应商定义的设置或编码器条目规则缺失	验证 Adem 设置
“Test Connection” 失败（Adem）	已保存配置、Windows Agent、SQL Server 或读卡器不可用	修复 Adem 连接
Adem 读卡诊断返回意外结果	所选端口、SQL 设置、读卡器状态或 SDK 返回了诊断结果	解读 Adem 诊断
Adem 共享 agent 拒绝编码器	共享编码器使用 USB 0 或重复的 COM 端口	修复 Adem 端口分配
“Service URL is required”（LockSDK）	直连模式要求每个编码器配置 Service URL	添加 LockSDK Service URL
LockSDK agent 显示 Not registered	尚未创建该编码器专用的 agent 设备	注册 LockSDK agent
Heartbeat Monitor 保存后关闭	当前酒店会话中的保存未持久化	重新保存 Heartbeat Monitor
Heartbeat unreachable	agent 或隧道离线	检查状态
Heartbeat unknown	AVA 无法验证状态	检查 unknown
Heartbeat 报告状态或隧道错误	诊断检查或 agent 隧道失败	检查报告的错误
Google Chat 报告编码器问题	编码器短暂失败、已恢复或仍然停机	按提醒处理
编码器仍不可用	动态列表认为 agent 断开	检查实时状态
Windows Agent Not connected	agent 未运行或安装不完整	重新连接
“This Windows Agent is too old to read keycards”	已安装的 agent 不包含 Read Keycard	更新 Windows Agent
Pending encoder setup sync	保存的分配与 agent 已应用的设置不同	同步 agent 设置
“The encoder tunnel is offline”	Universal Encoder Agent 隧道不可用	重新连接编码器隧道
Windows 请求权限	托盘服务控制需要提升权限	批准 UAC 提示

无法解析预订房间

你会看到： 选择编码器后，AVA 显示 "We could not determine the room for this reservation."。

原因： 已验证的 PMS 查询没有返回可用房间标识。

解决方法：

1. 刷新预订或 Operations View。
2. 确认 PMS 中已分配房间。
3. 重新开始预订、入住或房卡管理流程。
4. AVA 询问时选择在线编码器。
5. 消息仍出现时联系支持。

AVA 接受有效 PMS 房间标识，包括较长的 AVA PMS 标识符。不要手动缩短或编辑它。

分配房间的入住状态未知

你会看到： 房间入住状态显示 Unknown，或 AVA 阻止房卡编码。

原因： AVA 无法验证准确分配房间的入住状态。它不会用其他房间的入住状态代替该状态。

解决方法：

1. 在 PMS 中确认预订已分配正确的房间。

2. 确认该房间属于所选预订，而不是关联的同组预订。

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

4. PMS 更新显示后，再次开始房卡流程。

5. 刷新一次后入住状态仍未知时，联系支持团队。

   ✓ 只有在分配房间的入住状态得到验证后，AVA 才应编码。

无法验证关联预订的房间

你会看到： 关联预订中的次要房间仍无法编码。

原因： 所选房间的确认号缺失，或与其 PMS 房间不匹配。上游 PMS 读取也可能失败，或返回多个可能的房间。

解决方法：

1. 在 PMS 中确认所选房间及其确认号。
2. 在 AVA 中刷新预订或 Operations View。
3. 再次打开所选房间并重试房卡编码。
4. 不要使用旧房间号来选择同组的其他预订。
5. PMS 响应仍不明确或不可用时，联系支持团队。

AVA 会在编码前检查所选预订。对于已搬房、已退房或错误的同组房间，系统会阻止编码，而不是发放不安全的房卡。

搬房后仍显示旧房卡状态

你会看到： 编码过程中房间发生变化，或 AVA 显示旧的房卡状态。

原因： 房卡会话打开后，PMS 分配发生了变化。AVA 会在调用实体编码器前阻止过期请求。

解决方法：

1. 在 PMS 中确认新的房间分配。

2. 出现冲突后让 AVA 刷新预订。

3. 旧编码会话关闭后，重新打开房卡操作。

4. 编码前确认刷新的房间号。

5. 新房间的第一张卡选择 NEW。

6. 该房间的其他卡选择 DUPLICATE。

   ✓ 过期尝试不会调用编码器。 ✓ 刷新的房间需要新的住客操作。

不要在已关闭的会话中持续点击 Try Again。如果刷新失败，AVA 会关闭会话并显示错误。手动刷新预订，然后重新打开房卡操作。

AVA 会保留住客验证信息和之前的房卡历史记录，不会将旧房间的完成状态用于新的分配。如果 PMS 暂时没有显示房间，请等待重新分配、刷新后重试。

晚到的共享住客收到重复卡

你会看到： 共享住客稍后通过 ACI 抵达，且属于同一预订。即使该住客之前没有房卡，AVA 仍会请求 DUPLICATE 卡。

原因： 预订中的另一位住客已经在房间内。AVA 会保护在住住客的房卡，避免新卡将其取消。

解决方法：

1. 确认共享住客与已入住的住客分配到同一房间。
2. 让 AVA 继续使用 DUPLICATE。
3. 另一位住客仍在房间内时，不要将请求改为 NEW。
4. 如果编码器拒绝重复卡，请按照显示的错误说明操作。
5. 如果错误是暂时性的，刷新预订后重试一次。
6. 编码器仍持续拒绝房卡时，联系支持团队。

当前抵达决策

由当前抵达决策办理入住的住客仍使用正常的第一张卡行为。同一预订中更早抵达的住客会被视为已经在房间内。

编码器无响应

你会看到： 编码器在 AVA 中离线或无响应。

解决方法：

1. 检查电源和线缆。
2. 验证 kiosk 与编码器网络连接（仅限 Direct Connection）。
3. 确认服务器 IP 和端口正确。
4. 重启编码器软件。

卡片无法编码

你会看到： 房卡写入失败或生成空白卡。

解决方法：

1. 确认卡片类型匹配编码器。
2. 重新插卡并重试。
3. 使用新空白卡测试。
4. Enable guest selection 关闭时，确认 kiosk 路由正确。
5. 开启时，确认客人在 kiosk 选择在线编码器。

规范化的编码失败

你会看到： 弹窗显示简短自然语言消息，而非原始供应商字符串。

原因： AVA 会在显示消息前保留并规范化 Saflok、Be-Tech、Adem、Opera 以及内部会话失败。它会优先使用结构化消息，必要时再回退到旧版供应商字符串解析。HTTP 504 房间访问超时也使用此路径，并标记为 KEYCARD_VENDOR_TIMEOUT。员工提醒和相关日志详情使用同一规范化失败类别。例如，卡片已插入时发生的错误不会报告为 No card detected。

解决方法：

1. 先阅读简短消息。
2. 在支持视图查找 userMessage、errorCode、retriable、供应商名称和安全 upstream 详情。
3. 联系支持时提供这些详情。
4. 将消息与最可能的修复方式对应起来：
   • Occupied room：刷新预订，然后重试。
   • Encoder offline：检查电源、网络或 agent 状态。
   • No card detected：重新插卡并检查放置位置。
   • Unsupported card type：使用此编码器支持的卡片类型。
   • Card could not be read：尝试另一张卡并检查是否损坏。
   • No active session：重新连接编码器会话。
   • Missing mapping：确认房间映射正确。
   • Invalid room or date：核对入住日期和房间分配。
   • Vendor auth, gateway, or timeout：检查供应商访问权限，或稍后重试。
   • HTTP 504 timeout：短暂等待后重试。
   • Adem card is not blank：使用备用空白卡，或先请获授权的员工在 Adem 中擦除可重复使用的卡片。
   • Invalid request：重新打开正确的预订并重试。
5. retriable 为 true 时刷新后重试。
6. retriable 为 false 时先修复映射或供应商问题。

有些卡成功、有些失败

你会看到： 手动批量操作同时报告成功和失败的卡片。

原因： AVA 会分别处理每张卡，并保留每张卡的结果。即使单张卡失败，批量操作仍可能返回 HTTP 200。

解决方法：

1. 查看 Success count 和 Failure count。
2. 将标记为成功的卡片交给住客。
3. 阅读每张失败卡片上的指引。
4. 修复当前问题后，再重试失败的卡片。
5. 只重试标记为可重试或显示重试指引的卡片。

房卡超时指引

你会看到： AVA 提示在重试前确认房卡供应商的服务器或软件正在运行且工作正常。

原因： 供应商未能在 AVA 的房卡请求超时前作出响应。

解决方法：

1. 检查供应商服务器是否已开机且可以访问。
2. 检查供应商的房卡软件或本地服务是否正在运行。
3. 确认编码器电脑可以通过网络访问供应商服务。
4. 如有需要，重启服务后短暂等待。
5. 只重试一次房卡操作。
6. 如果再次重试仍失败，打开 Command Center → Status → View Details。
7. 联系支持时提供显示的错误代码。

超时指引会以你选择的 AVA 语言显示。 它仅适用于房卡供应商。 智能锁超时仍使用常规房间访问指引。

旧版回退仍处于启用状态

较旧的响应仍可能显示旧版供应商字符串。 AVA 保留此解析路径，因此历史日志和较旧的集成仍可正确读取。

Adem 卡不是空白卡

你会看到： Adem 报告卡片不是空白卡。 支持详情中还可能显示代码 0xFFFF0007。

原因： 卡片中已经包含数据，并且 Adem 的默认覆盖设置已禁用。 AVA 不会自动擦除或覆盖卡片。

解决方法：

1. 从编码器中取出被拒绝的卡片。

2. 使用新的空白备用卡。

3. 重试 Create Keycard。

4. 如果必须重复使用该卡，请先让获授权的酒店员工在 Adem 锁软件中擦除卡片。

5. 擦除完成后再重试。

   ✓ 面向员工的消息会提示使用空白卡。 ✓ 预订和房间映射保持不变。

不要持续重试同一张被拒绝的卡片。 如果使用空白卡仍然失败，请向支持团队提供数字代码和原始供应商消息。

酒店时区阻止房卡编码

你会看到： PMS 返回房间钥匙前，房卡流程停止。你可能会看到 "Request timezone does not match the hotel timezone" 或 "Hotel timezone configuration is invalid"。

原因： AVA 会将房卡有效期格式化为酒店本地墙上时钟时间，而不是 UTC。酒店时区缺失或无效时，系统会安全停止；请求时区数据冲突时也会停止。手动房卡流程和基于预订的房卡流程使用同一个已保存的酒店时区。

解决方法：

1. 前往 Settings → Essentials → Hotel Basic Details。
2. 确认 Timezone 有效并匹配本地时钟。
3. 更新后保存。
4. 刷新预订或重新打开流程。
5. 重试房卡请求。

保存设置后，AVA 会使用最新保存的时区。它不会回退到 UTC 或其他默认时区。

保存设置后，AVA 使用最新保存的时区。它不会回退到 UTC 或其他默认时区。

Saflok/Ambiance 编码无法工作

你会看到： 编码失败、超时或 kiosk 报告无响应。

解决方法： 按顺序完成三个检查，每一步先排除一个常见原因。

Saflok 自动恢复

Saflok PMSI 启动较慢或重启时，AVA 每 10 秒重新检查就绪状态。稍等并刷新，再考虑重新安装 agent。

1. 检查 Windows Agent 是否已连接到 AVA

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

2. 找到 Windows Agent 卡片。

3. 确认状态 Connected 且 Last Seen 较新。

   

4. 如果 agent 显示 Not connected，继续前先参阅 Windows Agent 未连接。如果 Saflok PMSI 仍在启动，请等待 10 秒并刷新一次，然后再重新安装任何内容。

2. 检查 Ambiance 中的编码器是否在线

agent 已连接但编码仍失败时登录 Ambiance。

如果 agent 已连接但编码仍失败，请登录 Ambiance 服务器并验证编码器设备。

1. 打开 Ambiance，进入 Device Management → Encoders。

2. 找到此 kiosk 的编码器（例如 Vouch 编码器）。

3. 确认 Status 显示 Online。

   

4. 如果编码器显示 Offline，继续第 3 步重启编码器服务。

3. 重启 Ambiance Encoder Service

如果编码器在 Ambiance 中离线，请在安装 Ambiance 服务器的电脑上重启编码器服务。

1. 在运行 Ambiance 服务器的电脑上，按 Windows 键或点击 Start 菜单。

2. 输入 services manager，从结果中打开 Ambiance Services Manager。

3. 在服务列表中选择 Ambiance Encoder Service。

   

4. 点击 Stop（红色方块）按钮。

5. 等待几秒，直到服务状态变为 Stopped。

6. 点击 Start（红色播放）按钮。

7. 确认 State 恢复为 Running。

8. 返回 Ambiance 的 Device Management → Encoders，确认编码器为 Online。

9. 从 kiosk 尝试编码测试卡。

为什么重启有效

网络短暂中断或长时间空闲后，编码器服务可能失去与实体编码器的连接。停止并重新启动服务会强制重新建立连接。

Saflok 复制卡需要先有第一张房卡

你会看到： AVA 显示 "Please create a new keycard first, then use Duplicate for any extra cards."

原因： Saflok 找不到该预订的活动注册或房卡记录。AVA 添加更多房卡前，必须先成功创建第一张房卡。

当 Saflok 拒绝请求的复制卡时，就会出现此错误。对于晚到的共享住客，AVA 可能会有意请求 DUPLICATE，以保护房间内另一位住客的房卡。确认房间内没有住客之前，不要切换为 NEW。

解决方法：

1. 确认房间内是否已有其他住客。
2. 如果有，刷新预订，然后重试一次 DUPLICATE 请求。
3. 如果没有，为该预订创建第一张房卡。
4. 等待第一张房卡成功编码。
5. 只有第一张房卡存在后，才选择 Duplicate。
6. 错误再次出现时，确认 Ambiance 中该预订仍有活动注册。
7. 编码器仍拒绝正确的卡片类型时，联系支持团队。

你不应该看到的内容

消息中不应出现原始 ReservationNotFound 或 SOAP fault 详情。

Saflok/Ambiance 多房间房卡需要房间级预订 ID

你会看到： 为多房间住宿中的一个房间编码时，AVA 停止流程。

原因： 复制卡使用所选房间的子预订 ID；没有该 ID 就会快速失败。

解决方法：

1. 打开预订并选择所需的确切房间行。
2. 房间刚拆分或移动时等待 PMS 同步。
3. 确认它在 PMS 中是独立子预订。
4. 再次尝试 Encode Keycard。

编码器没有活动会话

你会看到： AVA 显示 "The keycard encoder is temporarily offline. Please approach the Front Desk for assistance."

原因： 编码器没有活动会话，AVA 将其视为离线就绪问题。

解决方法：

1. 确认通电并连接。
2. 刷新 Settings → Room Access → Keycard Encoding。
3. 检查 Online 或 Connected。
4. 会话恢复后再编码。
5. 仍失败时使用其他编码器或联系支持。

原始房间访问载荷出现在弹窗中

你会看到： 弹窗显示 DoorLock generate fail! 或 internal error。

原因： AVA 捕获技术性房间访问 blob，并回退到通用重试消息。

解决方法：

1. 关闭弹窗。
2. 等待几秒。
3. 再次编码。
4. 消息再次出现时确认在线。
5. 仍失败时切换编码器或联系支持。

未提供 Saflok 凭据

你会看到： AVA 在编码房卡时显示 "Invalid Saflok configuration"。你也可能看到 "Saflok credentials not configured"、"Saflok configuration incomplete" 或 "Saflok encoder is disabled"。旧版 agent 响应可能显示 "UserCredentialsNotProvided.NotApplicable"。

原因： Saflok 无法使用已保存的配置启动。AVA 将此错误标记为 CREDENTIAL_CONFIG_INVALID，且不可重试。再次尝试同一张卡之前，请先修复设置。

解决方法：

1. 前往 Settings → Room Access → Keycard Encoding。
2. 将 Encoder Type 设为 Saflok。
3. 确认已启用 Saflok 编码器。
4. 在 Encoder Credentials 中输入 Username 和 Password。
5. 开启直接通信时，输入 PMSI Server URL。
6. 使用 Windows Agent 时，确认连接方式和 agent 状态。
7. 点击 Save。
8. 点击 Test Connection，然后编码一张测试卡。

Saflok 连接方式

直接通信需要 PMSI Server URL、Username 和 Password。 Windows Agent 模式仍需要 Username 和 Password，由 agent 提供 PMSI 连接。

编码器类型更改没有生效

你会看到： 选择一种类型后另一种仍活动。

解决方法：

1. 前往 Settings → Room Access → Keycard Encoding。
2. 在 Keycard Encoder Settings 选择类型。
3. 只点击一次 Save 并等待成功消息。
4. 刷新并确认只有该类型活动。
5. 问题重复时切换、保存，再切回并保存。

PMS 编码器发现没有返回结果

你会看到： 点击 Load Encoders 后没有 PMS 终端。

原因： PMS vendor 不匹配，或 PMS 没有公开终端。

解决方法：

1. 前往 Settings → Room Access → Keycard Encoding。
2. 确认 PMS vendor 匹配酒店。
3. 再次点击 Save。
4. 返回 Physical Encoder Devices，点击 Load Encoders。
5. 列表为空时确认 PMS 集成活动。
6. 仍无终端时联系支持并提供供应商及酒店名称。

PMS 读卡不可用

你会看到： Entitlements 没有 Start scanning，或提示物理房卡读取不可用。

原因： 读取禁用、PMS adapter 不支持或能力查询暂不可用；还需要活动 PMS 编码器。

解决方法：

1. 前往 Settings → Room Access → Keycard Encoding。
2. 选择 PMS Integration。
3. 确认已开启 Enable PMS Encoder Integration。
4. 确认 PMS vendor 与酒店匹配。
5. 确认发现的编码器为 Active。
6. 开启 Enable physical keycard reading，然后点击 Save。
7. 重新加载 Entitlements，检查 Start scanning。
8. 读卡不可用时使用 Look up by room 或 Look up by confirmation number。

PMS 读卡直接使用 PMS transport，不需要 Universal Encoder Agent 会话。如果警告仍存在，PMS adapter 可能尚未声明支持读卡。

Opera 路由不明确或不完整

你会看到： 加载编码器后 Opera 读卡仍不可用。

原因： Opera 返回了重复或不完整的 workstation、编码器、接口或 outbound-code 详情。AVA 会安全停止，而不会将读卡请求发送到错误的 Door Lock 路由。

解决方法：

1. 前往 Settings → Room Access → Keycard Encoding。
2. 确认 PMS vendor 为 Opera。
3. 确认目标编码器为 Active。
4. 点击 Load Encoders，正确终端出现后点击 Add Selected。
5. 请 Opera 管理员修正重复或缺失的 Door Lock 接口详情。
6. 编码器目录修正后重新加载 Entitlements。
7. 期间使用 Look up by room 或 Look up by confirmation number。

如果 Opera 确认存在一个明确的路由后仍不可用，请联系支持团队。

Opera 接口验证错误

你会看到： 读卡显示 OPERAWS-FOF01920 或接口编号验证错误。

原因： Opera 拒绝接口值，旧路由可能仍在缓存。

解决方法：

1. 前往 Settings → Room Access → Keycard Encoding。
2. 确认 Opera 编码器的 workstation 和 encoder ID 与实体设备匹配。
3. 点击 Load Encoders，然后为当前终端点击 Add Selected。
4. 确认编码器为 Active。
5. 重新加载 Entitlements，然后再次尝试 Start scanning。
6. 扫描仍失败时使用 Look up by room 或 Look up by confirmation number。

AVA 使用类似 SL01 的值选择 Door Lock 路由，并使用数字 outbound code 读取。不要编辑接口值。

重新加载当前编码器后仍返回 OPERAWS-FOF01920 时，联系支持团队。

Opera Door Lock System 超时

你会看到： 读卡显示 OPERAWS-FOF00199 或 Door Lock System 超时。

原因： Opera 接受请求但无法连接 Door Lock System，这是连接问题而非未检测到卡片。

解决方法：

1. 确认 Saflok 接口和编码器已通电。
2. 检查酒店网络到 Door Lock System 的连接。
3. 确认 Opera Door Lock 接口在线。
4. 重新插卡并尝试一次 Start scanning。
5. 接口离线时使用 Look up by room 或 Look up by confirmation number。
6. 请 Opera 管理员检查 Door Lock System 和编码器连接。

不要将错误视为 No card detected。如果接口显示在线但读卡仍持续超时，请联系支持。

不支持卡片类型

你会看到： AVA 表示类型不支持或无法识别。

原因： 卡片存在，但编码器不识别其类型。

解决方法：

1. 取出卡片。
2. 确认使用认可的卡片类型。
3. 放置受支持的空白卡。
4. 再次编码。
5. 消息再次出现时请经理确认设置。

不要继续反复调整不支持类型的卡片位置。

无法读取卡片

你会看到： AVA 表示无法读取或读卡失败。

原因： 卡片存在但无法读取数据，可能损坏、不兼容或放置错误。

解决方法：

1. 取出并检查损坏。
2. 正确的一面朝上重新插入。
3. 错误再次出现时尝试另一张受支持卡片。
4. 多张卡都无法读取时联系支持。

未检测到卡片

你会看到： 启动 PMS 扫描后 AVA 报告未检测到卡片。

原因： 读卡器没有找到卡片。

解决方法：

1. 取出并正确插入卡片。
2. 等待读卡器完成后再次扫描。
3. 仍无法读取时使用房间或确认号查询。
4. 多张已知正常卡片都返回无卡时联系支持。

Opera 读卡显示一般性失败

你会看到： Opera 返回 HTTP 200 后出现一般性 PMS 读卡失败。

原因： Opera 可能返回离店日期和时间范围。AVA 接受非空范围并使用结束时间；空或格式错误范围无效。

解决方法：

1. 确认卡片由 Opera 编码且属于预期预订。

2. 重新插卡并选择 Start scanning。

3. 没有房间时使用房间或确认号查询。

4. 持续失败时使用手动查询并请管理员检查数据。

5. 联系支持并提供扫描时间、酒店和编码器名称。

   ✓ 有效 Opera 卡片应显示读取数据，即使没有房间。

PMS kiosk 编码器映射未解析

你会看到： PMS kiosk 无法编码，虽然编码器在 Physical Encoder Devices 中。

原因： Device Model 与旧版映射可能使用不同标签；AVA 先使用前者再回退。

解决方法：

1. 前往 Settings → Kiosk → Device Routing 检查目标映射。

2. 确认匹配 PMS 编码器为 Active。

3. 目标改变时用当前 PMS 名称保存。

4. 从 kiosk 重试测试卡。

   ✓ AVA 应解析到活动 PMS 编码器并发送请求。

缺少编码器时参阅 PMS 编码器发现没有返回结果。

无法验证 kiosk 设备或编码器

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

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

解决方法：

1. 关闭编码弹窗。

2. 前往 Settings → Kiosk。

3. 确认实体 kiosk 使用预期的设备行。

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

5. 打开 Device Routing，确认 kiosk 目标。

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

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

8. 返回 kiosk，再试一张卡。

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

不要根据已配置编码器的数量来判断目标。存在多个目标时，请使用明确的路由或编码器选择。

Be-Tech 测试连接失败

你会看到： "Test Connection" 失败或按钮禁用。

直接配置 Base URL 或出现一般请求失败时使用此方法；客户端消息请使用 Be-Tech 客户端程序不可用。

Be-Tech 可达性检查

AVA 将 405 响应视为可达，因为某些 Be-Tech 部署不支持检查所用的方法。它将 401、404 和 5xx 响应视为不可用。

解决方法：

1. 确认 Base URL 以 http:// 或 https:// 开头。
2. 验证服务在编码器工作站运行。
3. 检查工作站和 kiosk 是否处于同一网络。
4. 使用 Windows Agent 时，确认 agent 卡片为 Connected。
5. 重新输入 Hotel Name、Chain No、Workstation 和 Reader No。
6. 再次点击 Test Connection。

Be-Tech 客户端或服务在重启或手动停止后停止

你会看到： Windows 重启或手动停止后客户端或服务停止，AVA 可能短暂显示不可用。

原因： Be-Tech 客户端可以独立于 Windows Agent 启动。托盘现在会检测已安装的客户端，并自动恢复其服务。

解决方法：

1. 让 Windows Agent 服务继续运行。
2. 等待托盘显示 Be-Tech 恢复通知。
3. 等待显示 Be-Tech 客户端服务已重新运行的通知。
4. 刷新 Settings → Room Access → Keycard Encoding。
5. 确认 agent 和编码器为 Connected 或 Online。
6. 重试房卡操作。

自动重试

恢复失败时，托盘会自动重试。只有恢复持续失败时，才使用托盘的 Restart 操作。

多个安装时询问部署管理员 BETECH_CLIENT_PATH；路径必须指向可信的 Program Files 安装。

Be-Tech 客户端程序不可用

你会看到： AVA 显示 "Make sure the Be-Tech client program is running on the encoder computer."

原因： Windows Agent 无法连接本地 Be-Tech 客户端服务。

解决方法：

1. 前往编码器电脑。
2. 检查 Windows 托盘中的 Be-Tech 恢复通知。
3. 稍等片刻，然后刷新 Settings → Room Access → Keycard Encoding。
4. agent 仍离线时，使用托盘的 Restart 操作。
5. 再次点击 Test Connection。

其他 Be-Tech 故障

如果看到 Be-Tech request failed，请参阅 Be-Tech 测试连接失败。客户端程序专用消息只适用于 502 vendor-unavailable 响应。

GreatLocks 测试连接失败

你会看到： 编辑服务器详情后 Test Connection 失败。

解决方法：

1. 前往 Settings → Room Access → Keycard Encoding。
2. 确认第一个活动行有 XHLSI Server IP Address 和 TCP Port。
3. 点击 Save。
4. 更新旧配置时保留服务器记录。
5. 再次 Test Connection。

需要选择 GreatLocks 编码器

你会看到： 操作要求选择编码器。

原因： 每个 Universal Encoder Agent 服务一个 GreatLocks 编码器；多个目标时无法安全选择。

解决方法：

1. 打开 Physical Encoder Devices。
2. 确认每行恰有一个 Encoder ID，不同物理设备使用不同 ID。
3. 选择所需 Windows PC 的编码器并确认 agent Online。
4. 保存后重复操作。

独立的编码器状态

每个编码器拥有自己的实时状态，一个在线 agent 不会使另一台上线。

GreatLocks 清单无法加载

你会看到： 楼栋、楼层或房间清单为空。

原因： 隧道离线或清单来源不可达。

解决方法：

1. 前往 Settings → Room Access → Keycard Encoding。
2. 确认 GreatLocks 服务器记录已保存。
3. 有多个 GreatLocks 编码器时，选择与该清单关联的编码器。
4. 检查其 agent 隧道是否连接正常。
5. 再次点击 Test Connection。
6. 连接恢复后刷新页面。

需要 LockSDK service URL

你会看到： 保存被阻止或显示 "Service URL is required."。

解决方法：

1. 前往 Settings → Room Access → Keycard Encoding。
2. 选择 LockSDK。
3. 打开 Physical Encoder Devices 并编辑编码器。
4. 输入有效 Service URL，如 http://127.0.0.1:8092。
5. 点击 Save，然后运行 Test Connection。

LockSDK agent 未注册

你会看到： 卡片显示 Not registered。

解决方法：

1. 确认 LockSDK 编码器存在于 Physical Encoder Devices。
2. 前往 Windows Agent，找到该编码器卡片。
3. 新卡片点击 Download Windows Agent，已有卡片点击 Reinstall。
4. 解压安装包，并在连接的 Windows PC 上运行 .bat 文件。
5. 刷新状态，确认从 Not registered 变为 Connected 或 Not connected。
6. 仅用 Advanced options 执行 View Logs、Rotate Secret 或 Delete。Rotate Secret 会先打开确认对话框，然后 AVA 才会断开当前 agent。

保存后 Heartbeat Monitor 关闭

你会看到： 启用并保存 Heartbeat Monitor 后又关闭。

解决方法：

1. 前往 Settings → Room Access → Keycard Encoding。
2. 打开 Encoding Options → Advanced options。
3. 开启 Heartbeat Monitor。
4. 只点击一次 Save，并等待成功消息。
5. 刷新页面，确认 Heartbeat Monitor 仍处于开启状态。
6. 仍关闭时参阅 Settings Not Saving After Switching Hotels。

Heartbeat 故障

你会看到： Heartbeat Monitor 显示 unreachable。

解决方法：

1. 确认 agent 在 kiosk/PC 运行。
2. 在 Registered Agents 查看在线状态和隧道。
3. 查看日志，必要时重新安装。

状态含义

Online 表示 AVA 已验证编码器和隧道。 Offline 表示 AVA 已验证编码器不可用。 Unknown 表示 AVA 无法验证编码器状态。 Unknown 不自动表示编码器离线。

编码器状态显示 unknown

你会看到： Heartbeat Monitor 显示 unknown，但会话和隧道正常。

原因： 可选供应商诊断或 Saflok Ambiance 凭据可能不可用。

解决方法：

1. 检查 Registered Agents，确认 agent 已连接。
2. 确认 Last Seen 较新且隧道可达。
3. 不要仅因 unknown 重启或重装 agent。
4. 需要确认编码器仍可用时，测试一张房卡。
5. 状态错误持续或编码失败时联系支持。

Heartbeat 状态或隧道错误

你会看到： Heartbeat 报告状态错误或隧道失败。

解决方法：

1. 阅读完整消息，并记下它指向编码器状态还是隧道。
2. 对于状态错误，检查供应商诊断并记录确切消息。
3. 对于隧道失败，确认 agent 正在运行且 Last Seen 较新。
4. 刷新 Settings → Room Access，然后再次检查状态。
5. 错误仍存在或房卡编码失败时联系支持。

Google Chat 编码器提醒

你会看到： Google Chat 发送编码器提醒，其中包含清晰的标题和员工操作建议。

含义： 提醒会说明房卡现在是否可用，或编码器是否仍不可用。配置了编码器显示名称时，提醒会使用该名称。时间采用酒店本地时区。

解决方法：

1. 如果只是短暂问题，除非有房卡失败，否则照常制作房卡。
2. 如果有房卡失败，检查编码器电源及其连接电脑的线缆。
3. 在编码器电脑上重启 Encoder Agent 应用。
4. 如果应用未恢复，重启电脑。
5. 编码器仍停机时，尽可能在前台发卡。
6. 如果没有其他发卡方式，立即联系 Vouch 支持。

提醒类型

Keycard encoder had brief problems 表示编码器出现短暂问题后已恢复，现在可以使用。 Keycard encoder not working 表示住客可能无法在 kiosk 获取房卡。 Keycards working again 表示编码器已恢复，无需采取操作。

提醒会在斜体 For Vouch support 页脚中保留技术详情。联系支持时请一并提供该页脚。

实时编码器状态不一致

你会看到： 编码器已配置，但预订弹窗仍标记不可用。

原因： AVA 验证 agent 和隧道后才显示 Online；Unknown 表示未验证。该状态驱动动态选择，GreatLocks 状态只属于关联编码器。

解决方法：

1. 检查 Registered Agents 卡片。
2. 确认设备连接且隧道可达。
3. 先修复 agent 或网络问题。
4. 刷新 Settings → Room Access，重试编码并检查 Status:。

Windows Agent 太旧，无法读取房卡

你会看到： Read Keycard 失败，并显示 "This Windows Agent is too old to read keycards. Update the Universal Encoder Agent, then try again."

原因： 旧版 agent 不公开 Saflok read API，AVA 会访问默认网页。

解决方法：

1. 前往 Settings → Room Access → Keycard Encoding。
2. Windows Agent 显示 outdated 时，在 Reinstall 前先点击 Update。
3. 等待 agent 重新连接。
4. 再次尝试 Read Keycard。

编码器隧道离线

你会看到： Read Keycard 显示 "The encoder tunnel is offline. Start the Universal Encoder Agent, then try again."

原因： 编码器电脑无法通过隧道连接 AVA。

解决方法：

1. 前往 Settings → Room Access → Keycard Encoding。
2. 找到 Saflok Windows Agent 卡片。
3. 在编码器电脑上启动 Universal Encoder Agent。
4. 等待 agent 显示 Connected，且 Last Seen 时间较新。
5. 再次尝试 Read Keycard。
6. agent 仍离线时，参阅 Windows Agent 未连接。

Windows Agent 未连接

你会看到： Not connected 或 "Never online."

解决方法：

1. 打开下载的 zip，并运行 download-installer.bat。
2. 等待它下载安装程序 .exe，然后运行该文件。
3. 确认 Windows PC 可以访问互联网。
4. 必要时在 Windows Agent 的 agent 卡片上点击 Reinstall。
5. Be-Tech 配置还要确认本地 adapter 服务正在运行。重启后，Be-Tech 状态最多可能需要 5 分钟刷新。
6. 刷新 Registered Agents 状态。
7. 返回 Settings → Room Access，确认 Status: 变为 online。

动态编码器列表

agent 连接且隧道可达时列表应显示 Online。嵌套卡片仍离线时刷新并先检查 agent。

Windows Agent 服务操作需要权限

你会看到： 点击 Start、Stop 或 Restart 时要求管理员权限。

原因： 托盘按钮需要提升权限控制 Windows 服务。

解决方法：

1. 在 UAC 提示点击 Yes。
2. 非管理员请让管理员批准。
3. 取消后再次尝试。

待处理的编码器设置同步

你会看到： agent 已连接，但 AVA 显示 Pending encoder setup sync。

原因： 已保存的编码器或 kiosk 分配与 agent 已应用的设置不同。在线连接不会自动应用分配变更。

解决方法：

1. 在 AVA 中打开 agent 卡片。

2. 点击 Sync Encoder Setup。

3. 如有需要，使用 Advanced options → Registered Agents。

4. 确认 agent 在线，并支持远程设置同步。

5. 同步后刷新 agent 状态。

   ✓ agent 报告已保存的分配后，待处理状态会清除。

Adem 分配会在点击 Save 后尝试同步。其他受支持的供应商需要手动同步。如果保存成功但同步失败，分配仍会保存；同步失败不会自动排队。

如果没有 Sync Encoder Setup，请更新 UEA 或使用 Reinstall。对于兼容的 agent，不要仅因为分配发生变化就重新安装。

Kiosk 路由规则不显示

你会看到： 找不到路由规则。

解决方法：

1. 前往 Settings → Kiosk。
2. 打开 Device Routing。
3. 关闭 Enable guest selection，以显示手动路由规则。
4. 在 Physical Encoder Devices 中至少添加一台设备。

Adem 设置无法保存

你会看到： 点击 Save 时，AVA 拒绝 Adem 配置。

解决方法：

1. 在 Settings → Room Access → Keycard Encoding 下选择 Adem。

2. 填写 Adem 配置中显示的所有必填字段。

3. 添加至少一个具有唯一 Encoder ID 的编码器。

4. 填写 AVA 显示的所有必填编码器条目字段。

5. 为每个串行读卡器使用实际的 Windows COM 编号。

6. 在直连模式下，AVA 标记为必填时输入服务 URL。

7. 运行 Test Connection 前先点击 Save。

   ✓ AVA 使用已保存的配置进行测试。 ✓ 更改供应商配置会清除之前的测试结果。

Adem 连接测试失败

你会看到： Test Connection 失败，或 Adem agent 保持离线。

解决方法：

1. 确认编码器电脑上已安装 Windows Agent。
2. 确认 Adem SQL Server 名称和 Log User 正确。
3. 检查 Adem 读卡器驱动和实体编码器是否已连接。
4. 确认 agent 软件包包含提供的 Adem DLL 文件。
5. 在 Settings → Room Access → Windows Agent 下检查 agent 状态。
6. 再次测试前，先保存任何已更改的 Adem 设置。
7. 刷新页面，然后再次运行 Test Connection。

健康状态限制

agent 健康检查会确认 DLL 可以加载。 Test Connection 还会检查 Adem 会话和 SQL 配置。

解读 Adem 读卡诊断

你会看到： 只读辅助工具返回 no_card、port_open_error 或其他结果。

解决方法：

1. 在 32-bit Windows PowerShell 中运行辅助工具。
2. 仅使用已确认的端口和酒店实际的 Adem SQL 设置。
3. 运行 -Read 前确认所选读卡器处于空闲状态。
4. 使用 -EncoderIdle 运行探测，并查看 JSON 结果。
5. 如果暂停了 UEA，请恢复 UEA，然后确认其隧道正常。

结果	应采取的措施
card_read	视所选读卡器为能够读取该卡。继续进行受控的卡片和门锁验收。
no_card	探测期间不要放置卡片。将其视为读卡器响应，而不是成功的卡片回读。
port_open_error	检查 COM 编号、读卡器连接和竞争中的应用。不要据此判定编码器故障。
communication_error	检查读卡器电源、驱动、线缆和所选端口。仅在读卡器空闲后重试。
SQL 或会话失败	检查 SQL Server、软件、版本和 SQL.ini 位置。实体连接仍未得到确认。
存在 CleanupError	恢复读卡器和 UEA 状态。重复探测前联系支持。

辅助工具会按顺序读取所选端口，不会自动重试。它不会编码、擦除、扫描所有端口，也不会共享 UEA 的操作锁。正在运行的进程不能证明读卡器当前由其占用。

保护测试窗口

不要同时运行 AVA 编码、供应商读卡器操作或其他探测。请使用专用控制台，因为原生 SDK 调用可能会阻塞。

Adem SQL 设置缺失

你会看到： 诊断无法启动会话，但 Adem 应用可以正常工作。

解决方法：

1. 向门锁系统管理员询问当前 SQL Server。
2. 检查 Lock.exe 旁边供应商应用的 SQL.ini。
3. 如果文件缺失，检查已登录用户的 Windows VirtualStore 路径。
4. 在辅助工具中使用相同的软件、版本和服务器值。
5. 不要将 SQL 凭据复制到报告或源代码管理中。

VirtualStore 路径

旧版 Adem 安装可能会将 SQL.ini 存储在 %LOCALAPPDATA%\VirtualStore 下。因此，不同的 Windows 用户可能看到不同的 SQL 设置。

Adem 共享 agent 端口错误

你会看到： AVA 提示共享 Adem 编码器需要不同的 COM 端口，或 agent 无法注册所选编码器。

解决方法：

1. 确认每个编码器实际使用的 Windows COM 编号。
2. 为每个串行编码器设置不同且大于 0 的 Port。
3. 不要在同一个共享 agent 上配置多个原生 USB 读卡器。
4. 如果条目共用一个静态 agent URL，也确认端口彼此不同。
5. 确认所选 agent 和 kiosk 分配与 AVA 中显示的路由一致。
6. 再次保存编码器记录。
7. 一次测试一个 kiosk 或编码器。

每个原生 USB 读卡器使用一个 agent。 USB 转串行读卡器必须使用分配给它的 COM 编号。 不同的编码器电脑可以重复使用同一个 COM 编号。

仍然卡住？

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

• ❌ 检查电源和网络后编码器仍离线
• ❌ Be-Tech 客户端持续停止
• ❌ 多个 kiosk 编码失败
• ❌ Heartbeat 超过 30 分钟不健康

建议附上：

• 编码器类型和型号
• 精确的 Be-Tech 错误消息
• 是否使用 Windows Agent 或直接 Base URL
• Registered Agents 和 Heartbeat Monitor 截图
• 问题开始时间

相关指南

• 房卡编码器概览
• 设置房卡编码器
• 房卡客人说明