Alur reservasi

Alur umum untuk booking engine: dapatkan token, tampilkan kamar untuk tanggal dan jumlah tamu yang dicari tamu, terapkan tarif yang dipilih dan kupon jika ada, selesaikan langkah pembayaran, lalu catat reservasi di HMS dengan BookingPushRQ. Panduan ini menjelaskan setiap langkah dengan permintaan dan respons nyata.

1Login/external/public/login
2Daftar kamar/external/online/roomType
3Kupon · Paketcoupon/search · stock/packages
4Pembayaranpayment/type/{type}
5Kirimchannel/booking

1. Dapatkan token#

Lakukan login sekali saat server Anda dijalankan atau saat token kedaluwarsa, lalu simpan token bersama ID hotel. Detail: Autentikasi.

2. Tampilkan daftar kamar#

Minta daftar kamar dengan nilai dari form pencarian tamu. Jika ada anak-anak, kirim usia mereka; harga anak dihitung berdasarkan usia.

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"

Yang perlu ditampilkan untuk setiap tipe kamar dalam respons:

FieldDi layar
name, images[], detail, roomFeatures[]Kartu kamar
roomCountSisa kamar. 0 berarti “tidak dijual” — alasannya ada di roomRestrictionMessage.
accommodationTypes[].titleOpsi meal plan (Termasuk Sarapan, Half Board…)
accommodationTypes[].prices{}Opsi tarif: standar dan tidak dapat di-refund

Kunci objek prices berbentuk "<persons>-<1|0>". Akhiran 1 adalah tarif standar (dapat di-refund), 0 tarif tidak dapat di-refund; opsi yang tidak dapat di-refund memuat nonRefundable: "[NR]". Pada harga per kamar (priceType: 1), kuncinya adalah 1-1 / 1-0, berapa pun jumlah tamunya.

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 dan paket#

Jika tamu memasukkan kupon, validasi kupon tersebut dan terapkan diskonnya di sisi Anda:

Terminal
curl "https://test.hms.gen.tr/external/online/coupon/search" \
  -H "Authorization: Bearer $HMS_TOKEN" \
  -d "hotelID=1000" -d "coupon=SUMMER2026"
Respons · 200
{
    "success": true,
    "cupon": {
        "id": 12,
        "change": 0,
        "rate": "10.00"
    }
}

Jika change bernilai 0, rate adalah diskon persentase (10%); jika 1, nilainya berupa jumlah tetap (10.00 dalam mata uang hotel). Terapkan diskon pada jumlah kamar dan kirim total setelah diskon dalam reservasi.

Untuk menjual ekstra, tampilkan daftar paket. Paket yang dipilih dimasukkan ke reservasi sebagai extras[], dengan id paket di stockID. Total setelah kupon dan paket dicatat di Total reservasi.

4. Langkah pembayaran#

Tampilkan jenis pembayaran yang diterima hotel dan lanjutkan sesuai pilihan tamu. Untuk jenis 10 (pembayaran online), sesi pembayaran dimulai dan tamu diteruskan ke penyedia pembayaran; setelah membayar, tamu kembali ke returnUrl Anda. Semua jenis dibahas dalam panduan Alur pembayaran.

5. Kirim reservasi#

Setelah hasil pembayaran diketahui, catat reservasi di HMS. ID adalah kode unik yang Anda buat; berikan kode yang sama kepada tamu. ID tipe kamar dan meal plan diambil dari daftar kamar.

Permintaan
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
Respons · 200
{
    "BookingPushRS": {
        "Success": true,
        "BookingConfirmNumbers": [
            {
                "confirmTime": 1755500000,
                "bookingID": 48213,
                "bookingType": "Book",
                "HMS_ID": 48213
            }
        ]
    }
}

HMS_ID adalah ID reservasi di HMS; simpan bersama record Anda sendiri. Reservasi muncul di panel pada channel “Online”, dan HMS mengirim email konfirmasi kepada tamu sesuai pengaturan hotel.

Beberapa kamar#

Jika beberapa kamar dengan tipe kamar dan meal plan yang sama terjual, setiap kamar menjadi item RoomStays terpisah; NumberOfUnits bernilai "1" untuk kamar pertama, "2" untuk kamar kedua, dan seterusnya. Tipe kamar yang berbeda juga menjadi item terpisah. Total reservasi adalah jumlah dari semua kamar dan ekstra.

Perubahan dan pembatalan#

Kirim ulang reservasi ke endpoint yang sama dengan ID yang sama:

  • type: "Modify" — tanggal, kamar, atau data tamu berubah. Kirim reservasi lengkap dalam kondisi terbarunya; HMS mengganti record yang ada dengan data tersebut.
  • type: "Cancel" — reservasi dibatalkan. Kamar-kamarnya juga memuat type: "Cancel".

Kesalahan umum#

  • Menyimpan daftar kamar di cache terlalu lama. Ketersediaan dan tarif terus berubah; perbarui daftar sebelum tamu masuk ke langkah pembayaran.
  • Mengirim childCount yang berbeda dari panjang childAges[]: server mengikuti daftar usia dan mengubah jumlah anak tanpa pemberitahuan.
  • Mengirim ID milik Anda sendiri sebagai roomTypeID / ratePlanID, bukan ID dari daftar kamar: respons yang dikembalikan adalah Could not register.
  • Mengirim PaymentCard untuk jenis pembayaran selain 9: data kartu dikirim ke HMS tanpa perlu.
  • Mencoba ulang setelah error jaringan dengan ID yang berbeda: ini membuat reservasi duplikat. Coba ulang dengan ID yang sama.
Terakhir diperbarui: 21 September 2026Menemukan kesalahan? Beri tahu kami