شروع سریع

در این صفحه در پنل HMS هتل یک کلید API می‌سازید و فهرست مهمانان مقیم را دریافت می‌کنید. به دسترسی پنل با کاربری نیاز دارید که اجازه مدیریت کلیدهای API را داشته باشد؛ در غیر این صورت مدیریت هتل می‌تواند کلید را بسازد و در اختیار شما بگذارد.

1. ساخت کلید#

• در پنل مدیریت HMS صفحه API را باز کنید و به زبانه Custom API بروید.
• در فیلد توضیحات بنویسید کلید کجا استفاده می‌شود (مثلاً Hotspot – ساختمان اصلی) و ذخیره کنید. HMS یک کلید 13 نویسه‌ای می‌سازد.
• کلید را از فهرست کپی کنید. این کلید به هتل وابسته است و منقضی نمی‌شود؛ به محض حذف از فهرست، نامعتبر می‌شود.

export HMS_API_KEY="017f1daf2d139"

شناسه هتل در HMS را هم یادداشت کنید؛ نمونه‌ها آن را به‌صورت 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 است.

ادامه مسیر#

• جریان تأیید مهمان — قواعد تطبیق، مدت نشست، همگام‌سازی دوره‌ای
• احراز هویت — مدیریت کلید و پاسخ 401
• مرجع API — توضیح همه فیلدها