邮轮航线查询、舱房选择与预订。静态/低频变化的基础信息见 module:cruise/meta。
本模块统一收录 itinerary/* 航线接口、cabin/* 舱房接口,以及 fares、price、book 票价与预订接口。
命名沿用既有 open api 惯例:<resource>/<action>,action 为动词(search/book)或业务名词(fares/meta);
不使用 create/update 这类 CRUD 词。模型定义见 module:cruise.CruiseItinerary、module:cruise.CruiseFare 等。
Classes
Methods
-
<static> book(header, body)
-
post使用报价和授信完成邮轮下单。Parameters:
Name Type Description headermodule:request.YHeader Http request header
bodyobject Http request body
Properties
Name Type Argument Description preferredmodule:common.Preferred <optional>
首选设置,名称和描述按 preferred.language 返回
priceIdstring cruise/price返回的报价识别码travelersArray.<module:common.Contact> 必须与报价时一致
cabinNostring 舱房号
diningstring <optional>
餐食
diningStartTimestring <optional>
餐食时间
contactmodule:common.Contact <optional>
联系人
- Since:
-
- 1.0.0
Returns:
- Type
- Order
-
<static> cabin/availability(header, body)
-
post查询指定舱型的可用舱房。Parameters:
Name Type Description headermodule:request.YHeader Http request header
bodyobject Http request body
Properties
Name Type Argument Description itineraryIdstring 行程识别码
categoryCodestring 舱型编码
guestmodule:common.Guest <optional>
入住人数,字段名和结构与
Stay.guest一致;未传时按供应商默认人数查询- Since:
-
- 1.0.0
Returns:
- Type
- availabilityResponse
-
<static> cabin/diningOptions(header, body)
-
post查询餐食时段。Parameters:
Name Type Description headermodule:request.YHeader Http request header
bodyobject Http request body
Properties
Name Type Argument Description itineraryIdstring 行程识别码
guestmodule:common.Guest <optional>
入住人数
- Since:
-
- 1.0.0
Returns:
- Type
- diningOptionsResponse
-
<static> cabin/hold(header, body)
-
post锁定舱房,锁定默认 5 分钟有效。Parameters:
Name Type Description headermodule:request.YHeader Http request header
bodyobject Http request body
Properties
Name Type Description itineraryIdstring 行程识别码
categoryCodestring 舱型编码
cabinNostring 舱房号
guestmodule:common.Guest 入住人数;必须传入,供应商占舱需要根据成人和儿童人数锁定舱房
- Since:
-
- 1.0.0
Returns:
- Type
- holdResponse
-
<static> cabin/release(header, body)
-
post释放尚未关联订单的指定锁舱;省略 holdId 时释放当前渠道用户的选房锁。订单持有的锁由订单流程释放。Parameters:
Name Type Description headermodule:request.YHeader Http request header
bodyobject Http request body
Properties
Name Type Argument Description holdIdstring <optional>
锁舱识别码;省略时释放该渠道用户尚未关联订单的锁舱
- Since:
-
- 1.0.0
Returns:
- Type
- releaseResponse
-
<static> fares(header, body)
-
post获取指定行程的票价方案。按船舱位置分组返回舱型与票价,并给出取消政策。 用户下单前展示的价格可直接使用各票价的price;原币金额及换算明细见priceDetailParameters:
Name Type Description headermodule:request.YHeader Http request header
bodyobject Http request body
Properties
Name Type Argument Description preferredmodule:common.Preferred <optional>
首选设置
itineraryIdstring 行程识别码,来自
itinerary/search的itineraries[].itineraryId,E.g. "DCL-20260415-4N-SIN"guestmodule:common.Guest 入住人数,字段名和结构与
Stay.guest一致- Since:
-
- 1.0.0
Returns:
- Type
- faresResponse
-
<static> itinerary/filterOptions(header [, body])
-
post获取航线筛选项。结果只包含当天及以后的可售数据,并按preferred.language返回名称。Parameters:
Name Type Argument Description headermodule:request.YHeader Http request header
bodyobject <optional>
Http request body
Properties
Name Type Argument Description preferredmodule:common.Preferred <optional>
首选设置
filterobject <optional>
与搜索条件一致的筛选范围
Properties
Name Type Argument Description datestring <optional>
指定出发日期,YYYY-MM-DD
dateStartstring <optional>
出发日期下限,YYYY-MM-DD
dateEndstring <optional>
出发日期上限,YYYY-MM-DD
departurePortCodesArray.<string> <optional>
出发港口编码
shipCodesArray.<string> <optional>
船只编码
durationsArray.<number> <optional>
行程天数(晚数)
- Since:
-
- 1.0.0
Returns:
- Type
- filterOptionsResponse
-
<static> itinerary/search(header, body)
-
post搜索邮轮行程。同一「船只 + 天数 + 出发港 + 停靠港序列」的多个行程聚合为一条航线,未来行程在itineraries[]返回。 只返回当天及以后的行程;查价与下单使用itineraries[].itineraryIdParameters:
Name Type Description headermodule:request.YHeader Http request header
bodyobject Http request body
Properties
Name Type Argument Default Description preferredmodule:common.Preferred <optional>
首选设置
itineraryobject <optional>
行程条件
Properties
Name Type Argument Description dateRangeArray.<string> <optional>
出发日期范围,YYYY-MM-DD,E.g. ["2026-04-01", "2026-06-30"]
filtermodule:cruise.CruiseItineraryFilter <optional>
筛选条件
sortstring <optional>
byRecommendation 排序方式
byRecommendation系统推荐byPriceAsc最低价升序byPriceDesc最低价倒序byDepartureDate最早出发日期
paginationobject <optional>
页码信息
Properties
Name Type Argument Default Description pagenumber <optional>
1 页码
limitnumber <optional>
10 每页数量
- Since:
-
- 1.0.0
Returns:
- Type
- itinerarySearchResponse
-
<static> price(header, body)
-
post按行程、舱型和旅客信息获取一次性报价。Parameters:
Name Type Description headermodule:request.YHeader Http request header
bodyobject Http request body
Properties
Name Type Argument Description preferredmodule:common.Preferred <optional>
首选设置,price 按 preferred.currency 换算,名称和描述按 preferred.language 返回
itineraryIdstring 行程识别码
categoryCodestring 舱型编码
fareCodestring 票价编码
cabinNostring <optional>
舱房号
travelersArray.<module:common.Contact> 旅客信息
- Since:
-
- 1.0.0
Returns:
- Type
- priceResponse
Type Definitions
-
availabilityResponse
-
Type:
- object
- Since:
-
- 1.0.0
Properties:
Name Type Argument Description errmodule:common.Error <optional>
错误信息
cabinsArray.<module:cruise.CruiseCabin> 可用舱房。舱房号
no始终为字符串shipmodule:cruise/meta.CruiseShip 船只及甲板信息
-
diningOptionsResponse
-
Type:
- object
- Since:
-
- 1.0.0
Properties:
Name Type Argument Description errmodule:common.Error <optional>
错误信息
diningsArray.<object> 可选主餐时段
dinings[].typestring 餐食类型,供应商返回的稳定编码
dinings[].startTimestring 开始时间,HH:mm,E.g. "17:45"
-
filterOptionsResponse
-
Type:
- object
- Since:
-
- 1.0.0
Properties:
Name Type Argument Description errmodule:common.Error <optional>
错误信息
portsArray.<object> 出发港口选项
ports[].codestring 港口编码
ports[].namestring 本地化名称
datesArray.<string> 可用出发日期,YYYY-MM-DD
durationsArray.<number> 可用行程天数(晚数)
shipsArray.<module:cruise/meta.CruiseShip> 可用船只选项
-
holdResponse
-
Type:
- object
- Since:
-
- 1.0.0
Properties:
Name Type Argument Description errmodule:common.Error <optional>
错误信息
holdIdstring 锁舱识别码
expiresAtstring 锁舱失效时间,ISO 8601
-
itinerarySearchResponse
-
Type:
- object
- Since:
-
- 1.0.0
Properties:
Name Type Argument Description errmodule:common.Error <optional>
错误信息
itinerariesArray.<object> 聚合后的航线;同一船只、天数、出发港和停靠港序列的行程聚合为一条
itineraries[].namestring 名称。E.g. "Singapore to Singapore"
itineraries[].durationnumber <optional>
行程天数(晚数),E.g. 4
itineraries[].departurePortstring <optional>
出发港口编码,枚举参考 CruisePort.code
itineraries[].shipmodule:cruise/meta.CruiseShip <optional>
船只
itineraries[].brandmodule:common.Brand <optional>
品牌
itineraries[].stopsArray.<object> <optional>
停靠港序列;日期取代表行程
itineraries[].stops[].dayIndexnumber 第几天,从 1 开始,E.g. 1
itineraries[].stops[].datestring 日期,YYYY-MM-DD,E.g. "2026-04-15"
itineraries[].stops[].timestring <optional>
离港时间,HH:mm,兼容字段
itineraries[].stops[].boardingTimestring <optional>
登船时间,HH:mm,E.g. "16:00"
itineraries[].stops[].departureTimestring <optional>
离港时间,HH:mm,E.g. "17:00"
itineraries[].stops[].arrivalTimestring <optional>
抵港时间,HH:mm,E.g. "07:00"
itineraries[].stops[].portobject 港口
Properties
Name Type Description codestring 港口编码,枚举参考 CruisePort.code
namestring 港口名称
itineraries[].stops[].remarkstring <optional>
备注
itineraries[].minPriceobject <optional>
按 preferred.currency 换算后的航线最低价(取该航线已算过价的最低行程)
Properties
Name Type Description amountnumber 换算后的金额
currencystring 换算后的币种
itineraries[].minPriceDetailmodule:common.PriceDetail <optional>
最低价明细;原币金额和换算金额分别见根节点和 approximate。aggregated.quantity 为 1,表示按一份最低价计算,不表示入住人数
itineraries[].minPriceItineraryIdstring <optional>
最低价对应行程,客户可直接引导到该行程
itineraries[].itinerariesArray.<module:cruise.CruiseItinerary> 该航线下的行程(仅未来行程)
paginationobject 页码信息
Properties
Name Type Description totalnumber 总数
pagenumber 页码
limitnumber 每页数量
pagesnumber 总页数
-
priceResponse
-
邮轮报价结果。priceId 只属于当前渠道与报价用户,并在有效期内使用一次。
Type:
- object
- Since:
-
- 1.0.0
Properties:
Name Type Description priceIdstring 报价识别码
expiresAtstring 报价失效时间,ISO 8601
priceobject 按 preferred.currency 换算后的总价
Properties
Name Type Description amountnumber 换算后的总金额,与 priceDetail.aggregated.approximate.sum 一致
currencystring 换算后的币种
priceDetailmodule:common.PriceDetail 计算后的总价明细;供应商 USD 总价见 aggregated.sum/currency,换算总价见 aggregated.approximate.sum。aggregated.quantity 为 1,表示按一份总价计算,不表示旅客人数
bookingPricemodule:common.PriceDetail 预订价格明细;amount/currency 与 breakdown[] 为供应商 USD,approximate.amount/currency 按 preferred.currency 换算,breakdown[].approximate.amount 为各费用项的换算金额。各项独立四舍五入,合计可能存在尾差
Properties
Name Type Argument Description refundPolicystring <optional>
退款政策原文
paymentScheduleArray.<object> <optional>
付款计划,字段随供应商变化
guestPricesArray.<module:common.PriceDetail> 每位旅客的价格明细;amount/currency 与 breakdown[] 为供应商 USD,approximate.amount/currency 按 preferred.currency 换算,breakdown[].approximate.amount 为各费用项的换算金额。各项独立四舍五入,合计可能与 price.amount 存在尾差
shipmodule:cruise/meta.CruiseShip 船只
-
releaseResponse
-
Type:
- object
- Since:
-
- 1.0.0
Properties:
Name Type Argument Description errmodule:common.Error <optional>
错误信息
releasedboolean 是否已处理
-
faresResponse
-
Type:
- object
- Since:
-
- 1.0.0
Properties:
Name Type Argument Description errmodule:common.Error <optional>
错误信息
itinerarymodule:cruise.CruiseItinerary 行程
shipmodule:cruise/meta.CruiseShip 船只
cabinGroupsArray.<object> 按船舱位置分组的舱型与票价
cabinGroups[].codestring 船舱位置编码,枚举参考 CruiseLocation.code
cabinGroups[].namestring 名称
cabinGroups[].nameEnstring 英文名称
cabinGroups[].roomsArray.<module:cruise/meta.CruiseCabinType> 舱型