Boekingsflow

De gebruikelijke flow voor een boekingsmodule: haal een token op, vraag de kamers op voor de datums en bezetting waarop de gast zoekt, pas het gekozen tarief en eventuele kortingscode toe, doorloop de betaalstap en leg de boeking met BookingPushRQ vast in HMS. Deze handleiding loopt elke stap door met echte verzoeken en antwoorden.

1Inloggen/external/public/login

2Kamerlijst/external/online/roomType

3Kortingscode · Pakkettencoupon/search · stock/packages

4Betalingpayment/type/{type}

5Doorsturenchannel/booking

1. Token ophalen#

Log één keer in wanneer je server start of wanneer het token verloopt, en bewaar het token samen met de hotel-ID. Details: Authenticatie.

2. Kamers opvragen#

Vraag de kamerlijst op met de waarden uit het zoekformulier van de gast. Reizen er kinderen mee, stuur dan hun leeftijden mee; kinderprijzen worden op basis van de leeftijd berekend.

Terminal

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"

Wat je per kamertype uit het antwoord toont:

Veld	Op het scherm
`name`, `images[]`, `detail`, `roomFeatures[]`	Kamerkaart
`roomCount`	Aantal resterende kamers. 0 betekent “niet te boeken” — de reden staat in `roomRestrictionMessage`.
`accommodationTypes[].title`	Verzorgingsoptie (Logies & ontbijt, Halfpension…)
`accommodationTypes[].prices{}`	Tariefopties: standaard en niet-restitueerbaar

De sleutels van het object prices hebben de vorm "<persons>-<1|0>". Het achtervoegsel 1 staat voor het standaardtarief (restitueerbaar), 0 voor het niet-restitueerbare tarief; de niet-restitueerbare optie bevat nonRefundable: "[NR]". Bij prijzen per kamer (priceType: 1) is de sleutel 1-1 / 1-0, ongeacht de bezetting.

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. Kortingscodes en pakketten#

Voert de gast een kortingscode in, valideer die dan en pas de korting zelf toe:

Terminal

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

Antwoord · 200

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

Bij change 0 is rate een kortingspercentage (10%); bij 1 is het een vast bedrag (10.00 in de valuta van het hotel). Pas de korting toe op het kamerbedrag en stuur de totalen na korting mee in de boeking.

Wil je extra’s verkopen, toon dan de pakketlijst. Gekozen pakketten gaan als extras[] mee in de boeking, met de id van het pakket in stockID. De totalen na kortingscodes en pakketten komen in Total van de boeking.

4. Betaalstap#

Vraag de betaalmethoden op die het hotel accepteert en ga verder op basis van de keuze van de gast. Bij type 10 (online betaling) wordt een betaalsessie gestart en wordt de gast doorgestuurd naar de provider; na de betaling keert de gast terug naar je returnUrl. Alle methoden worden behandeld in de handleiding Betaalflow.

5. Boeking doorsturen#

Zodra de uitkomst van de betaling bekend is, leg je de boeking vast in HMS. ID is de unieke code die je zelf aanmaakt; geef de gast dezelfde code. De ID’s van kamertype en verzorgingstype komen uit de kamerlijst.

Verzoek

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,                      // je unieke boekingscode
  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,          // je unieke boekingscode
    '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'];

Antwoord · 200

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

HMS_ID is de boekings-ID in HMS; bewaar die bij je eigen record. De boeking verschijnt in het beheerpaneel onder het kanaal “Online”, en HMS stuurt de gast een bevestigingsmail volgens de instellingen van het hotel.

Meerdere kamers#

Worden meerdere kamers van hetzelfde kamertype en verzorgingstype verkocht, dan is elke kamer een apart RoomStays-item; NumberOfUnits is "1" voor de eerste, "2" voor de tweede, enzovoort. Verschillende kamertypen zijn ook aparte items. Total van de boeking is de som van alle kamers en extra’s.

Wijzigingen en annuleringen#

Stuur de boeking opnieuw naar hetzelfde endpoint, met dezelfde ID:

type: "Modify" — datums, kamers of gastgegevens zijn gewijzigd. Stuur de volledige boeking in de huidige staat; HMS vervangt het bestaande record daarmee.
type: "Cancel" — de boeking is geannuleerd. De kamers krijgen ook type: "Cancel".

Veelgemaakte fouten#

De kamerlijst lang cachen. Beschikbaarheid en tarieven veranderen voortdurend; vernieuw de lijst voordat de gast aan de betaalstap begint.
Een childCount sturen die afwijkt van de lengte van childAges[]: de server gaat uit van de leeftijdenlijst en past het aantal kinderen stilzwijgend aan.
Je eigen ID’s als roomTypeID / ratePlanID sturen in plaats van de ID’s uit de kamerlijst: je krijgt dan Could not register. terug.
PaymentCard sturen bij andere betaalmethoden dan 9: kaartgegevens worden dan onnodig naar HMS verstuurd.
Na een netwerkfout opnieuw proberen met een andere ID: daarmee maak je een dubbele boeking aan. Probeer opnieuw met dezelfde ID.

Laatst bijgewerkt: 21 september 2026Fout gevonden? Laat het ons weten