Alur verifikasi tamu

Panduan ini menjelaskan cara menggunakan daftar tamu yang sedang menginap di captive portal: mencocokkan input tamu dengan daftar, kapan sesi Wi-Fi harus berakhir, seberapa sering daftar perlu diperbarui, dan field mana yang perlu disimpan untuk catatan sesuai Undang-Undang Turki No. 5651.

Yang perlu diminta di portal#

Karena daftar menyediakan detail kamar dan identitas sekaligus, form yang paling umum adalah nomor kamar + nama belakang. Nomor kamar saja tidak cukup; siapa pun yang mengetahui nomor kamar sebelah bisa login. Alternatifnya adalah nomor kamar + nomor identitas/paspor atau nama belakang + tanggal lahir; gunakan yang terakhir sebagai cadangan untuk tamu yang nomor identitasnya kosong.

Aturan pencocokan#

Normalisasikan kedua sisi sebelum membandingkan input tamu dengan nilai di daftar:

• Nomor kamar: hapus spasi di awal dan akhir, lalu ubah ke huruf kapital. roomName berupa string (bisa "104", "A-12", atau "Villa 3"); jangan mengonversinya menjadi angka atau menghapus nol di depan.
• Nama belakang: ubah ke huruf kapital (perhatikan pemetaan bahasa Turki i → İ) dan gabungkan spasi berulang. Nilai di daftar biasanya dibaca dari dokumen identitas dalam huruf kapital.
• Nomor identitas: hapus spasi dan ubah ke huruf kapital. Nomor identitas nasional Turki terdiri dari 11 digit; nomor paspor merupakan campuran huruf dan angka.
• Tanggal lahir: daftar memberikan format DD.MM.YYYY; konversikan jika form Anda menggunakan format lain.

const norm = (s) => String(s ?? "")
  .replace(/\s+/g, " ")
  .trim()
  .toLocaleUpperCase("tr-TR");

function findGuest(list, room, lastName) {
  return list.find((g) =>
    norm(g.roomName) === norm(room) && norm(g.lastName) === norm(lastName)
  ) || null;
}

const guest = findGuest(data.otelde, form.room, form.lastName);
if (!guest) {
  // "Nomor kamar dan nama belakang tidak cocok" — hitung percobaan gagal, batasi setelah 5 kali
}

Nilai unique dari record yang cocok adalah identitas pengguna hotspot. Saat tamu yang sama login dari perangkat kedua, gunakan kembali akun yang terikat dengan nilai ini alih-alih membuat akun baru, dan terapkan batas perangkat pada akun tersebut.

Masa berlaku sesi#

checkout adalah tanggal check-out yang direncanakan dan menunjuk ke pukul 00:00 (UTC) pada hari tersebut; nilainya tidak memuat jam. Jika Anda membuka sesi hingga saat itu, tamu akan kehilangan akses pada pagi hari keberangkatan. Hitung akhir sesi dengan menambahkan jam check-out hotel ke tanggal tersebut:

const CHECKOUT_TIME = "12:00";                       // jam check-out hotel
const day = new Date(guest.checkout * 1000)
  .toLocaleDateString("en-CA", { timeZone: "UTC" });   // "2026-09-10"
const sessionEnd = new Date(`${day}T${CHECKOUT_TIME}:00+03:00`);

Jika tamu pergi sebelum jam check-out, tamu tersebut hilang dari daftar; tutup akunnya pada sinkronisasi berikutnya. Jika masa menginap diperpanjang, checkout berubah; bandingkan field ini saat sinkronisasi dan perbarui akhir sesi. Untuk check-out terlambat, lebih aman membiarkan akses tetap terbuka selama tamu masih ada di daftar.

Sinkronisasi berkala#

Daftar ini merupakan snapshot; tidak ada notifikasi perubahan (webhook). Ambil daftar pada interval tetap dan bandingkan dengan daftar sebelumnya berdasarkan unique:

• Interval: 5 menit sudah cukup untuk sebagian besar hotel. Jika tamu diharapkan bisa langsung online saat check-in, Anda dapat menurunkannya hingga 1–2 menit; jangan kurang dari 1 menit.
• unique baru: siapkan akun; tamu dicocokkan saat login pertama di portal.
• unique hilang: tamu sudah check-out atau reservasi dibatalkan. Akhiri sesi dan tutup akunnya.
• unique sama, roomName atau checkout berbeda: pindah kamar atau perpanjangan. Perbarui akunnya.
• Permintaan gagal: saat terjadi timeout, 401, atau 5xx, pertahankan daftar terakhir yang berhasil; jangan pernah menutup akun berdasarkan respons error.

async function sync(prev) {
  const res = await fetch(BASE + "/public/json/customer/inhotel", {
    method: "POST",
    headers: { "ApiKey": process.env.HMS_API_KEY, "HotelCode": HOTEL_CODE }
  });
  if (!res.ok) return prev;                                   // 401 / 5xx: pertahankan daftar lama
  const { success, otelde } = await res.json();
  if (success !== 1) return prev;

  const next = new Map(otelde.map((g) => [g.unique, g]));
  for (const [id] of prev) {
    if (!next.has(id)) await closeAccount(id);                // sudah check-out
  }
  for (const [id, g] of next) {
    const old = prev.get(id);
    if (!old) await openAccount(g);                           // tamu baru
    else if (old.checkout !== g.checkout || old.roomName !== g.roomName) await updateAccount(g);
  }
  return next;
}

Beberapa tamu dalam satu kamar#

Setiap tamu dalam satu kamar merupakan record terpisah: rezervasyon_id sama, unique berbeda. Buka akun per tamu, bukan per kamar, agar setiap tamu memiliki perangkat, sesi, dan catatan UU No. 5651 masing-masing. Kueri nomor kamar + nama belakang dapat mengembalikan lebih dari satu record untuk tamu dengan nama belakang yang sama (satu keluarga); alih-alih mengambil kecocokan pertama, bedakan berdasarkan nama depan atau tanggal lahir, atau buka akun bersama untuk mereka.

Catatan sesuai UU No. 5651#

Kewajiban menyimpan log akses berdasarkan Undang-Undang Turki No. 5651 ada pada sistem hotspot; HMS hanya menyediakan data identitas. Saat sesi dibuka, simpan field berikut bersama alamat MAC/IP dan timestamp: unique, rezervasyon_id, firstName, lastName, identityNumber, birthDate, roomName, checkin, checkout. Setelah tamu hilang dari daftar, HMS tidak lagi menyediakan informasi ini; simpan catatannya di sisi Anda.