Guida rapida

In questa pagina genererai una chiave API nel pannello HMS dell’hotel e recupererai l’elenco degli ospiti in hotel. Ti serve l’accesso al pannello con un utente autorizzato a gestire le chiavi API; in alternativa, la direzione dell’hotel può generare la chiave e fornirtela.

1. Genera una chiave#

• Nel pannello di amministrazione di HMS apri la pagina API e passa alla scheda Custom API.
• Nel campo della descrizione indica dove verrà usata la chiave (ad es. Hotspot – Edificio principale) e salva. HMS genera una chiave di 13 caratteri.
• Copia la chiave dall’elenco. È legata all’hotel e non scade; diventa non valida nel momento in cui viene eliminata dall’elenco.

export HMS_API_KEY="017f1daf2d139"

Annota anche l’ID HMS dell’hotel; gli esempi lo inviano come HotelCode: 1000. L’header non viene usato per la validazione, ma nei log mostra quale hotel è stato interrogato.

2. Recupera l’elenco#

L’endpoint si chiama con POST e non accetta alcun corpo:

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. Leggi la risposta#

Ogni ospite in hotel è un record separato nell’array otelde. Un esempio troncato con due ospiti nella stessa camera:

{
    "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 è univoco per ogni ospite: associa a questo valore l’utente hotspot. rezervasyon_id è condiviso dagli ospiti della stessa camera.
• Il numero di camera richiesto nel portale si confronta con roomName, il cognome con lastName. I valori sono di solito in maiuscolo.
• checkin è il momento del check-in; checkout è la data di check-out prevista (00:00 UTC), senza orario. Aggiungi l’orario di check-out dell’hotel per ottenere la fine della sessione.
• Se non ci sono ospiti in hotel, otelde è un array vuoto e success vale comunque 1.

Per proseguire#

• Flusso di verifica degli ospiti — regole di corrispondenza, durata della sessione, sincronizzazione periodica
• Autenticazione — gestione delle chiavi e risposta 401
• Riferimento API — tutti i campi spiegati