mipu-open/docs/03-03_shopping-baggage.md

shopping/baggage - 行李报价

用户使用场景

获取行程可支持的收费行李规格，以及各个规格的行李价格

性能指标

• 通过sessionId访问，或者sessionId有效，响应时间<8秒。

请求说明

请求地址	https://${endpoint}/shopping/baggage
请求方法	POST
注意事项	Header必须带压缩请求。

请求参数

Header

参数名称	类型	是否必选	示例值	说明
Content-Type	String	是	application/json	固定值，指定请求体格式为 JSON
Accept-Encoding	String	是	gzip, deflate, br	必须要填写，否则服务器会拒绝。
client-key	String	是	xxxxx	联系我们获取生产环境key
client-secret	String	是	xxxxx	联系我们获取生产环境secret

请求体

{
  "sessionId": "66d807b0-abbc-4b57-aeff-bbf4fc29fb75",
  "journeyType": "OW",
  "origin": "MIL",
  "destination": "CAG",
  "departureDate": "20251118",
  "adults": 1,
  "children": 0,
  "infants": 0,
  "agent": "u2web",
  "proxy": "myproxy-us",
  "outboundFareFamily": "promo",
  "inboundFareFamily": "",
  "outboundSegments": [
    {
      "carrier": "SL",
      "originAirport": "PHS",
      "destinationAirport": "DMK",
      "flightNumber": "SL557",
      "departureDate": "20251119"
    }
  ],
  "inboundSegments": [
  ]
}

注意：本接口的请求参数与 shopping/select 完全一致，详细的参数说明请参考 shopping/select 文档。

参数名称	类型	是否必选	示例值(默认值)	说明
sessionId	String	否	66d807b0-abbc-4b57-aeff-bbf4fc29fb75	目的是为了复用前一步的shopping/search的session，提升速度&成功率。如带入session，请务必保障：1. 出发到达/旅行日期/人数与前一步保持一致。
journeyType	String	是	"OW"	行程为单程还是往返程OW：单程OneWayRT：往返RoundTrip
origin	String	是	"CJJ"	出发地，为IATA 3字码兼容城市或者机场3字码
destination	String	是	"SHA"	到达地，为IATA3字码兼容城市或者机场3字码
departureDate	String	是	20240326	出发日期，格式为 YYYYMMDD（如 2024 年 5 月 1 日为 20240501）
returnDate	String	否	20240423（仅 RT 必填）	返程日期，格式同 departureDate，仅当 journeyType=RT 时必传，OW 时可传空
adults	Integer	是	2	成人，乘机人数量
children	Integer	是	1	儿童，乘机人数量
infants	Integer	是	0	婴儿，乘机人数量
outboundSegments	Array	是		去程航段信息，详见 FlightSegmentRequest
inboundSegments	Array	否		返程航段信息往返行程为必须，详见 FlightSegmentRequest
outboundFareFamily	String	是		去程FareFamily的名字
inboundFareFamily	String	否		回程FareFamily的名字仅往返程有值
agent	String	是	"u2web"	你自行定义的执行器编码（Agent Code）
proxy	String	是		本次获取航司数据采用的代理方式。如果需要指定代理国家请在代理用户后面加上国家二字码。如myproxy-USUS代表美国
acceptCacheMinutes	Integer	否	5	默认值：5**如无特殊情况，本参数不建议设置或调整。**为了避免频繁请求航司设置的缓存，用户可以指定缓存时长，不填写为5。
async	Boolean	是	false	是否启用 Webhook 异步模式。 - false: 同步模式，等待完整结果返回 - true: 异步模式，立即返回 202，结果通过 Webhook 回调 异步模式说明： 1. 系统会同步检查是否有新鲜缓存（acceptCacheMinutes），如有则立即返回 2. 无缓存时返回 202 Accepted，包含 requestId 用于追踪 3. 航司数据返回后，通过预先配置的 Webhook 回调通知 注意：使用异步模式需提前配置 shopping_response 类型的 Webhook
callbackId	String	否	-	异步模式下的业务回调标识，用于客户自行匹配业务。建议格式：baggage_{origin}_{destination}_{departureDate}_{adults}-{children}-{infants}_{flightNumber}，最大 50 个字符

参数一致性说明：本接口的所有请求参数（Header 和 请求体）与 shopping/select 完全相同。如果您已经熟悉 shopping/select 接口，可以直接使用相同的参数格式调用本接口。

返回参数

参数名称	类型	示例值	说明
code	Integer	0	系统状态码：0 = 成功，非 0 为失败
msg	String	null	系统消息：成功时为 null，失败时返回具体系统提示信息
sessionId	String	66d807b0-abbc-4b57-aeff-bbf4fc29fb75	UUID: 与航司通信的session值，可以用于加速后续动作，如继续获取包裹，选座，下单。
itineraries	Array<Itinerary>	-	航线组合列表。由于在本接口已确定路线和FareFamily，数组长度 ≤ 1
ancillaries	Array<AncillaryGroup>	{json实体}	辅营产品分组列表（新结构，三级嵌套）
ancillaryList	Array	{json实体}	(兼容旧结构) 当 ancillaries 为空时可能存在，建议优先使用 ancillaries

异步模式响应（async=true）

当 async=true 且无可用缓存时，系统立即返回 202 Accepted：

参数名称	类型	说明
code	Integer	202（表示请求已接受，正在处理中）
msg	String	"Accepted. Please wait for the webhook callback"
requestId	String	请求ID（UUID），用于追踪和关联 Webhook 回调
status	String	"PROCESSING"（处理中）

完整结果将通过预先配置的 Webhook 回调返回。

---

响应实体介绍

响应采用三级嵌套结构：AncillaryGroup → AncillaryCategory → BaggageOption

ancillaries (Array)
  └─ AncillaryGroup          ← 按航程方向 + 运价家族分组
       └─ categoryList (Array)
            └─ AncillaryCategory   ← 按行李类别分组
                 └─ categoryDetail (Array)
                      └─ BaggageOption  ← 具体行李选项及价格

AncillaryGroup（最外层）

字段名	类型	说明
currency	String	售价币种（ISO 4217），如 CAD、EUR、USD
fareFamilyType	String	运价家族类型，如 BASIC、SMART、PROMO
journeyDirection	String	航程方向：outbound（去程）/ inbound（回程）
categoryList	Array<AncillaryCategory>	辅营类别列表

AncillaryCategory（中间层）

字段名	类型	说明
categoryCode	String	类别代码，见 categoryCode 说明
maxPieces	String	该类别最多可购买件数
pricingMode	String	定价模式，见 pricingMode 说明
categoryDetail	Array<BaggageOption>	选项列表

BaggageOption（最内层）

字段名	类型	说明
pieceNo	Integer	第 N 件。STEP 模式下为序号（1, 2, 3...），FLAT/TIERED 模式下为 1
weight	BigDecimal	行李额重量（KG）
size	String	尺寸限制，如 "55x40x23cm"
price	BigDecimal	该选项/该件价格
maxPieces	Integer	该选项可购买数量

---

响应示例

示例1：FLAT + STEP 混合

{
  "code": 0,
  "msg": null,
  "sessionId": "NYW34327-f212fbacdd054dda8a509e846e300ebf",
  "itineraries": [],
  "ancillaries": [
    {
      "currency": "CAD",
      "fareFamilyType": "BASIC",
      "journeyDirection": "outbound",
      "categoryList": [
        {
          "categoryCode": "CabinBaggageOverheadLocker",
          "maxPieces": "1",
          "pricingMode": "FLAT",
          "categoryDetail": [
            { "pieceNo": 1, "weight": 10, "size": "55x40x23cm", "price": 39.00, "maxPieces": 1 },
            { "pieceNo": 1, "weight": 23, "size": "55x40x23cm", "price": 64.00, "maxPieces": 1 }
          ]
        },
        {
          "categoryCode": "StandardCheckedBaggage",
          "maxPieces": "5",
          "pricingMode": "STEP",
          "categoryDetail": [
            { "pieceNo": 1, "weight": 10, "size": "", "price": 39.00, "maxPieces": 1 },
            { "pieceNo": 1, "weight": 23, "size": "", "price": 64.00, "maxPieces": 1 },
            { "pieceNo": 2, "weight": 23, "size": "", "price": 64.00, "maxPieces": 1 },
            { "pieceNo": 3, "weight": 23, "size": "", "price": 99.00, "maxPieces": 1 }
          ]
        }
      ]
    },
    {
      "currency": "CAD",
      "fareFamilyType": "BASIC",
      "journeyDirection": "inbound",
      "categoryList": [
        {
          "categoryCode": "CabinBaggageOverheadLocker",
          "maxPieces": "1",
          "pricingMode": "FLAT",
          "categoryDetail": [
            { "pieceNo": 1, "weight": 10, "size": "55x40x23cm", "price": 35.00, "maxPieces": 1 }
          ]
        }
      ]
    }
  ]
}

示例2：TIERED 模式（按重量档位）

{
  "code": 0,
  "msg": null,
  "sessionId": "...",
  "ancillaries": [
    {
      "currency": "CNY",
      "fareFamilyType": "ECONOMY",
      "journeyDirection": "outbound",
      "categoryList": [
        {
          "categoryCode": "StandardCheckedBaggage",
          "maxPieces": "1",
          "pricingMode": "TIERED",
          "categoryDetail": [
            { "pieceNo": 1, "weight": 20, "size": "", "price": 300.00, "maxPieces": 1 },
            { "pieceNo": 1, "weight": 25, "size": "", "price": 500.00, "maxPieces": 1 },
            { "pieceNo": 1, "weight": 30, "size": "", "price": 800.00, "maxPieces": 1 }
          ]
        }
      ]
    }
  ]
}

---

categoryCode 说明

categoryCode	说明
CabinBaggageOverheadLocker	手提行李（头顶行李架）
CabinBaggageUnderSeat	手提行李（座椅下）
StandardCheckedBaggage	托运行李

pricingMode 说明

pricingMode	说明	渲染建议
FLAT	固定单价，每件独立产品	卡片网格展示，每个选项一张卡片
STEP	逐件定价，第 N 件对应不同价格	表格展示，按 pieceNo 分组，同 pieceNo 行用背景色合并
TIERED	按总重量档位选择，不计件	单选列表展示，互斥选项

提示：

• ancillaries 数组按 journeyDirection（outbound/inbound）和 fareFamilyType 分组
• 优先使用 ancillaries（新三级结构），ancillaryList 为兼容旧结构
• 同一 pricingMode 内，categoryDetail 按 pieceNo 升序排列
• STEP 模式下，相同 pieceNo 可能有多个重量/价格选项（如第 1 件可选 10kg 或 23kg）