Fluxul de rezervare

Fluxul tipic al unui motor de rezervări: obțineți un token, listați camerele pentru datele și numărul de persoane căutate de oaspete, aplicați tariful ales și eventualul cupon, finalizați pasul de plată și scrieți rezervarea în HMS cu BookingPushRQ. Acest ghid parcurge fiecare pas cu cereri și răspunsuri reale.

1Login/external/public/login

2Lista de camere/external/online/roomType

3Cupon · Pachetecoupon/search · stock/packages

4Platăpayment/type/{type}

5Transmiterechannel/booking

1. Obțineți un token#

Faceți login o singură dată, la pornirea serverului sau când tokenul expiră, și păstrați tokenul împreună cu ID-ul hotelului. Detalii: Autentificare.

2. Listați camerele#

Cereți lista de camere cu valorile din formularul de căutare al oaspetelui. Dacă sunt și copii, trimiteți vârstele lor; prețul pentru copii se calculează în funcție de vârstă.

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"

Ce afișați pentru fiecare tip de cameră din răspuns:

Câmp	Pe ecran
`name`, `images[]`, `detail`, `roomFeatures[]`	Cardul camerei
`roomCount`	Camere rămase. 0 înseamnă „nu se vinde” — motivul este în `roomRestrictionMessage`.
`accommodationTypes[].title`	Opțiunea de masă (mic dejun inclus, demipensiune…)
`accommodationTypes[].prices{}`	Opțiunile de tarif: standard și nerambursabil

Cheile obiectului prices au forma "<persons>-<1|0>". Sufixul 1 înseamnă tariful standard (rambursabil), 0 tariful nerambursabil; opțiunea nerambursabilă conține nonRefundable: "[NR]". La tarifarea pe cameră (priceType: 1), cheia este 1-1 / 1-0, indiferent de numărul de persoane.

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. Cupoane și pachete#

Dacă oaspetele introduce un cupon, validați-l și aplicați reducerea în sistemul dumneavoastră:

Terminal

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

Răspuns · 200

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

Cu change 0, rate este o reducere procentuală (10%); cu 1 este o sumă fixă (10.00 în moneda hotelului). Aplicați reducerea la suma camerei și trimiteți în rezervare totalurile reduse.

Pentru a vinde servicii suplimentare, afișați lista de pachete. Pachetele selectate intră în rezervare în extras[], cu id al pachetului în stockID. Totalurile rezultate după cupoane și pachete se scriu în Total al rezervării.

4. Pasul de plată#

Listați tipurile de plată acceptate de hotel și continuați în funcție de alegerea oaspetelui. Pentru tipul 10 (plată online) se inițiază o sesiune de plată, iar oaspetele este redirecționat către furnizor; după plată, revine la returnUrl al dumneavoastră. Toate tipurile sunt descrise în ghidul Fluxul de plată.

5. Transmiteți rezervarea#

După ce rezultatul plății este cunoscut, scrieți rezervarea în HMS. ID este codul unic pe care îl generați; comunicați oaspetelui același cod. ID-urile tipurilor de cameră și de masă provin din lista de camere.

Cerere

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,                      // codul unic al rezervării, generat de dvs.
  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,          // codul unic al rezervării, generat de dvs.
    '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'];

Răspuns · 200

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

HMS_ID este ID-ul rezervării în HMS; păstrați-l împreună cu propria înregistrare. Rezervarea apare în panou sub canalul „Online”, iar HMS trimite oaspetelui un e-mail de confirmare, conform setărilor hotelului.

Mai multe camere#

Când se vând mai multe camere cu același tip de cameră și tip de masă, fiecare cameră este un element RoomStays separat; NumberOfUnits este "1" pentru prima, "2" pentru a doua și așa mai departe. Tipurile de cameră diferite sunt, de asemenea, elemente separate. Total al rezervării este suma tuturor camerelor și a serviciilor suplimentare.

Modificări și anulări#

Trimiteți din nou rezervarea la același endpoint, cu același ID:

type: "Modify" — s-au schimbat datele, camerele sau datele oaspetelui. Trimiteți rezervarea completă, în starea ei actuală; HMS înlocuiește înregistrarea existentă cu aceasta.
type: "Cancel" — rezervarea a fost anulată. Și camerele au type: "Cancel".

Greșeli frecvente#

Păstrarea listei de camere în cache pentru mult timp. Disponibilitatea și tarifele se schimbă permanent; reîmprospătați lista înainte ca oaspetele să ajungă la pasul de plată.
Trimiterea unui childCount diferit de lungimea lui childAges[]: serverul se bazează pe lista de vârste și modifică tacit numărul de copii.
Trimiterea propriilor ID-uri ca roomTypeID / ratePlanID în locul ID-urilor din lista de camere: se returnează Could not register.
Trimiterea PaymentCard pentru alte tipuri de plată decât 9: datele cardului ajung inutil în HMS.
Reîncercarea după o eroare de rețea cu un alt ID: se creează o rezervare duplicată. Reîncercați cu același ID.

Ultima actualizare: 21 septembrie 2026Ați găsit o greșeală? Anunțați-ne