البدء السريع

ستنشئ في هذه الصفحة مفتاح API في لوحة تحكم HMS الخاصة بالفندق، ثم تجلب قائمة النزلاء المقيمين. تحتاج إلى الدخول إلى اللوحة بحساب مستخدم مسموح له بإدارة مفاتيح 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 فريد لكل نزيل، فاربط به مستخدم hotspot. أما rezervasyon_id فيتشاركه النزلاء في الغرفة نفسها.
• يُقارَن رقم الغرفة المطلوب في البوابة مع roomName، واسم العائلة مع lastName. وتكون القيم عادةً بأحرف كبيرة.
• checkin هو لحظة تسجيل الوصول؛ أما checkout فهو تاريخ المغادرة المخطط (00:00 UTC) دون وقت من اليوم. أضف موعد المغادرة في الفندق للحصول على نهاية الجلسة.
• إذا لم يكن هناك نزلاء مقيمون، تكون otelde مصفوفة فارغة وتبقى قيمة success هي 1.

ماذا بعد؟#

• مسار التحقق من النزلاء — قواعد المطابقة، ومدة الجلسة، والمزامنة الدورية
• المصادقة — إدارة المفاتيح والاستجابة 401
• مرجع API — شرح لكل الحقول