Flusso di verifica degli ospiti

Questa guida spiega come usare l’elenco degli ospiti in hotel in un captive portal: come confrontare con l’elenco i dati digitati dall’ospite, quando deve terminare la sessione Wi-Fi, con quale frequenza aggiornare l’elenco e quali campi conservare per i log previsti dalla legge turca n. 5651.

Cosa chiedere nel portale#

Poiché l’elenco fornisce insieme i dati della camera e dell’identità, il form più comune è numero di camera + cognome. Il solo numero di camera non basta: chiunque conosca il numero di una camera vicina potrebbe accedere. Le alternative sono numero di camera + numero di documento/passaporto oppure cognome + data di nascita; tieni quest’ultima come soluzione di riserva per gli ospiti senza numero di documento.

Regole di corrispondenza#

Prima di confrontare ciò che l’ospite ha digitato con i valori dell’elenco, normalizza entrambi i lati:

• Numero di camera: rimuovi gli spazi iniziali e finali e converti in maiuscolo. roomName è una stringa (può essere "104", "A-12" o "Villa 3"): non convertirla in numero e non eliminare gli zeri iniziali.
• Cognome: converti in maiuscolo (attenzione alla conversione turca i → İ) e riduci gli spazi ripetuti a uno solo. I valori dell’elenco sono di solito letti in maiuscolo dal documento d’identità.
• Numero di documento: rimuovi gli spazi e converti in maiuscolo. Il numero di identità nazionale turco ha 11 cifre; un numero di passaporto combina lettere e cifre.
• Data di nascita: l’elenco usa DD.MM.YYYY; converti il valore se il tuo form raccoglie un formato diverso.

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) {
  // "Numero di camera e cognome non corrispondono" — conta i tentativi falliti e limita dopo 5
}

Il valore unique del record corrispondente è l’identità dell’utente hotspot. Quando lo stesso ospite accede da un secondo dispositivo, riusa l’account legato a questo valore invece di crearne uno nuovo e applica il limite di dispositivi a quell’account.

Durata della sessione#

checkout è la data di check-out prevista e punta alle 00:00 (UTC) di quel giorno; non contiene l’orario. Se apri la sessione fino a quel momento, l’ospite perde l’accesso la mattina della partenza. Calcola la fine della sessione aggiungendo alla data l’orario di check-out dell’hotel:

const CHECKOUT_TIME = "12:00";                       // orario di check-out dell’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`);

Se l’ospite parte prima dell’orario di check-out, esce dall’elenco: chiudi l’account alla sincronizzazione successiva. Se il soggiorno viene prolungato, checkout cambia: confronta questo campo durante la sincronizzazione e aggiorna la fine della sessione. In caso di late check-out è più sicuro mantenere l’accesso aperto finché l’ospite resta nell’elenco.

Sincronizzazione periodica#

L’elenco è un’istantanea: non esistono notifiche di modifica (webhook). Recupera l’elenco a intervalli fissi e confrontalo con il precedente in base a unique:

• Intervallo: 5 minuti bastano per la maggior parte degli hotel. Se gli ospiti devono potersi connettere subito dopo il check-in puoi scendere a 1–2 minuti; non andare sotto 1 minuto.
• Nuovo unique: prepara l’account; la corrispondenza con l’ospite avviene al primo accesso al portale.
• unique mancante: l’ospite ha effettuato il check-out o la prenotazione è stata cancellata. Termina la sessione e chiudi l’account.
• Stesso unique, roomName o checkout diversi: cambio di camera o prolungamento del soggiorno. Aggiorna l’account.
• Richiesta non riuscita: in caso di timeout, 401 o 5xx, conserva l’ultimo elenco ricevuto correttamente; non chiudere mai gli account in base a una risposta di errore.

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: mantieni il vecchio elenco
  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);                // check-out effettuato
  }
  for (const [id, g] of next) {
    const old = prev.get(id);
    if (!old) await openAccount(g);                           // nuovo ospite
    else if (old.checkout !== g.checkout || old.roomName !== g.roomName) await updateAccount(g);
  }
  return next;
}

Più ospiti nella stessa camera#

Ogni ospite di una camera è un record separato: rezervasyon_id è condiviso, unique è diverso. Apri gli account per ospite anziché per camera, così che ogni ospite abbia i propri dispositivi, la propria sessione e il proprio record per la legge 5651. Una ricerca per numero di camera + cognome può restituire più record per ospiti con lo stesso cognome (una famiglia): invece di prendere la prima corrispondenza, distinguili per nome o data di nascita, oppure apri per loro un account condiviso.

Log per la legge turca n. 5651#

L’obbligo di conservare i log di accesso ai sensi della legge turca n. 5651 spetta al sistema hotspot; HMS fornisce solo i dati identificativi. All’apertura di una sessione, salva i seguenti campi insieme all’indirizzo MAC/IP e al timestamp: unique, rezervasyon_id, firstName, lastName, identityNumber, birthDate, roomName, checkin, checkout. Quando un ospite esce dall’elenco, HMS non fornisce più queste informazioni: conserva il record dal tuo lato.