Démarrage rapide

Sur cette page, vous allez générer une clé API dans le panneau HMS de l’hôtel, puis récupérer la liste des clients en séjour. Il vous faut un accès au panneau avec un utilisateur autorisé à gérer les clés API ; à défaut, la direction de l’hôtel peut générer la clé et vous la transmettre.

1. Générer une clé#

• Dans le panneau d’administration HMS, ouvrez la page API et passez à l’onglet Custom API.
• Indiquez dans le champ de description l’usage prévu de la clé (p. ex. Hotspot – Bâtiment principal) et enregistrez. HMS génère une clé de 13 caractères.
• Copiez la clé depuis la liste. Elle est liée à l’hôtel et n’expire pas ; elle devient invalide dès qu’elle est supprimée de la liste.

export HMS_API_KEY="017f1daf2d139"

Notez aussi l’identifiant HMS de l’hôtel ; les exemples l’envoient sous la forme HotelCode: 1000. Cet en-tête ne sert pas à la validation, mais il indique dans les journaux quel hôtel a été interrogé.

2. Récupérer la liste#

L’endpoint s’appelle en POST et n’attend aucun corps :

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. Lire la réponse#

Chaque client en séjour est un enregistrement distinct du tableau otelde. Voici un extrait pour deux clients partageant une chambre :

{
    "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 est propre à chaque client ; rattachez-y l’utilisateur hotspot. rezervasyon_id est commun aux clients d’une même chambre.
• Le numéro de chambre demandé sur le portail est comparé à roomName, le nom de famille à lastName. Les valeurs sont généralement en majuscules.
• checkin est l’heure d’arrivée ; checkout est la date de départ prévue (00:00 UTC), sans heure. Ajoutez l’heure de départ de l’hôtel pour obtenir la fin de session.
• Si aucun client n’est en séjour, otelde est un tableau vide et success vaut toujours 1.

Et ensuite#

• Flux de vérification des clients — règles de correspondance, durée de session, synchronisation périodique
• Authentification — gestion des clés et réponse 401
• Référence API — explication de chaque champ