mipu-open/docs/03-02_shopping-select.md

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

请求体

{
  "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
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	否	-	异步模式下的业务回调标识，用于客户自行匹配业务。建议格式：select_{origin}_{destination}_{departureDate}_{adults}-{children}-{infants}_{flightNumber}，最大 50 个字符

返回参数

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

参数名称	类型	示例值	说明
itineraries	Array	-	航线组合列表，包含不同航班拼接的行程方案
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 回调返回。

响应实体介绍

响应示例

{
  "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 实体定义

常见问题

航司不稳定的时候，如何保障成功率>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秒。