Phản hồi lỗi
Hotspot API cho ra hai loại kết quả: xác thực thất bại (HTTP 401) và phản hồi thành công (HTTP 200). Danh sách khách rỗng không phải là lỗi. Dưới đây là các tình huống bạn có thể gặp và cách xử lý từng tình huống.
Mã trạng thái HTTP#
| Mã | Nội dung | Ý nghĩa và cách xử lý |
|---|---|---|
200 | {"success": 1, "otelde": [...]} | Thành công. Xử lý danh sách. |
200 | {"success": 1, "otelde": []} | Thành công; không có khách nào đang lưu trú. Xem ghi chú về danh sách rỗng bên dưới. |
401 | {"success": 0} | Thiếu header ApiKey hoặc khóa không được nhận diện. Không thử lại; hãy kiểm tra khóa và báo cho quản trị viên. |
404 | Trang lỗi | Sai đường dẫn. Hãy kiểm tra đường dẫn chính xác là /public/json/customer/inhotel. |
405 | Trang lỗi | Đã dùng phương thức khác POST (ví dụ GET từ trình duyệt). |
5xx / hết thời gian chờ | — | Lỗi tạm thời của máy chủ hoặc mạng. Thử lại với độ trễ tăng dần (30 giây, 1 phút, 5 phút) và trong thời gian đó tiếp tục dùng danh sách thành công gần nhất. |
Danh sách rỗng#
otelde: [] nghĩa là không có khách đã nhận phòng nào đang lưu trú, điều này bình thường với khách sạn nhỏ vào mùa thấp điểm. Tuy nhiên, một danh sách vừa đầy ở lần truy vấn trước mà đột nhiên rỗng thường cho thấy thao tác sai ở phía khách sạn (trả phòng hàng loạt nhầm, thay đổi trạng thái đặt phòng). Trước khi đóng mọi tài khoản Wi-Fi, hãy xác nhận danh sách trả về rỗng ở hai lần truy vấn liên tiếp.
Thử lại và hết thời gian chờ#
- Dùng thời gian chờ yêu cầu 10 giây; ngay cả với khách sạn lớn, danh sách cũng được trả về trong khoảng thời gian đó.
- Thử lại khi gặp
5xxvà lỗi mạng; không thử lại với401,404hoặc405, vì đó là lỗi cấu hình. - Giữ lại danh sách thành công gần nhất khi truy vấn thất bại. Chỉ đóng tài khoản của những khách đã biến mất khỏi danh sách trong một phản hồi thành công.
- Đếm số lần thất bại liên tiếp và thông báo cho quản trị viên khi vượt ngưỡng (ví dụ 15 phút).
Tình huống thường gặp#
| Tình huống | Nguyên nhân có thể | Cách xử lý |
|---|---|---|
| Khách không có trong danh sách | Lễ tân chưa làm thủ tục nhận phòng cho khách, đặt phòng đã bị hủy, khách không được đánh dấu “đang lưu trú”, hoặc khách đã trả phòng. | Hiển thị “số phòng và họ không khớp” trên trang đăng nhập và hướng dẫn khách đến lễ tân. Không cần lấy lại danh sách; khách sẽ xuất hiện ở lần đồng bộ tiếp theo. |
| Nhiều bản ghi cho cùng một phòng | Có nhiều hơn một khách ở trong phòng; mỗi khách là một bản ghi riêng. | Bình thường. Mở tài khoản theo từng khách (unique). |
identityNumber trống | Khách được đăng ký mà không có thông tin giấy tờ tùy thân. | Chuyển sang đối chiếu bằng họ + ngày sinh; để trống trường này trong bản ghi theo Luật 5651 và gắn bản ghi với unique. |
roomName không khớp | Khách nhập “0104” hoặc “Phòng 104” thay vì “104”; giá trị này là chuỗi. | Chuẩn hóa cả hai phía trước khi so sánh; không chuyển sang số. |
checkout đã qua nhưng khách vẫn có trong danh sách | Khách đã gia hạn lưu trú hoặc trả phòng muộn và lễ tân chưa xử lý. | Giữ quyền truy cập khi khách vẫn còn trong danh sách; cập nhật thời điểm kết thúc phiên khi checkout thay đổi. |