b450b512a2
- 添加 mipu-api 作为 git submodule (Claude Code Skill) - 迁移 API 文档源文件到 docs/ 目录统一维护 - 添加 Gitea Actions 工作流：tag推送自动打包docs并发布Release - Skill 运行时自动从 mipu-open Release 下载最新文档 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
265 lines
11 KiB
Markdown
265 lines
11 KiB
Markdown
<!-- mipuyun-api-doc: shopping-baggage -->
|
||
# 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 |
|
||
|
||
###
|
||
|
||
### 请求体
|
||
|
||
```json
|
||
{
|
||
"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](03-02_shopping-select.md) 完全一致，详细的参数说明请参考 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> | 是 | | 去程航段信息，详见 [FlightSegmentRequest](07-01_flight-segment-request.md) |
|
||
| inboundSegments | Array<FlightSegmentRequest> | 否 | | 返程航段信息往返行程为必须，详见 [FlightSegmentRequest](07-01_flight-segment-request.md) |
|
||
| outboundFareFamily | String | 是 | | 去程FareFamily的名字 |
|
||
| inboundFareFamily | String | 否 | | 回程FareFamily的名字仅往返程有值 |
|
||
| agent | String | 是 | "u2web" | 你自行定义的执行器编码（Agent Code） |
|
||
| proxy | String | 是 | | 本次获取航司数据采用的代理方式。如果需要指定代理国家请在代理用户后面加上国家二字码。如myproxy-USUS代表美国 |
|
||
| acceptCacheMinutes | Integer | 否 | 5 | 默认值：5**如无特殊情况，本参数不建议设置或调整。**为了避免频繁请求航司设置的缓存，用户可以指定缓存时长，不填写为5。 |
|
||
| async | Boolean | 是 | false | 是否启用 Webhook 异步模式。<br>- **false**: 同步模式，等待完整结果返回<br>- **true**: 异步模式，立即返回 202，结果通过 Webhook 回调<br><br>**异步模式说明**：<br>1. 系统会同步检查是否有新鲜缓存（acceptCacheMinutes），如有则立即返回<br>2. 无缓存时返回 202 Accepted，包含 requestId 用于追踪<br>3. 航司数据返回后，通过预先配置的 Webhook 回调通知<br><br>**注意**：使用异步模式需提前配置 `shopping_response` 类型的 Webhook |
|
||
| callbackId | String | 否 | - | 异步模式下的业务回调标识，用于客户自行匹配业务。建议格式：`baggage_{origin}_{destination}_{departureDate}_{adults}-{children}-{infants}_{flightNumber}`，最大 50 个字符 |
|
||
|
||
> **参数一致性说明**：本接口的所有请求参数（Header 和 请求体）与 [shopping/select](03-02_shopping-select.md) 完全相同。如果您已经熟悉 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](#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)\> | 辅营类别列表 |
|
||
|
||
### AncillaryCategory（中间层）
|
||
|
||
| 字段名 | 类型 | 说明 |
|
||
|--------|------|------|
|
||
| categoryCode | String | 类别代码，见 [categoryCode 说明](#categorycode-说明) |
|
||
| maxPieces | String | 该类别最多可购买件数 |
|
||
| pricingMode | String | 定价模式，见 [pricingMode 说明](#pricingmode-说明) |
|
||
| categoryDetail | Array\<[BaggageOption](#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 混合
|
||
|
||
```json
|
||
{
|
||
"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 模式（按重量档位）
|
||
|
||
```json
|
||
{
|
||
"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）
|