房型与价格

为预订引擎搜索结果提供数据的两个端点：房型列表返回指定日期和入住人数下可售的房型、餐食类型及价格；房态返回逐日的可用房量和价格，用于日历视图。

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必填
酒店 ID。必须与 token 所属酒店一致。
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
房型 ID 和名称。预订时作为 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 基础 URL。
items[].accommodationTypes[]object[]
餐食类型。id 在预订中即 ratePlanID。priceType：0 按人计价，1 按房间计价。
…accommodationTypes[].prices{}object
价格选项。每个选项包含：total 晚数，price 总金额，currency，nonRefundable（为 "[NR]" 时不可退款），id 选项 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 m² 标准间。</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": "免费 Wi-Fi",
                    "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必填
酒店 ID。
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"
}
最后更新: 2026年9月21日发现错误？请告诉我们