Buchungsablauf

Der typische Ablauf einer Buchungsmaschine: Token abrufen, Zimmer für den Zeitraum und die Belegung der Suche des Gastes auflisten, die gewählte Rate und einen eventuellen Gutschein anwenden, den Zahlungsschritt abschließen und die Buchung per BookingPushRQ in HMS schreiben. Dieser Leitfaden führt mit echten Anfragen und Antworten durch jeden Schritt.

1Anmeldung/external/public/login

2Zimmerliste/external/online/roomType

3Gutschein · Paketecoupon/search · stock/packages

4Zahlungpayment/type/{type}

5Übermittlungchannel/booking

1. Token abrufen#

Melden Sie sich einmal beim Start Ihres Servers oder nach Ablauf des Tokens an und speichern Sie das Token zusammen mit der Hotel-ID. Details: Authentifizierung.

2. Zimmer auflisten#

Fragen Sie die Zimmerliste mit den Werten aus dem Suchformular des Gastes ab. Reisen Kinder mit, senden Sie ihr Alter; die Kinderpreise werden nach Alter berechnet.

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"

Was Sie für jeden Zimmertyp der Antwort anzeigen:

Feld	Anzeige
`name`, `images[]`, `detail`, `roomFeatures[]`	Zimmerkarte
`roomCount`	Verbleibende Zimmer. 0 bedeutet „nicht buchbar“ — Grund in `roomRestrictionMessage`.
`accommodationTypes[].title`	Verpflegungsoption (Übernachtung mit Frühstück, Halbpension …)
`accommodationTypes[].prices{}`	Ratenoptionen: Standard und nicht erstattbar

Die Schlüssel des Objekts prices haben die Form "<persons>-<1|0>". Die Endung 1 steht für die Standardrate (erstattbar), 0 für die nicht erstattbare Rate; die nicht erstattbare Option enthält nonRefundable: "[NR]". Bei Preisen pro Zimmer (priceType: 1) lautet der Schlüssel unabhängig von der Belegung 1-1 / 1-0.

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. Gutscheine und Pakete#

Gibt der Gast einen Gutschein ein, prüfen Sie ihn und wenden Sie den Rabatt auf Ihrer Seite an:

Terminal

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

Antwort · 200

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

Bei change 0 ist rate ein prozentualer Rabatt (10 %), bei 1 ein fester Betrag (10.00 in der Hotelwährung). Wenden Sie den Rabatt auf den Zimmerbetrag an und senden Sie in der Buchung die rabattierten Summen.

Um Extras zu verkaufen, zeigen Sie die Paketliste an. Ausgewählte Pakete gehen als extras[] in die Buchung ein, mit der id des Pakets in stockID. Die Summen nach Gutscheinen und Paketen werden in Total der Buchung geschrieben.

4. Zahlungsschritt#

Listen Sie die Zahlungsarten auf, die das Hotel akzeptiert, und fahren Sie entsprechend der Wahl des Gastes fort. Bei Typ 10 (Online-Zahlung) wird eine Zahlungssitzung gestartet und der Gast an den Anbieter übergeben; nach der Zahlung kehrt er zu Ihrer returnUrl zurück. Alle Typen behandelt der Leitfaden Zahlungsablauf.

5. Buchung übermitteln#

Sobald das Ergebnis der Zahlung feststeht, schreiben Sie die Buchung in HMS. ID ist der eindeutige Code, den Sie erzeugen; teilen Sie dem Gast denselben Code mit. Die IDs von Zimmertyp und Verpflegungsart stammen aus der Zimmerliste.

Anfrage

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,                      // Ihr eindeutiger Buchungscode
  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,          // Ihr eindeutiger Buchungscode
    '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'];

Antwort · 200

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

HMS_ID ist die Buchungs-ID in HMS; speichern Sie sie mit Ihrem eigenen Datensatz. Die Buchung erscheint im Panel unter dem Kanal „Online“, und HMS sendet dem Gast entsprechend den Einstellungen des Hotels eine Bestätigungs-E-Mail.

Mehrere Zimmer#

Werden mehrere Zimmer desselben Zimmertyps und derselben Verpflegungsart verkauft, ist jedes Zimmer ein eigenes RoomStays-Element; NumberOfUnits ist "1" für das erste, "2" für das zweite und so weiter. Unterschiedliche Zimmertypen sind ebenfalls eigene Elemente. Total der Buchung ist die Summe aller Zimmer und Extras.

Änderungen und Stornierungen#

Senden Sie die Buchung mit derselben ID erneut an denselben Endpunkt:

type: "Modify" — Reisedaten, Zimmer oder Angaben zu den Gästen haben sich geändert. Senden Sie die vollständige Buchung im aktuellen Zustand; HMS ersetzt den bestehenden Datensatz damit.
type: "Cancel" — die Buchung wurde storniert. Auch die Zimmer tragen type: "Cancel".

Häufige Fehler#

Die Zimmerliste lange zwischenspeichern. Verfügbarkeit und Preise ändern sich ständig; aktualisieren Sie die Liste, bevor der Gast zum Zahlungsschritt wechselt.
Einen childCount senden, der von der Länge von childAges[] abweicht: Der Server verlässt sich auf die Altersliste und ändert die Kinderanzahl stillschweigend.
Eigene IDs als roomTypeID / ratePlanID senden statt der IDs aus der Zimmerliste: Es wird Could not register. zurückgegeben.
PaymentCard bei anderen Zahlungsarten als 9 senden: Kartendaten werden unnötig an HMS übertragen.
Nach einem Netzwerkfehler mit einer anderen ID wiederholen: Dadurch entsteht eine doppelte Buchung. Wiederholen Sie mit derselben ID.

Zuletzt aktualisiert: 21. September 2026Fehler gefunden? Schreiben Sie uns