Rezervasyon akışı

Bir rezervasyon motoru için tipik akış: token al, misafirin aradığı tarih ve kişi sayısıyla odaları listele, seçilen fiyatı ve varsa kuponu uygula, ödeme adımını tamamla, rezervasyonu BookingPushRQ ile HMS’e yaz. Bu rehber her adımı gerçek istek ve yanıtlarla anlatır.

1Giriş/external/public/login

2Oda listesi/external/online/roomType

3Kupon · Paketcoupon/search · stock/packages

4Ödemepayment/type/{tip}

5Aktarımchannel/booking

1. Token alın#

Sunucunuz başlarken veya token süresi dolunca bir kez giriş yapın ve token’ı otel kimliğiyle birlikte saklayın. Ayrıntı: Kimlik doğrulama.

2. Odaları listeleyin#

Misafirin arama formundaki değerlerle oda listesini isteyin. Çocuk varsa yaşlarını gönderin; çocuk fiyatı yaşa göre hesaplanır.

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=tr"

Yanıttaki her oda tipi için ekranda gösterilecekler:

Alan	Ekranda
`name`, `images[]`, `detail`, `roomFeatures[]`	Oda kartı
`roomCount`	Kalan oda adedi. 0 ise “satışta değil” — nedeni `roomRestrictionMessage`.
`accommodationTypes[].title`	Pansiyon seçeneği (Kahvaltı dahil, Yarım pansiyon…)
`accommodationTypes[].prices{}`	Fiyat seçenekleri: standart ve iade edilemez

prices nesnesinin anahtarı "<kişi>-<1|0>" biçimindedir. Sonek 1 standart (iade edilebilir), 0 iade edilemez fiyattır; iade edilemez seçenekte nonRefundable alanı "[NR]" gelir. Oda bazlı fiyatlamada (priceType: 1) anahtar kişi sayısından bağımsız olarak 1-1 / 1-0 olur.

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. Kupon ve paketler#

Misafir kupon girerse doğrulayın ve indirimi kendi tarafınızda uygulayın:

Terminal

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

Yanıt · 200

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

change 0 ise rate yüzde indirimdir (%10), 1 ise net tutardır (10,00 TL). İndirimi oda tutarına uygulayın ve indirimli tutarı rezervasyonda gönderin.

Ek hizmet satacaksanız paket listesini gösterin. Seçilen paketler rezervasyonda extras[] olarak, paket id değeri stockID alanında gönderilir. Kupon ve paketlerden sonra oluşan tutarlar rezervasyonun Total alanına yazılır.

4. Ödeme adımı#

Otelin kabul ettiği ödeme tiplerini listeleyin ve misafirin seçtiği tipe göre ilerleyin. Tip 10 (online ödeme) için ödeme oturumu açılır ve misafir dönen adrese yönlendirilir; ödeme tamamlandığında returnUrl adresinize döner. Tüm tipler için Ödeme akışı rehberine bakın.

5. Rezervasyonu aktarın#

Ödeme sonucu belli olduktan sonra rezervasyonu HMS’e yazın. ID sizin ürettiğiniz benzersiz koddur; misafire de bu kodu iletin. Oda ve konaklama tipi kimlikleri oda listesinden gelir.

İstek

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

const booking = {
  hotelID: "1000",
  ID: orderNo,                      // sizin benzersiz rezervasyon kodunuz
  type: "Book",
  createDateTime: new Date().toISOString(),
  checkinDate: "2026-08-18",
  checkoutDate: "2026-08-20",
  RoomStays: [{
    roomTypeID: "2", roomName: "Standart Oda",
    ratePlanID: "2", ratePlanName: "Kahvaltı Dahil",
    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: "Geç giriş, 23:00 civarı." }],
  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,          // sizin benzersiz rezervasyon kodunuz
    'type'           => 'Book',
    'createDateTime' => date('c'),
    'checkinDate'    => '2026-08-18',
    'checkoutDate'   => '2026-08-20',
    'RoomStays'      => [[
        'roomTypeID' => '2', 'roomName' => 'Standart Oda',
        'ratePlanID' => '2', 'ratePlanName' => 'Kahvaltı Dahil',
        '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' => 'Geç giriş, 23:00 civarı.']],
    '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'];

Yanıt · 200

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

HMS_ID HMS’deki rezervasyon kimliğidir; kendi kaydınızda saklayın. Rezervasyon panelde “Online” kanalı altında görünür ve HMS otel ayarlarına göre misafire onay e-postası gönderir.

Birden fazla oda#

Aynı oda tipi ve konaklama tipinden birden fazla oda satıldığında her oda ayrı bir RoomStays öğesi olur; NumberOfUnits ilk odada "1", ikincide "2"… şeklinde artar. Farklı oda tipleri için de her oda ayrı öğedir. Rezervasyonun Total alanı tüm odaların ve ekstraların toplamıdır.

Değişiklik ve iptal#

Aynı uç noktaya aynı ID ile yeniden gönderin:

type: "Modify" — tarih, oda veya misafir bilgisi değişti. Tüm rezervasyonu güncel haliyle gönderin; HMS mevcut kaydı bu içerikle günceller.
type: "Cancel" — rezervasyon iptal edildi. Odalar da type: "Cancel" taşır.

Sık yapılan hatalar#

Oda listesini uzun süre önbelleklemek. Müsaitlik ve fiyat anlık değişir; misafir ödeme adımına geçmeden önce listeyi yenileyin.
childCount ile childAges[] uzunluğunu farklı göndermek: sunucu yaş listesini esas alır, çocuk sayısı sessizce değişir.
Rezervasyonda roomTypeID / ratePlanID olarak oda listesindeki kimlikler yerine kendi kimliklerinizi göndermek: Could not register. döner.
Ödeme tipi 9 dışında PaymentCard göndermek: kart verisi gereksiz yere HMS’e iletilir.
Ağ hatasında farklı bir ID ile tekrar göndermek: çift rezervasyon oluşur. Aynı ID ile tekrarlayın.

Son güncelleme: 8 Eylül 2026Bu sayfada bir hata mı var? Bize yazın