邮轮预订流程
邮轮预订使用 Open API v2。渠道客户端负责行程、舱房和旅客信息的交互,渠道服务端负责请求签名和订单处理。以下接口均为 POST,省略环境域名和版本前缀。
sequenceDiagram
accTitle: 邮轮预订流程
accDescr: 查询邮轮行程和票价,选择并锁定舱房,填写旅客信息获取报价,确认后授信下单;放弃时释放锁舱。
autonumber
box rgb(235, 247, 243) 渠道方
participant C as 渠道客户端
participant S as 渠道服务端
end
box rgb(255, 246, 229) YSystem
participant Y as YSystem 服务端
end
C->>S: 查询行程(日期、目的地等)
S->>Y: /cruise/itinerary/search
Y-->>S: 行程列表(itineraryId)
S-->>C: 展示行程
C->>S: 选择行程,设置出行人数
S->>Y: /cruise/fares
Y-->>S: 舱型、票价方案及取消政策
S-->>C: 展示舱型与票价
C->>S: 选择舱型和票价方案
S->>Y: /cruise/cabin/availability
Y-->>S: 可选舱房
S-->>C: 展示舱房
C->>S: 选择舱房(cabinNo)
S->>Y: /cruise/cabin/hold
Y-->>S: holdId、expiresAt
S-->>C: 提示锁舱有效期,填写旅客信息
C->>S: 提交旅客信息
S->>Y: /cruise/price
Y-->>S: priceId、expiresAt、价格明细
S->>Y: /cruise/cabin/diningOptions
Y-->>S: 可选用餐安排
S-->>C: 展示报价、条款和用餐选项
alt 用户确认预订
C->>S: 确认价格、旅客及用餐安排
S->>Y: /cruise/book(priceId、travelers、cabinNo)
Y->>Y: 校验报价与旅客,创建订单并使用渠道授信
Y-->>S: 订单或业务错误
S-->>C: 展示订单状态或失败原因
opt 订单仍待确认
S->>Y: /order/search
Y-->>S: 最新订单与预订结果
S-->>C: 更新预订状态
end
else 用户放弃或更换舱房
C->>S: 取消当前选择
S->>Y: /cruise/cabin/release(holdId)
Y-->>S: 释放结果
S-->>C: 更新舱房选择状态
end
接入要点
/cruise/itinerary/search的itineraries[].stops[]在供应商提供时返回boardingTime(登船)、departureTime(离港)和arrivalTime(抵港),格式均为HH:mm;未提供的时间字段不返回。原有time是离港时间的兼容字段。stops[]的日期取航线代表行程。/cruise/fares返回舱型与票价方案,使用选中的categoryCode、fareCode继续查询和报价;下单前展示/cruise/price返回的价格明细。- 邮轮的
minPriceDetail和priceDetail中,aggregated.quantity为1,表示按一份总价计算,不是入住人数。fares按请求的guest(成人数和儿童数)查询票价;price按travelers报价。展示总价使用对应的minPrice、fare.price或price。 price返回的guestPrices[]保留每位旅客的供应商 USD 金额和breakdown[],同时在approximate、breakdown[].approximate中提供按preferred.currency换算的金额。各金额独立四舍五入,旅客换算价之和可能与总价price.amount存在尾差;订单总价以price.amount为准。- 锁舱和报价各有有效期,以各自返回的
expiresAt为准。锁舱到期后应重新检查舱房可用性;报价到期后必须重新报价并让用户确认。 priceId仅限当前渠道和报价用户使用,且只能用于一次下单。下单时的travelers必须与报价时一致,修改旅客信息后需重新报价。- Open API 邮轮下单使用渠道的邮轮授信,需提前开通并确保额度可用。返回订单不代表供应商已确认,应检查订单状态及预订结果。
- 放弃预订或更换舱房时,使用具体的
holdId释放原锁舱。锁舱只是临时保留舱位,不等于已创建订单。 - 请求签名由渠道服务端完成,见 请求认证与签名。
旅客字段填写
/cruise/price 的 travelers 为旅客数组,每位旅客填写各自的真实信息;/cruise/book 应回传与报价时一致的旅客信息。以下为单个旅客的字段示例,完整请求还需提供 itineraryId、categoryCode、fareCode 等参数:
{
"firstName": "三",
"lastName": "张",
"firstNameEn": "SAN",
"lastNameEn": "ZHANG",
"gender": "M",
"birthday": "1989-01-01",
"nationality": "CN",
"telephoneCountryCode": "86",
"telephone": "13800000000",
"email": "traveler@example.com"
}
firstNameEn是英文名,lastNameEn是英文姓,分别对应firstName和lastName;gender使用M或F。birthday严格按YYYY-MM-DD(推荐)或YYYYMMDD传入,月、日均需补零;1989-1-1无效。nationality使用 ISO 3166-1 alpha-2 两位国籍代码,如中国为CN,不可传1或中国。nationalityName是订单响应中的展示字段,不能代替请求里的nationality。telephoneCountryCode是电话国家区号,如中国大陆为86;0514等城市区号不能用于此字段。- 收到
CRUISE_TRAVELER_INVALID时,检查英文姓名、性别和国籍是否缺失,并检查生日格式;当前错误文案不会指出具体字段。国籍代码和电话国家区号也应按上述规则填写,以免后续报价或预订失败。
可通过 邮轮 API Demo 体验流程;完整字段见 v2 邮轮接口。