Xác thực

Quyền truy cập được cấp thông qua một tài khoản đối tác do HMS tạo. Tài khoản đối tác nhận một apiKey và apiSecret, và HMS ủy quyền những khách sạn mà tài khoản đó được phép truy cập. Endpoint đăng nhập đổi thông tin xác thực này lấy một token gắn với khách sạn.

Đăng nhập và token#

POST /external/public/login HTTP/1.1
Host: test.hms.gen.tr
Content-Type: application/x-www-form-urlencoded

apiKey=5y94tLmALIKDyUVdEPlAAjg5xWGQNgQtnALlV4%2BAm7Q%3D&apiSecret=a143d640…&hotelCode=1000

{
    "success": true,
    "hotelCode": "1000",
    "token": "eyJlbmREYXRlIjp7ImRhdGUiOiIyMDI2LTA5LTE1IDEwOjI0OjMxLjAwMDAwMCIs…",
    "hotelSeoUrl": "demo-otel"
}

Header Bearer#

Mọi endpoint, trừ đăng nhập, đều yêu cầu token trong header Authorization:

GET /external/currencies HTTP/1.1
Host: test.hms.gen.tr
Authorization: Bearer eyJlbmREYXRlIjp7ImRhdGUiOiIyMDI2LTA5LTE1IDEwOjI0OjMxLjAwMDAwMCIs…

Nếu header bị thiếu, sai định dạng (không có tiền tố Bearer) hoặc token không xác định, API trả về 401:

{
    "success": false,
    "error": "Authentication required"
}

Thời hạn và gia hạn token#

• Token có hiệu lực 7 ngày. Hãy gia hạn bằng cách đăng nhập lại trước khi token hết hạn; đăng nhập không tốn nhiều tài nguyên và có thể lặp lại cho cùng một khách sạn.
• Không phân tích nội dung token. Dù token là một cấu trúc mã hóa base64, định dạng của nó không được đảm bảo; hãy lưu và chuyển tiếp token như một chuỗi nguyên khối.
• Khi gặp 401, hãy đăng nhập lại một lần và thử lại yêu cầu; nếu vẫn nhận 401 lần thứ hai, nghĩa là cặp khóa hoặc quyền truy cập khách sạn đã thay đổi.

Ngữ cảnh khách sạn#

Mỗi token gắn với một khách sạn duy nhất. Tham số hotelID trên các endpoint phải trùng với khách sạn đó; yêu cầu dữ liệu của khách sạn khác sẽ gây lỗi ủy quyền hoặc trả về kết quả rỗng. Với tích hợp nhiều khách sạn, hãy lấy token riêng cho từng khách sạn và lưu bộ nhớ đệm theo từng khách sạn.

Lỗi đăng nhập#

Các lỗi này được trả về với HTTP 200, kèm success: false và token: null.