快速入门
本页将引导您在酒店的 HMS 后台生成 API 密钥，并获取在住客人名单。您需要一个有权管理 API 密钥的后台用户；如果没有，可以由酒店管理方生成密钥后提供给您。
1. 生成密钥#
- 在 HMS 管理后台打开 API 页面，切换到自定义 API（Custom API）选项卡。
- 在描述字段中填写密钥的用途（例如 Hotspot – 主楼）并保存。HMS 会生成一个 13 位字符的密钥。
- 从列表中复制密钥。它绑定该酒店且不会过期；一旦从列表中删除，即刻失效。
export HMS_API_KEY="017f1daf2d139"同时记下酒店在 HMS 中的 ID；示例中以 HotelCode: 1000 发送。该请求头不参与验证，但可以在日志中显示查询的是哪家酒店。
2. 获取名单#
该端点使用 POST 调用，不需要请求体：
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. 解读响应#
每位在住客人都是 otelde 数组中的一条独立记录。以下为两位同住一间房的客人的节选示例：
{
"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对每位客人唯一，请将热点用户与其关联。同住一间房的客人共享rezervasyon_id。- 认证门户上填写的房间号与
roomName比对，姓氏与lastName比对。这些值通常为大写。 checkin是入住时刻；checkout是计划退房日期（00:00 UTC），不含具体时刻。加上酒店的退房时间即可得出会话结束时间。- 如果没有在住客人，
otelde为空数组，success仍为1。