<!-- mipuyun-api-doc: shopping-select -->
# shopping/select - 验价/确定航班

# 确定航班（shopping/select）API 说明文档

## 用户使用场景

> 本接口目的是：
> 验价：可满足8秒内响应，>95%成功率。
> 进一步获取免费行李/退改规则信息（对于无法再shopping/search获取的航司场景）

## 错误场景(不应该使用本接口的场景)

> 如航司在点选行程后占位，本接口需谨慎使用，防止航司侧异常。

## 性能指标

> - 响应速度：95%的请求<8秒。
> - 请求频率QPS：根据你的商务合同确定
> - 接口成功率：>95%

## 请求说明

| **请求地址** | https://${endpoint}/shopping/select |
| --- | --- |
| **请求方法** | 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": [
  ]
}
```

| **参数名称** | **类型** | **是否必选** | **示例值(默认值)** | **说明** |
| --- | --- | --- | --- | --- |
| 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 | 否 | - | 异步模式下的业务回调标识，用于客户自行匹配业务。建议格式：`select_{origin}_{destination}_{departureDate}_{adults}-{children}-{infants}_{flightNumber}`，最大 50 个字符 |

## 返回参数

探索一个返回参数json（同shopping/search），https://jsonhero.io/j/XmTLWK94Ae5X

| 参数名称 | 类型 | 示例值 | 说明 |
| --- | --- | --- | --- |
| itineraries | Array<Itinerary> | - | 航线组合列表，包含不同航班拼接的行程方案 |
| baggageList |  |  |  |
|  |  |  |  |
| code | Integer | 0 | 系统状态码：0 = 成功，非 0 为失败 |
| msg | String | null | 系统消息：成功时为 null，失败时返回具体系统提示信息 |
| sessionId | String | 66d807b0-abbc-4b57-aeff-bbf4fc29fb75 | UUID: 与航司通信的session值，可以用于加速后续动作，如继续获取包裹，选座，下单。 |

### 异步模式响应（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 回调返回。

## 响应实体介绍

### 响应示例

```json
{
  "code": 0,
  "msg": null,
  "sessionId": "66d807b0-abbc-4b57-aeff-bbf4fc29fb75",
  "itineraries": [
    {
      "outboundSegments": [
        {
          "index": 1,
          "carrier": "SL",
          "flightNumber": "SL557",
          "operatingCarrier": "",
          "operatingFlightnumber": "",
          "originAirport": "PHS",
          "destinationAirport": "DMK",
          "departureTime": "202511190800",
          "arrivalTime": "202511191130",
          "departureTerminal": "",
          "arrivalTerminal": "",
          "stopCities": "",
          "duration": 210,
          "aircraftCode": "320",
          "codeShare": false
        }
      ],
      "inboundSegments": [],
      "fares": [
        {
          "fareBasis": "",
          "rtnFareBasis": "",
          "fareFamily": "promo",
          "rtnFareFamily": "",
          "currency": "USD",
          "adultFare": 80.00,
          "adultTax": 30.00,
          "bookingCode": "Y",
          "availableSeats": 9,
          "flightPolicy": {
            "airlineCode": "SL",
            "fareFamilyType": "promo",
            "freeAncillaryList": [
              { "categoryCode": "CabinBaggageOverheadLocker", "segmentIndex": 1, "paxType": "ADT", "piece": 1, "weight": 7, "size": "" },
              { "categoryCode": "StandardCheckedBaggage", "segmentIndex": 1, "paxType": "ADT", "piece": 0, "weight": 0 }
            ]
          }
        }
      ]
    }
  ],
  "baggageList": []
}
```

> **提示**：`itineraries` 数组中的每个元素是一个完整的行程方案，详见 [Itinerary 实体定义](08-01_itinerary.md)

# 常见问题

## 航司不稳定的时候，如何保障成功率>95%

我们支持多个通过proxy入参实现并发请求。

**案例1：竖线分隔，随机挑选**

proxy= myproxy-us|myproxy-uk

行为：随机从myproxy-us中挑选一个

**案例2：加号分隔**

proxy= myproxy-us+myproxy-uk

行为：启动两个进程对数据源(航司)做并发访问，确保成功率。

**案例3：组合**

proxy= myproxy1-us|myproxy2-au+myproxy1-uk|myproxy2-de

行为：随机挑选myproxy1|myproxy2的代理，并启动两个进程对数据源做并发访问。

## 如果航司侧响应大于8秒，这个请求会被抛弃吗？

不会，为了兼容异常场景，该接口我们最大等待航司响应的时长为15秒。