Bắt đầu nhanh

Trên trang này, bạn sẽ tạo khóa API trong bảng quản trị HMS của khách sạn và lấy danh sách khách đang lưu trú. Bạn cần quyền truy cập bảng quản trị bằng một người dùng được phép quản lý khóa API; nếu không, ban quản lý khách sạn có thể tạo khóa và chuyển cho bạn.

1. Tạo khóa#

• Trong bảng quản trị HMS, mở trang API và chuyển sang thẻ Custom API.
• Nhập nơi sẽ dùng khóa vào trường mô tả (ví dụ Hotspot – Tòa nhà chính) rồi lưu. HMS tạo một khóa gồm 13 ký tự.
• Sao chép khóa từ danh sách. Khóa gắn với khách sạn và không hết hạn; khóa mất hiệu lực ngay khi bị xóa khỏi danh sách.

export HMS_API_KEY="017f1daf2d139"

Hãy ghi lại cả ID HMS của khách sạn; các ví dụ gửi giá trị này dưới dạng HotelCode: 1000. Header này không dùng để xác thực, nhưng giúp log cho thấy khách sạn nào đã được truy vấn.

2. Lấy danh sách#

Endpoint được gọi bằng POST và không nhận nội dung yêu cầu:

curl -X POST "https://test.hms.gen.tr/public/json/customer/inhotel" \
  -H "ApiKey: $HMS_API_KEY" \
  -H "HotelCode: 1000"

const res = await fetch("https://test.hms.gen.tr/public/json/customer/inhotel", {
  method: "POST",
  headers: {
    "ApiKey": process.env.HMS_API_KEY,
    "HotelCode": "1000"
  }
});
if (res.status === 401) throw new Error("Invalid ApiKey");
const data = await res.json();
for (const g of data.otelde) {
  console.log(g.roomName, g.firstName, g.lastName, new Date(g.checkout * 1000));
}

$ch = curl_init('https://test.hms.gen.tr/public/json/customer/inhotel');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => 'POST',
    CURLOPT_HTTPHEADER     => [
        'ApiKey: ' . getenv('HMS_API_KEY'),
        'HotelCode: 1000',
    ],
]);
$body = curl_exec($ch);
if (curl_getinfo($ch, CURLINFO_HTTP_CODE) === 401) {
    throw new RuntimeException('Invalid ApiKey');
}
$data = json_decode($body, true);
foreach ($data['otelde'] as $g) {
    echo $g['roomName'], ' · ', $g['firstName'], ' ', $g['lastName'], ' · ', date('d.m.Y', $g['checkout']), "\n";
}

3. Đọc phản hồi#

Mỗi khách đang lưu trú là một bản ghi riêng trong mảng otelde. Ví dụ rút gọn cho hai khách ở chung một phòng:

{
    "success": 1,
    "otelde": [
        {
            "unique": 58211,
            "firstName": "AYŞE",
            "lastName": "DEMİR",
            "identityNumber": "11111111110",
            "birthDate": "14.03.1985",
            "roomID": 4,
            "roomName": "104",
            "checkin": 1788863400,
            "checkout": 1788998400,
            "rezervasyon_id": 282799
        },
        {
            "unique": 58212,
            "firstName": "MEHMET",
            "lastName": "DEMİR",
            "identityNumber": "22222222220",
            "birthDate": "02.11.1982",
            "roomID": 4,
            "roomName": "104",
            "checkin": 1788863400,
            "checkout": 1788998400,
            "rezervasyon_id": 282799
        }
    ]
}

• unique là duy nhất cho mỗi khách; hãy gắn người dùng hotspot với giá trị này. rezervasyon_id được dùng chung bởi các khách ở cùng phòng.
• Số phòng được hỏi trên trang đăng nhập được so với roomName, họ được so với lastName. Các giá trị thường viết hoa.
• checkin là thời điểm nhận phòng; checkout là ngày trả phòng dự kiến (00:00 UTC), không có thông tin giờ. Cộng thêm giờ trả phòng của khách sạn để có thời điểm kết thúc phiên.
• Nếu không có khách nào đang lưu trú, otelde là một mảng rỗng và success vẫn là 1.

Tiếp theo#

• Luồng xác minh khách — quy tắc đối chiếu, thời hạn phiên, đồng bộ định kỳ
• Xác thực — quản lý khóa và phản hồi 401
• Tham chiếu API — giải thích từng trường