クイックスタート
このページでは、ホテルの HMS 管理パネルで API キーを発行し、滞在中のゲスト一覧を取得します。API キーの管理権限を持つユーザーで管理パネルにアクセスできる必要があります。アクセスできない場合は、ホテルの管理者にキーを発行して共有してもらってください。
1. キーを発行する#
- HMS の管理パネルで API ページを開き、カスタム 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 配列の中でそれぞれ個別のレコードになります。以下は同室のゲスト2名の例（抜粋）です。
{
"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のままです。
次に読むページ#
- ゲスト認証フロー — 照合ルール、セッションの有効期間、定期同期
- 認証 — キーの管理と 401 レスポンス
- API リファレンス — 全フィールドの説明