Module: hotel

酒店查询与预订。无需入住日期的基础资料查询见 module:hotel/meta。

Methods


<static> book(header, body)

post 预订

Parameters:
Name Type Argument Default Description
header YHeader

Http request header

params.mode string <optional>
async

模式。由于预订可能需要耗费较长时间,为了提升用户体验可以通过异步机制来分步产生订单和获取预订确认号

  • sync 同步响应所有数据
  • async 推荐,同步响应订单数据,订单状态为 confirming。后续通过 webhook 或 order/search 异步获取确认号,订单状态为 upcoming
body object

Http request body

Properties
Name Type Argument Description
user User <optional>

预订人

booking HotelBooking

酒店预订信息

payment Payment <optional>

支付信息

merchant object <optional>

商户的订单信息

Properties:
Name Type Description
body.merchant.uid string

订单识别码

Since:
  • 1.0.0
Returns:
Type
bookResponse

<static> rateCalendar(header, body)

post 查询酒店每日单晚价格。dateRange.end 为不包含的结束日期;普通渠道最多查询 90 天,hotelux 和 hoteluxjp 最多查询 270 天。

Parameters:
Name Type Description
header YHeader

Http request header

body object

Http request body

Properties
Name Type Argument Description
preferred Preferred <optional>

偏好设置,currency 用于价格换算

hotel Hotel

酒店,传入 _id

dateRange object

查询日期区间

Properties
Name Type Description
start string

起始入住日期,YYYY-MM-DD

end string

结束日期,YYYY-MM-DD,不包含当天

Since:
  • 1.0.0
Returns:
Type
HotelRateCalendarResponse

<static> rateRule(header, body)

post 获取价格方案及规则。获取更准确的价格明细,务必在用户下单前向用户展示。

  • E.g. 部分酒店住三付二(第一天 1200,第二天 1200,第三天免费),在 rates 接口可能会获得 800, 800, 800 的价格明细,在 rateRule 接口可以获得准确的 1200, 1200, 0 价格明细
Parameters:
Name Type Description
header YHeader

Http request header

body object

Http request body

Properties
Name Type Argument Description
preferred Preferred <optional>

偏好设置

stay Stay

入住信息

hotel Hotel

酒店

rate HotelRate

价格方案

Since:
  • 1.0.0
Returns:
Type
rateRuleResponse

<static> rates(header [, params], body)

post 获取酒店详细房型及价格方案

Parameters:
Name Type Argument Description
header YHeader

Http request header

params object <optional>

Http request query string parameters

Properties
Name Type Argument Default Description
mode string <optional>
sync

模式。由于获取所有 rates 可能需要耗费较长时间,为了提升用户体验可以通过异步机制来分批获取首页 rates 和所有 rates

  • sync 同步响应所有数据
  • async 推荐,异步获取所有 rates。同步响应首页 rates 和 asyncJobId,通过 asyncJobId 异步获取所有 rates
  • asyncPaging 推荐,异步获取所有 rates。同步响应首页 rates 和 asyncJobId,通过 asyncJobId 异步获取次页 rates,逐页获取直至 asyncJobId 为空
body object

Http request body

Properties
Name Type Argument Description
preferred Preferred <optional>

偏好设置

stay Stay

入住信息

hotel Hotel

酒店

Since:
  • 1.0.0
Returns:
Type
ratesResponse

<static> search(header [, params], body)

post 搜索酒店及价格

Parameters:
Name Type Argument Description
header YHeader

Http request header

params object <optional>

Http request query string parameters

Properties
Name Type Argument Default Description
mode string <optional>
sync

模式。由于获取价格可能需要耗费较长时间,为了提升用户体验可以通过异步机制来分批获取基础数据和价格

  • sync 同步响应所有数据
  • async 推荐,异步获取价格。同步响应基础数据(不含 minBasePrice、minPrice)和 asyncJobId,通过 asyncJobId 异步获取价格
body object

Http request body

Properties
Name Type Argument Default Description
preferred Preferred <optional>

偏好设置

user User <optional>

预订人

stay Stay

入住信息

filter HotelFilter

筛选条件

  • filter.highCommission=true 时仅返回对本次入住日期命中高佣采样的酒店
sort string <optional>
byRecommendation

排序方式

  • byRecommendation 按系统推荐排序
  • byUserRecommendation 按用户使用记录及系统推荐排序。仅 user 有值时有效
  • byMinBasePrice 按最低单晚价格升序。由于价格是实时向供应商查询,该排序会导致查询性能明显下降
  • byMinBasePriceDescending 按最低单晚价格倒序。由于价格是实时向供应商查询,该排序会导致查询性能明显下降
  • byDistance 按距离远近排序,仅在传入 filter.geospatial 时有效
  • bySearch 按搜索关键字匹配度排序,传入 filter.search 时有效
  • byHotelFilterOrder 按 filter.hotels 中的酒店顺序排序,仅支持使用 _id 筛选酒店
paging Paging <optional>

页码信息,limit 最大 20

Since:
  • 1.0.0
See:
Returns:
Type
searchResponse

Type Definitions


bookResponse

Type:
  • object
Properties:
Name Type Argument Description
err Error <optional>

错误信息,可能的 messageKey

  • invalidTraveler 出行人信息不正确,通常是出行人姓名包含了非英语字符
  • invalidCreditCard 信用卡信息不正确,通常是有效期年月格式不正确,或者卡号不正确
  • invalidPriceDetail 价格不正确,通常是 booking.rate.priceDetail 不正确。(默认不校验,如需校验请联系开通,并在 book 请求中设置 booking.rateRule.key )
  • invalidRate 价格方案不正确,通常是价格已经变动,需要重新获取价格方案。(默认不校验,如需校验请联系开通,并在 book 请求中设置 booking.rateRule.key )
order Order

订单

Since:
  • 1.0.0

HotelRateCalendarDay

Type:
  • object
Properties:
Name Type Argument Description
checkIn string

入住日期,YYYY-MM-DD;每项对应入住一晚

lowest HotelRate <optional>

当天最低价,仅包含 code、name、nameEn、price、priceDetail;无可用价格时为空

Since:
  • 1.0.0

HotelRateCalendarResponse

Type:
  • object
Properties:
Name Type Argument Description
err Error <optional>

错误信息

results Array.<HotelRateCalendarDay>

按日期排序的价格日历;无可用价格的日期仍返回 checkIn

Since:
  • 1.0.0

rateRuleResponse

Type:
  • object
Properties:
Name Type Argument Description
err Error <optional>

错误信息

rate HotelRate

价格方案,仅包含 price, priceDetail 节点。此时的数据相较 rates 接口返回的数据更准确。

rateRule HotelRateRule

价格方案规则

Since:
  • 1.0.0

ratesResponse

Type:
  • object
Properties:
Name Type Argument Description
err Error <optional>

错误信息

rooms Array.<HotelRoom>

房型

asyncJobId string <optional>

异步任务 id。为空时表示没有更多 rates 需要通过异步获取

Since:
  • 1.0.0

searchResponse

Type:
  • object
Properties:
Name Type Argument Description
err Error <optional>

错误信息

paging Paging

页码信息

hotels Array.<Hotel>

酒店

asyncJobId string <optional>

异步任务 id

Since:
  • 1.0.0