اتاق‌ها و نرخ‌ها

دو اندپوینت که نتایج جست‌وجوی موتور رزرو را تأمین می‌کنند: فهرست اتاق‌ها که انواع اتاق قابل فروش، انواع پذیرایی و قیمت‌ها را برای تاریخ‌ها و تعداد نفرات موردنظر برمی‌گرداند، و ظرفیت خالی که ظرفیت و نرخ روزبه‌روز را برای نمای تقویمی ارائه می‌دهد.

POST/external/online/roomTypeفهرست اتاق‌ها و نرخ‌هاGET/external/room/type/hotel/availabilityتقویم ظرفیت

فهرست اتاق‌ها و نرخ‌ها#

POST/external/online/roomType

احراز هویت: Authorization: Bearer · بدنه: application/x-www-form-urlencoded یا multipart/form-data

انواع اتاق هتل را که برای تاریخ‌ها و تعداد نفرات موردنظر برای فروش آنلاین باز هستند برمی‌گرداند. برای هر نوع اتاق، تعداد اتاق خالی (roomCount)، محدودیت‌ها (حداقل اقامت، بسته بودن برای ورود/خروج)، انواع پذیرایی و گزینه‌های قیمت محاسبه می‌شود. اگر کودک همراه است، سن کودکان را با childAges[] ارسال کنید؛ قیمت کودک به سن بستگی دارد.

قواعد اعتبارسنجی: تاریخ ورود امروز یا بعد از آن، تاریخ خروج بعد از تاریخ ورود، حداکثر 30 شب، 1 تا 40 بزرگسال، 0 تا 10 کودک (0 تا 16 سال).

فیلدهای فرم

hotelIDintegerالزامی
شناسه هتل. باید با هتل توکن یکسان باشد.
startDatedateالزامی
تاریخ ورود، YYYY-MM-DD.
endDatedateالزامی
تاریخ خروج، YYYY-MM-DD.
adultCountintegerالزامی
تعداد بزرگسالان (1 تا 40).
childCountintegerپیش‌فرض: 0
تعداد کودکان (0 تا 10). اگر با childAges همخوانی نداشته باشد، طول فهرست سنین ملاک است.
childAges[]integer[]
سن هر کودک (0 تا 16). به‌صورت فیلد فرم تکرار می‌شود: childAges[]=7&childAges[]=12.
languagestringپیش‌فرض: tr
زبان پاسخ (نام اتاق‌ها، عنوان ویژگی‌ها، پیام‌های خطا).
buildingIDinteger
فقط اتاق‌های این ساختمان (بلوک) را فهرست می‌کند.

پاسخ

200 فهرست انواع اتاق. قیمت‌ها زیر هر نوع پذیرایی در شیء prices قرار دارند، با کلیدهایی به شکل "<persons>-<1|0>": -1 نرخ استاندارد (قابل استرداد) و -0 نرخ غیرقابل استرداد ([NR]) است. در قیمت‌گذاری بر اساس اتاق، کلیدها 1-1 / 1-0 هستند.

items[].id / nameinteger / string
شناسه و نام نوع اتاق. در رزرو به‌صورت roomTypeID ارسال می‌شود.
items[].capacityAdult / capacityChildren / capacityTotalinteger
ظرفیت بزرگسال، کودک و کل.
items[].roomCountinteger
تعداد اتاق‌های قابل فروش برای این تاریخ‌ها. 0 یعنی قابل فروش نیست؛ دلیل آن در roomRestrictionMessage آمده است.
items[].roomRestrictionMessagestring | null
محدودیت فروش.
closed_to_checkinclosed_to_checkoutpassive_salesminimum_staymaximum_stayclosed_to_arrivalprice_not_found
items[].nonRefundable / refundableboolean
اینکه نوع اتاق نرخ غیرقابل استرداد و/یا قابل استرداد ارائه می‌کند یا نه.
items[].images[]string[]
مسیر تصاویر، نسبت به آدرس پایه API.
items[].accommodationTypes[]object[]
انواع پذیرایی. id در رزرو به ratePlanID تبدیل می‌شود. priceType: 0 قیمت‌گذاری بر اساس نفر، 1 بر اساس اتاق.
…accommodationTypes[].prices{}object
گزینه‌های قیمت. هر گزینه: total تعداد شب‌ها، price مبلغ کل، currency، nonRefundable ("[NR]" یعنی غیرقابل استرداد)، id شناسه انتخاب، prices[] نرخ‌های شبانه (price، tarih به قالب dd.mm.yyyy).
items[].roomFeatures[]object[]
ویژگی‌های اتاق: title، icon.
countinteger
تعداد انواع اتاق بازگشتی.
errorMessage / errorCodestring | integer | null
در صورت خطا مقدار می‌گیرد. فهرست کدها: کدهای خطا.

پاسخ‌های خطا

  • 200 errorCode 10001 هتل یافت نشد · 10002 پارامتر ناقص · 10003 هتل برای فروش آنلاین بسته است · 10004 هیچ نوع اتاقی برای فروش باز نیست · 10022 پارامترهای تاریخ/تعداد نفرات نامعتبر · 20001 تا 20004 ظرفیت خالی کافی نیست.
درخواست
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"
پاسخ · 200
{
    "success": true,
    "items": [
        {
            "id": 2,
            "name": "اتاق استاندارد",
            "capacityAdult": 2,
            "capacityTotal": 3,
            "totalBed": 1,
            "totalBathroom": 1,
            "roomSize": 24,
            "currency": "TRY",
            "detail": "<p>اتاق استاندارد 24 متر مربعی با چشم‌انداز باغ.</p>",
            "roomCount": 5,
            "roomRestrictionMessage": null,
            "nonRefundable": false,
            "refundable": true,
            "images": [
                "images/1000/odatipi/standart-1.jpg",
                "images/1000/odatipi/standart-2.jpg"
            ],
            "accommodationTypes": [
                {
                    "id": 2,
                    "title": "با صبحانه",
                    "priceType": 0,
                    "roomRestriction": 1,
                    "roomRestrictionMessage": null,
                    "roomRestrictionValue": null,
                    "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"
                                }
                            ]
                        }
                    }
                }
            ],
            "roomFeatures": [
                {
                    "title": "تهویه مطبوع",
                    "icon": "fa-snowflake"
                },
                {
                    "title": "وای‌فای رایگان",
                    "icon": "fa-wifi"
                }
            ],
            "capacityChildren": 1
        }
    ],
    "count": 1,
    "errorMessage": null,
    "errorCode": null
}
پاسخ · 200 (بدون ظرفیت خالی)
{
    "success": false,
    "errorMessage": "ظرفیت خالی کافی برای بزرگسالان وجود ندارد.",
    "errorCode": 20001
}

تقویم ظرفیت#

GET/external/room/type/hotel/availability

احراز هویت: Authorization: Bearer

تعداد اتاق خالی و نرخ پایه هر نوع اتاق را روزبه‌روز برمی‌گرداند. برای نمای تقویمی و نقشه حرارتی نرخ‌ها طراحی شده است؛ برای قیمت دقیق و بررسی محدودیت‌ها از فهرست اتاق‌ها استفاده کنید.

پارامترهای کوئری

hotelIDintegerالزامی
شناسه هتل.
startDatedatetimeالزامی
شروع، YYYY-MM-DD یا YYYY-MM-DDTHH:MM:SS.
endDatedatetimeالزامی
پایان (خود این روز هم شامل می‌شود).

پاسخ

200 فهرست روزانه برای هر نوع اتاق. availability برابر -1 یعنی برای آن روز داده‌ای درباره ظرفیت وجود ندارد؛ price برابر "-" یعنی نرخی تعریف نشده است.

پاسخ‌های خطا

  • 200 hotel_id_is_not_found، start_date_is_not_found، end_date_is_not_found — پارامتر ارسال نشده است.
درخواست
curl "https://test.hms.gen.tr/external/room/type/hotel/availability?hotelID=1000&startDate=2026-08-18&endDate=2026-08-21" \
  -H "Authorization: Bearer $HMS_TOKEN"
پاسخ · 200
{
    "success": true,
    "roomTypes": [
        {
            "name": "اتاق استاندارد",
            "id": 2,
            "rate": 2,
            "availability": [
                {
                    "id": 20260818,
                    "start": "2026-08-18 12:00:00",
                    "end": "2026-08-19 12:00:00",
                    "availability": 5,
                    "price": "965.00"
                },
                {
                    "id": 20260819,
                    "start": "2026-08-19 12:00:00",
                    "end": "2026-08-20 12:00:00",
                    "availability": 3,
                    "price": "965.00"
                },
                {
                    "id": 20260820,
                    "start": "2026-08-20 12:00:00",
                    "end": "2026-08-21 12:00:00",
                    "availability": 0,
                    "price": "1,100.00"
                },
                {
                    "id": 20260821,
                    "start": "2026-08-21 12:00:00",
                    "end": "2026-08-22 12:00:00",
                    "availability": -1,
                    "price": "-"
                }
            ]
        }
    ],
    "currency": "TRY"
}
آخرین به‌روزرسانی: 21 سپتامبر 2026اشتباهی دیدید؟ به ما اطلاع دهید