错误响应
Hotspot API 只会产生两类结果：身份验证失败（HTTP 401）和成功响应（HTTP 200）。客人名单为空并不是错误。下面列出了您可能遇到的情况及相应的处理方法。
HTTP 状态码#
| 状态码 | 响应体 | 含义与处理方式 |
|---|---|---|
200 | {"success": 1, "otelde": [...]} | 成功。处理名单。 |
200 | {"success": 1, "otelde": []} | 成功；当前没有在住客人。参见下文关于空名单的说明。 |
401 | {"success": 0} | 缺少 ApiKey 请求头或密钥无法识别。不要重试；检查密钥并通知管理员。 |
404 | 错误页面 | 路径错误。请确认路径与 /public/json/customer/inhotel 完全一致。 |
405 | 错误页面 | 使用了 POST 以外的方法（例如从浏览器发起的 GET）。 |
5xx / 超时 | — | 服务器或网络临时错误。按递增的间隔重试（30 秒、1 分钟、5 分钟），期间继续使用上一次成功获取的名单。 |
空名单#
otelde: [] 表示当前没有已入住的在住客人，这对淡季的小型酒店来说很正常。但如果上一次查询时名单还有很多人，这次突然变空，通常意味着酒店一侧出现了操作失误（误操作批量退房、预订状态被更改）。在关闭所有 Wi-Fi 账户之前，请确认连续两次查询返回的都是空名单。
重试与超时#
- 请求超时设为 10 秒；即使是大型酒店，名单也会在此时间内返回。
- 遇到
5xx和网络错误时重试；401、404和405属于配置错误，不要重试。 - 查询失败期间，保留上一次成功获取的名单。只关闭在成功响应中已从名单消失的客人的账户。
- 统计连续失败的次数，超过阈值（例如 15 分钟）时通知管理员。
常见情况#
| 情况 | 可能原因 | 处理方式 |
|---|---|---|
| 客人不在名单中 | 前台尚未为客人办理入住、预订已取消、客人未被标记为“在住”，或客人已退房。 | 在认证门户上显示“房间号与姓氏不匹配”，并引导客人联系前台。无需重新拉取；客人会在下一次同步时出现。 |
| 同一房间有多条记录 | 该房间住有多位客人，每位客人各为一条独立记录。 | 属正常情况。按客人（unique）分别开通账户。 |
identityNumber 为空 | 登记客人时未录入证件信息。 | 改用姓氏 + 出生日期进行匹配；在第 5651 号法律日志中将该字段留空，并将记录与 unique 关联。 |
roomName 不匹配 | 客人输入的是“0104”或“Room 104”，而不是“104”；该值为字符串。 | 比较前先对双方进行规范化处理；不要转换为数字。 |
checkout 已过但客人仍在名单中 | 客人延长了住宿或延迟退房，而前台尚未处理。 | 只要客人仍在名单中，就保持访问权限；checkout 变化时更新会话结束时间。 |