Flusso di prenotazione

Il flusso tipico di un motore di prenotazione: ottieni un token, elenca le camere per le date e l’occupazione cercate dall’ospite, applica la tariffa scelta ed eventuali coupon, completa la fase di pagamento e scrivi la prenotazione in HMS con BookingPushRQ. Questa guida illustra ogni passaggio con richieste e risposte reali.

1Login/external/public/login

2Elenco camere/external/online/roomType

3Coupon · Pacchetticoupon/search · stock/packages

4Pagamentopayment/type/{type}

5Inviochannel/booking

1. Ottieni un token#

Esegui il login una volta all’avvio del server o alla scadenza del token e salva il token insieme all’ID dell’hotel. Dettagli: Autenticazione.

2. Elenca le camere#

Richiedi l’elenco camere con i valori del form di ricerca dell’ospite. Se viaggiano bambini, invia le loro età: il prezzo per i bambini viene calcolato in base all’età.

Terminale

curl "https://test.hms.gen.tr/external/online/roomType" \
  -H "Authorization: Bearer $HMS_TOKEN" \
  -d "hotelID=1000" -d "startDate=2026-08-18" -d "endDate=2026-08-20" \
  -d "adultCount=2" -d "childCount=1" -d "childAges[]=7" -d "language=en"

Cosa mostrare per ogni tipologia di camera della risposta:

Campo	Sullo schermo
`name`, `images[]`, `detail`, `roomFeatures[]`	Scheda della camera
`roomCount`	Camere rimaste. 0 significa “non in vendita”: il motivo è in `roomRestrictionMessage`.
`accommodationTypes[].title`	Opzione di trattamento (pernottamento e colazione, mezza pensione…)
`accommodationTypes[].prices{}`	Opzioni tariffarie: standard e non rimborsabile

Le chiavi dell’oggetto prices hanno la forma "<persons>-<1|0>". Il suffisso 1 indica la tariffa standard (rimborsabile), 0 la tariffa non rimborsabile; l’opzione non rimborsabile contiene nonRefundable: "[NR]". Con il prezzo per camera (priceType: 1) la chiave è 1-1 / 1-0 indipendentemente dall’occupazione.

accommodationTypes[0].prices

{
    "2-1": {
        "total": 2,
        "title": 2,
        "nonRefundable": "",
        "price": "1930.00",
        "currency": "TRY",
        "id": "2/2",
        "prices": [
            {
                "price": "965.00",
                "tarih": "18.08.2026"
            },
            {
                "price": "965.00",
                "tarih": "19.08.2026"
            }
        ]
    },
    "2-0": {
        "total": 2,
        "title": 2,
        "nonRefundable": "[NR]",
        "price": "1737.00",
        "currency": "TRY",
        "id": "2-0/2",
        "prices": [
            {
                "price": "868.50",
                "tarih": "18.08.2026"
            },
            {
                "price": "868.50",
                "tarih": "19.08.2026"
            }
        ]
    }
}

3. Coupon e pacchetti#

Se l’ospite inserisce un coupon, convalidalo e applica lo sconto dal tuo lato:

Terminale

curl "https://test.hms.gen.tr/external/online/coupon/search" \
  -H "Authorization: Bearer $HMS_TOKEN" \
  -d "hotelID=1000" -d "coupon=SUMMER2026"

Risposta · 200

{
    "success": true,
    "cupon": {
        "id": 12,
        "change": 0,
        "rate": "10.00"
    }
}

Con change 0, rate è uno sconto percentuale (10%); con 1 è un importo fisso (10.00 nella valuta dell’hotel). Applica lo sconto all’importo della camera e invia i totali scontati nella prenotazione.

Per vendere extra, mostra l’elenco dei pacchetti. I pacchetti selezionati entrano nella prenotazione come extras[], con l’id del pacchetto in stockID. I totali comprensivi di coupon e pacchetti vanno scritti nel campo Total della prenotazione.

4. Fase di pagamento#

Elenca i tipi di pagamento accettati dall’hotel e procedi in base alla scelta dell’ospite. Per il tipo 10 (pagamento online) viene avviata una sessione di pagamento e l’ospite viene reindirizzato al provider; dopo il pagamento torna al tuo returnUrl. Tutti i tipi sono descritti nella guida Flusso di pagamento.

5. Invia la prenotazione#

Quando conosci l’esito del pagamento, scrivi la prenotazione in HMS. ID è il codice univoco che generi tu; comunica lo stesso codice all’ospite. Gli ID di tipologia di camera e di trattamento provengono dall’elenco camere.

Richiesta

curl -X POST "https://test.hms.gen.tr/external/online/channel/booking" \
  -H "Authorization: Bearer $HMS_TOKEN" \
  -H "Content-Type: application/json" \
  -d @booking.json

const booking = {
  hotelID: "1000",
  ID: orderNo,                      // il tuo codice di prenotazione univoco
  type: "Book",
  createDateTime: new Date().toISOString(),
  checkinDate: "2026-08-18",
  checkoutDate: "2026-08-20",
  RoomStays: [{
    roomTypeID: "2", roomName: "Standard Room",
    ratePlanID: "2", ratePlanName: "Bed & Breakfast",
    type: "Book", NumberOfUnits: "1",
    checkinDate: "2026-08-18", checkoutDate: "2026-08-20",
    GuestCount: { adult: 2, child: 1 },
    PerDayRates: { currency: "TRY", PerDayRate: [
      { stayDate: "2026-08-18", baseRate: "965.00", hotelServiceFees: "0" },
      { stayDate: "2026-08-19", baseRate: "965.00", hotelServiceFees: "0" }
    ]},
    Total: { amountAfterTaxes: "1930.00", amountOfTaxes: "175.45", currency: "TRY" }
  }],
  PrimaryGuests: [{ name: "Ayşe", surname: "Demir", PhoneNumber: "+905551112233", email: "[email protected]", CountryCode: "TR" }],
  ChildGuests: [{ age: 7 }],
  SpecialRequest: [{ text: "Late check-in, around 23:00." }],
  extras: [],
  Total: { amountAfterTaxes: "1930.00", amountOfTaxes: "175.45", extraTotal: "0.00", currency: "TRY" }
};

const res = await fetch("https://test.hms.gen.tr/external/online/channel/booking", {
  method: "POST",
  headers: { "Authorization": `Bearer ${process.env.HMS_TOKEN}`, "Content-Type": "application/json" },
  body: JSON.stringify({ BookingPushRQ: { Bookings: [booking] } })
});
const { BookingPushRS } = await res.json();
if (BookingPushRS.Error) throw new Error(BookingPushRS.Error);
const hmsId = BookingPushRS.BookingConfirmNumbers[0].HMS_ID;

$booking = [
    'hotelID'        => '1000',
    'ID'             => $orderNo,          // il tuo codice di prenotazione univoco
    'type'           => 'Book',
    'createDateTime' => date('c'),
    'checkinDate'    => '2026-08-18',
    'checkoutDate'   => '2026-08-20',
    'RoomStays'      => [[
        'roomTypeID' => '2', 'roomName' => 'Standard Room',
        'ratePlanID' => '2', 'ratePlanName' => 'Bed & Breakfast',
        'type' => 'Book', 'NumberOfUnits' => '1',
        'checkinDate' => '2026-08-18', 'checkoutDate' => '2026-08-20',
        'GuestCount'  => ['adult' => 2, 'child' => 1],
        'PerDayRates' => ['currency' => 'TRY', 'PerDayRate' => [
            ['stayDate' => '2026-08-18', 'baseRate' => '965.00', 'hotelServiceFees' => '0'],
            ['stayDate' => '2026-08-19', 'baseRate' => '965.00', 'hotelServiceFees' => '0'],
        ]],
        'Total' => ['amountAfterTaxes' => '1930.00', 'amountOfTaxes' => '175.45', 'currency' => 'TRY'],
    ]],
    'PrimaryGuests'  => [['name' => 'Ayşe', 'surname' => 'Demir', 'PhoneNumber' => '+905551112233', 'email' => '[email protected]', 'CountryCode' => 'TR']],
    'ChildGuests'    => [['age' => 7]],
    'SpecialRequest' => [['text' => 'Late check-in, around 23:00.']],
    'extras'         => [],
    'Total'          => ['amountAfterTaxes' => '1930.00', 'amountOfTaxes' => '175.45', 'extraTotal' => '0.00', 'currency' => 'TRY'],
];

$ch = curl_init('https://test.hms.gen.tr/external/online/channel/booking');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => 'POST',
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . getenv('HMS_TOKEN'), 'Content-Type: application/json'],
    CURLOPT_POSTFIELDS     => json_encode(['BookingPushRQ' => ['Bookings' => [$booking]]]),
]);
$rs = json_decode(curl_exec($ch), true)['BookingPushRS'];
if (isset($rs['Error'])) {
    throw new RuntimeException($rs['Error']);
}
$hmsId = $rs['BookingConfirmNumbers'][0]['HMS_ID'];

Risposta · 200

{
    "BookingPushRS": {
        "Success": true,
        "BookingConfirmNumbers": [
            {
                "confirmTime": 1755500000,
                "bookingID": 48213,
                "bookingType": "Book",
                "HMS_ID": 48213
            }
        ]
    }
}

HMS_ID è l’ID della prenotazione in HMS: salvalo insieme al tuo record. La prenotazione compare nel pannello sotto il canale “Online” e HMS invia all’ospite un’e-mail di conferma in base alle impostazioni dell’hotel.

Più camere#

Quando si vendono più camere della stessa tipologia e con lo stesso trattamento, ogni camera è un elemento RoomStays separato; NumberOfUnits vale "1" per la prima, "2" per la seconda e così via. Anche tipologie di camera diverse sono elementi separati. Il Total della prenotazione è la somma di tutte le camere e degli extra.

Modifiche e cancellazioni#

Invia di nuovo la prenotazione allo stesso endpoint con lo stesso ID:

type: "Modify" — sono cambiati date, camere o dati degli ospiti. Invia la prenotazione completa nel suo stato attuale: HMS sostituisce con essa il record esistente.
type: "Cancel" — la prenotazione è stata cancellata. Anche le camere riportano type: "Cancel".

Errori comuni#

Tenere in cache l’elenco camere troppo a lungo. Disponibilità e tariffe cambiano di continuo: aggiorna l’elenco prima che l’ospite passi alla fase di pagamento.
Inviare un childCount diverso dalla lunghezza di childAges[]: il server si basa sull’elenco delle età e modifica il numero di bambini senza segnalarlo.
Inviare i tuoi ID come roomTypeID / ratePlanID invece degli ID dell’elenco camere: viene restituito Could not register.
Inviare PaymentCard per tipi di pagamento diversi dal 9: i dati della carta vengono trasmessi a HMS inutilmente.
Riprovare dopo un errore di rete con un ID diverso: si crea una prenotazione duplicata. Riprova con lo stesso ID.

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