Autenticazione

L’accesso avviene tramite un account partner definito da HMS. Un account partner riceve una coppia apiKey e apiSecret, e HMS stabilisce a quali hotel può accedere. L’endpoint di login scambia queste credenziali con un token legato all’hotel.

Richiesta

POST /external/public/login HTTP/1.1
Host: test.hms.gen.tr
Content-Type: application/x-www-form-urlencoded

apiKey=5y94tLmALIKDyUVdEPlAAjg5xWGQNgQtnALlV4%2BAm7Q%3D&apiSecret=a143d640…&hotelCode=1000

Risposta · 200

{
    "success": true,
    "hotelCode": "1000",
    "token": "eyJlbmREYXRlIjp7ImRhdGUiOiIyMDI2LTA5LTE1IDEwOjI0OjMxLjAwMDAwMCIs…",
    "hotelSeoUrl": "demo-otel"
}

Campo	Descrizione
`apiKey`	Chiave partner. Contiene caratteri base64, quindi in un corpo form va codificata per URL (`+` → `%2B`, `=` → `%3D`). Le librerie HTTP lo fanno automaticamente.
`apiSecret`	Chiave segreta. Conservala solo lato server; non includerla mai in codice eseguito nel browser o in un’app mobile.
`hotelCode`	ID HMS dell’hotel. Se il partner non è autorizzato per l’hotel, viene restituito `hotel_permission_is_not_found`.
`hotelSeoUrl`	Slug SEO dell’hotel. Viene usato al posto di `hotelCode` solo dal motore di prenotazione di HMS; le integrazioni di terze parti inviano `hotelCode`.

Header Bearer#

Tutti gli endpoint, tranne il login, si aspettano il token nell’header Authorization:

Richiesta

GET /external/currencies HTTP/1.1
Host: test.hms.gen.tr
Authorization: Bearer eyJlbmREYXRlIjp7ImRhdGUiOiIyMDI2LTA5LTE1IDEwOjI0OjMxLjAwMDAwMCIs…

Se l’header manca o non è valido (senza prefisso Bearer) oppure il token è sconosciuto, l’API restituisce 401:

401 Unauthorized

{
    "success": false,
    "error": "Authentication required"
}

Durata e rinnovo del token#

Il token è valido 7 giorni. Rinnovalo ripetendo il login prima della scadenza: il login è un’operazione leggera e si può ripetere per lo stesso hotel.
Non analizzare il contenuto del token. Anche se è una struttura codificata in base64, il suo formato non è garantito: salvalo e inoltralo come stringa opaca.
In caso di 401, ripeti il login una volta e riprova la richiesta; un secondo 401 significa che la coppia di chiavi o l’autorizzazione per l’hotel è cambiata.

Contesto dell’hotel#

Un token è legato a un solo hotel. Il parametro hotelID degli endpoint deve corrispondere a quell’hotel; se richiedi un altro hotel ottieni un errore di autorizzazione o risultati vuoti. Per le integrazioni multi-hotel ottieni un token separato per ogni hotel e tienilo in cache per hotel.

message	Significato
`partner_is_not_found`	La coppia `apiKey` / `apiSecret` non corrisponde. Controlla le chiavi e la codifica URL.
`hotel_is_not_found`	Nessun hotel corrisponde a `hotelSeoUrl`.
`hotel_permission_is_not_found`	Il partner non è autorizzato per questo hotel oppure l’autorizzazione non è attiva. Contatta il supporto HMS.

Questi errori tornano come HTTP 200 con success: false e token: null.

Ultimo aggiornamento: 21 settembre 2026Hai trovato un errore? Segnalacelo

Autenticazione

Login e token#

Header Bearer#

Durata e rinnovo del token#

Contesto dell’hotel#

Errori di login#