Module: cruise

邮轮航线查询、舱房选择与预订。静态/低频变化的基础信息见 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

CruiseBooking
CruiseCabin
CruiseFare
CruiseItinerary
CruiseItineraryFilter

Methods


<static> book(header, body)

post 使用报价和授信完成邮轮下单。

Parameters:
Name Type Description
header module:request.YHeader

Http request header

body object

Http request body

Properties
Name Type Argument Description
preferred module:common.Preferred <optional>

首选设置,名称和描述按 preferred.language 返回

priceId string

cruise/price 返回的报价识别码

travelers Array.<module:common.Contact>

必须与报价时一致

cabinNo string

舱房号

dining string <optional>

餐食

diningStartTime string <optional>

餐食时间

contact module:common.Contact <optional>

联系人

Since:
  • 1.0.0
Returns:
Type
Order

<static> cabin/availability(header, body)

post 查询指定舱型的可用舱房。

Parameters:
Name Type Description
header module:request.YHeader

Http request header

body object

Http request body

Properties
Name Type Argument Description
itineraryId string

行程识别码

categoryCode string

舱型编码

guest module:common.Guest <optional>

入住人数,字段名和结构与 Stay.guest 一致;未传时按供应商默认人数查询

Since:
  • 1.0.0
Returns:
Type
availabilityResponse

<static> cabin/diningOptions(header, body)

post 查询餐食时段。

Parameters:
Name Type Description
header module:request.YHeader

Http request header

body object

Http request body

Properties
Name Type Argument Description
itineraryId string

行程识别码

guest module:common.Guest <optional>

入住人数

Since:
  • 1.0.0
Returns:
Type
diningOptionsResponse

<static> cabin/hold(header, body)

post 锁定舱房,锁定默认 5 分钟有效。

Parameters:
Name Type Description
header module:request.YHeader

Http request header

body object

Http request body

Properties
Name Type Description
itineraryId string

行程识别码

categoryCode string

舱型编码

cabinNo string

舱房号

guest module:common.Guest

入住人数;必须传入,供应商占舱需要根据成人和儿童人数锁定舱房

Since:
  • 1.0.0
Returns:
Type
holdResponse

<static> cabin/release(header, body)

post 释放尚未关联订单的指定锁舱;省略 holdId 时释放当前渠道用户的选房锁。订单持有的锁由订单流程释放。

Parameters:
Name Type Description
header module:request.YHeader

Http request header

body object

Http request body

Properties
Name Type Argument Description
holdId string <optional>

锁舱识别码;省略时释放该渠道用户尚未关联订单的锁舱

Since:
  • 1.0.0
Returns:
Type
releaseResponse

<static> fares(header, body)

post 获取指定行程的票价方案。按船舱位置分组返回舱型与票价,并给出取消政策。 用户下单前展示的价格可直接使用各票价的 price;原币金额及换算明细见 priceDetail

Parameters:
Name Type Description
header module:request.YHeader

Http request header

body object

Http request body

Properties
Name Type Argument Description
preferred module:common.Preferred <optional>

首选设置

itineraryId string

行程识别码,来自 itinerary/search 的 itineraries[].itineraryId,E.g. "DCL-20260415-4N-SIN"

guest module:common.Guest

入住人数,字段名和结构与 Stay.guest 一致

Since:
  • 1.0.0
Returns:
Type
faresResponse

<static> itinerary/filterOptions(header [, body])

post 获取航线筛选项。结果只包含当天及以后的可售数据,并按 preferred.language 返回名称。

Parameters:
Name Type Argument Description
header module:request.YHeader

Http request header

body object <optional>

Http request body

Properties
Name Type Argument Description
preferred module:common.Preferred <optional>

首选设置

filter object <optional>

与搜索条件一致的筛选范围

Properties
Name Type Argument Description
date string <optional>

指定出发日期,YYYY-MM-DD

dateStart string <optional>

出发日期下限,YYYY-MM-DD

dateEnd string <optional>

出发日期上限,YYYY-MM-DD

departurePortCodes Array.<string> <optional>

出发港口编码

shipCodes Array.<string> <optional>

船只编码

durations Array.<number> <optional>

行程天数(晚数)

Since:
  • 1.0.0
Returns:
Type
filterOptionsResponse

<static> itinerary/search(header, body)

post 搜索邮轮行程。同一「船只 + 天数 + 出发港 + 停靠港序列」的多个行程聚合为一条航线,未来行程在 itineraries[] 返回。 只返回当天及以后的行程;查价与下单使用 itineraries[].itineraryId

Parameters:
Name Type Description
header module:request.YHeader

Http request header

body object

Http request body

Properties
Name Type Argument Default Description
preferred module:common.Preferred <optional>

首选设置

itinerary object <optional>

行程条件

Properties
Name Type Argument Description
dateRange Array.<string> <optional>

出发日期范围,YYYY-MM-DD,E.g. ["2026-04-01", "2026-06-30"]

filter module:cruise.CruiseItineraryFilter <optional>

筛选条件

sort string <optional>
byRecommendation

排序方式

  • byRecommendation 系统推荐
  • byPriceAsc 最低价升序
  • byPriceDesc 最低价倒序
  • byDepartureDate 最早出发日期
pagination object <optional>

页码信息

Properties
Name Type Argument Default Description
page number <optional>
1

页码

limit number <optional>
10

每页数量

Since:
  • 1.0.0
Returns:
Type
itinerarySearchResponse

<static> price(header, body)

post 按行程、舱型和旅客信息获取一次性报价。

Parameters:
Name Type Description
header module:request.YHeader

Http request header

body object

Http request body

Properties
Name Type Argument Description
preferred module:common.Preferred <optional>

首选设置,price 按 preferred.currency 换算,名称和描述按 preferred.language 返回

itineraryId string

行程识别码

categoryCode string

舱型编码

fareCode string

票价编码

cabinNo string <optional>

舱房号

travelers Array.<module:common.Contact>

旅客信息

Since:
  • 1.0.0
Returns:
Type
priceResponse

Type Definitions


availabilityResponse

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

错误信息

cabins Array.<module:cruise.CruiseCabin>

可用舱房。舱房号 no 始终为字符串

ship module:cruise/meta.CruiseShip

船只及甲板信息

Since:
  • 1.0.0

diningOptionsResponse

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

错误信息

dinings Array.<object>

可选主餐时段

dinings[].type string

餐食类型,供应商返回的稳定编码

dinings[].startTime string

开始时间,HH:mm,E.g. "17:45"

Since:
  • 1.0.0

filterOptionsResponse

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

错误信息

ports Array.<object>

出发港口选项

ports[].code string

港口编码

ports[].name string

本地化名称

dates Array.<string>

可用出发日期,YYYY-MM-DD

durations Array.<number>

可用行程天数(晚数)

ships Array.<module:cruise/meta.CruiseShip>

可用船只选项

Since:
  • 1.0.0

holdResponse

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

错误信息

holdId string

锁舱识别码

expiresAt string

锁舱失效时间,ISO 8601

Since:
  • 1.0.0

itinerarySearchResponse

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

错误信息

itineraries Array.<object>

聚合后的航线;同一船只、天数、出发港和停靠港序列的行程聚合为一条

itineraries[].name string

名称。E.g. "Singapore to Singapore"

itineraries[].duration number <optional>

行程天数(晚数),E.g. 4

itineraries[].departurePort string <optional>

出发港口编码,枚举参考 CruisePort.code

itineraries[].ship module:cruise/meta.CruiseShip <optional>

船只

itineraries[].brand module:common.Brand <optional>

品牌

itineraries[].stops Array.<object> <optional>

停靠港序列;日期取代表行程

itineraries[].stops[].dayIndex number

第几天,从 1 开始,E.g. 1

itineraries[].stops[].date string

日期,YYYY-MM-DD,E.g. "2026-04-15"

itineraries[].stops[].time string <optional>

离港时间,HH:mm,兼容字段

itineraries[].stops[].boardingTime string <optional>

登船时间,HH:mm,E.g. "16:00"

itineraries[].stops[].departureTime string <optional>

离港时间,HH:mm,E.g. "17:00"

itineraries[].stops[].arrivalTime string <optional>

抵港时间,HH:mm,E.g. "07:00"

itineraries[].stops[].port object

港口

Properties
Name Type Description
code string

港口编码,枚举参考 CruisePort.code

name string

港口名称

itineraries[].stops[].remark string <optional>

备注

itineraries[].minPrice object <optional>

按 preferred.currency 换算后的航线最低价(取该航线已算过价的最低行程)

Properties
Name Type Description
amount number

换算后的金额

currency string

换算后的币种

itineraries[].minPriceDetail module:common.PriceDetail <optional>

最低价明细;原币金额和换算金额分别见根节点和 approximate。aggregated.quantity 为 1,表示按一份最低价计算,不表示入住人数

itineraries[].minPriceItineraryId string <optional>

最低价对应行程,客户可直接引导到该行程

itineraries[].itineraries Array.<module:cruise.CruiseItinerary>

该航线下的行程(仅未来行程)

pagination object

页码信息

Properties
Name Type Description
total number

总数

page number

页码

limit number

每页数量

pages number

总页数

Since:
  • 1.0.0

priceResponse

邮轮报价结果。priceId 只属于当前渠道与报价用户,并在有效期内使用一次。

Type:
  • object
Properties:
Name Type Description
priceId string

报价识别码

expiresAt string

报价失效时间,ISO 8601

price object

按 preferred.currency 换算后的总价

Properties
Name Type Description
amount number

换算后的总金额,与 priceDetail.aggregated.approximate.sum 一致

currency string

换算后的币种

priceDetail module:common.PriceDetail

计算后的总价明细;供应商 USD 总价见 aggregated.sum/currency,换算总价见 aggregated.approximate.sum。aggregated.quantity 为 1,表示按一份总价计算,不表示旅客人数

bookingPrice module:common.PriceDetail

预订价格明细;amount/currency 与 breakdown[] 为供应商 USD,approximate.amount/currency 按 preferred.currency 换算,breakdown[].approximate.amount 为各费用项的换算金额。各项独立四舍五入,合计可能存在尾差

Properties
Name Type Argument Description
refundPolicy string <optional>

退款政策原文

paymentSchedule Array.<object> <optional>

付款计划,字段随供应商变化

guestPrices Array.<module:common.PriceDetail>

每位旅客的价格明细;amount/currency 与 breakdown[] 为供应商 USD,approximate.amount/currency 按 preferred.currency 换算,breakdown[].approximate.amount 为各费用项的换算金额。各项独立四舍五入,合计可能与 price.amount 存在尾差

ship module:cruise/meta.CruiseShip

船只

Since:
  • 1.0.0

releaseResponse

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

错误信息

released boolean

是否已处理

Since:
  • 1.0.0

faresResponse

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

错误信息

itinerary module:cruise.CruiseItinerary

行程

ship module:cruise/meta.CruiseShip

船只

cabinGroups Array.<object>

按船舱位置分组的舱型与票价

cabinGroups[].code string

船舱位置编码,枚举参考 CruiseLocation.code

cabinGroups[].name string

名称

cabinGroups[].nameEn string

英文名称

cabinGroups[].rooms Array.<module:cruise/meta.CruiseCabinType>

舱型

Since:
  • 1.0.0