mipu-open/docs/03-04_shopping-seat.md

shopping/seat - 选座报价

用户使用场景

获取航班座位图信息，包括每个座位的位置、价格、状态（可用/已占）、以及座位特性（靠窗、靠过道、紧急出口等）

性能指标

• 通过 sessionId 访问，或者 sessionId 有效，响应时间 < 10 秒
• 接口成功率：> 90%

请求说明

请求地址	https://${endpoint}/shopping/seat
请求方法	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": "743768c1-8bdc-46ed-a586-94fdbd0ce24a",
  "journeyType": "OW",
  "origin": "OTP",
  "destination": "CAG",
  "departureDate": "20260116",
  "adults": 1,
  "children": 0,
  "infants": 0,
  "agent": "AXZ",
  "proxy": "res_mipu_bookxWdyg-it",
  "outboundFareFamily": "BASIC",
  "inboundFareFamily": "",
  "outboundSegments": [
    {
      "carrier": "XZ",
      "originAirport": "OTP",
      "destinationAirport": "FCO",
      "flightNumber": "XZ3115",
      "departureDate": "20260116"
    },
    {
      "carrier": "XZ",
      "originAirport": "FCO",
      "destinationAirport": "CAG",
      "flightNumber": "XZ2341",
      "departureDate": "20260116"
    }
  ],
  "inboundSegments": []
}

参数名称	类型	是否必选	示例值(默认值)	说明
sessionId	String	否	743768c1-8bdc-46ed-a586-94fdbd0ce24a	目的是为了复用前一步的 shopping/search 或 shopping/select 的 session，提升速度 & 成功率。如带入 session，请务必保障：1. 出发到达/旅行日期/人数与前一步保持一致
journeyType	String	是	"OW"	行程为单程还是往返程 OW：单程 OneWay RT：往返 RoundTrip
origin	String	是	"OTP"	出发地，为 IATA 3 字码兼容城市或者机场 3 字码
destination	String	是	"CAG"	到达地，为 IATA 3 字码兼容城市或者机场 3 字码
departureDate	String	是	20260116	出发日期，格式为 YYYYMMDD（如 2024 年 5 月 1 日为 20240501）
returnDate	String	否	20240423（仅 RT 必填）	返程日期，格式同 departureDate，仅当 journeyType=RT 时必传，OW 时可传空
adults	Integer	是	1	成人，乘机人数量
children	Integer	是	0	儿童，乘机人数量
infants	Integer	是	0	婴儿，乘机人数量
agent	String	是	"AXZ"	Agent 代码
proxy	String	是	"res_mipu_bookxWdyg-it"	本次获取航司数据采用的代理方式。如果需要指定代理国家请在代理用户后面加上国家二字码。如 myproxy-US，US 代表美国
outboundSegments	Array	是	见示例	去程航段信息，详见 FlightSegmentRequest
inboundSegments	Array	否		返程航段信息，往返行程为必须，详见 FlightSegmentRequest
outboundFareFamily	String	是	"BASIC"	去程 FareFamily 的名字
inboundFareFamily	String	否		回程 FareFamily 的名字，仅往返程有值
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	否	-	异步模式下的业务回调标识，用于客户自行匹配业务。建议格式：seat_{origin}_{destination}_{departureDate}_{adults}-{children}-{infants}_{flightNumber}，最大 50 个字符

返回参数

响应示例

{
  "cached": false,
  "code": 0,
  "itineraries": [],
  "msg": "success",
  "seatMapList": [
    {
      "segmentIndex": 1,
      "journeyDirection": "outbound",
      "segment": {
        "flightNumber": "DM200",
        "dptAirport": "AUA",
        "arrAirport": "CUR",
        "departureTime": "202604261100",
        "arrivalTime": "202604261150"
      },
      "cabins": [
        {
          "deck": "main",
          "cabinType": "Business",
          "cabinLayout": {
            "columns": [
              { "designator": "A", "characteristics": "W" },
              { "designator": "C", "characteristics": "A" },
              { "designator": "D", "characteristics": "A" },
              { "designator": "G", "characteristics": "A" },
              { "designator": "J", "characteristics": "W" }
            ],
            "rows": { "first": 1, "last": 8 },
            "exitRowPositions": []
          },
          "rows": [
            {
              "number": 1,
              "seats": [
                {
                  "column": "A",
                  "currency": "EUR",
                  "price": 120.0,
                  "seatCharacteristics": ["W", "L"],
                  "seatStatus": "F"
                }
              ]
            }
          ]
        },
        {
          "deck": "main",
          "cabinType": "Economy",
          "cabinLayout": {
            "columns": [
              { "designator": "A", "characteristics": "W" },
              { "designator": "B", "characteristics": "M" },
              { "designator": "C", "characteristics": "A" },
              { "designator": "D", "characteristics": "A" },
              { "designator": "E", "characteristics": "M" },
              { "designator": "F", "characteristics": "W" }
            ],
            "rows": { "first": 9, "last": 32 },
            "exitRowPositions": [
              { "first": 16, "last": 16 },
              { "first": 17, "last": 17 }
            ]
          },
          "rows": [
            {
              "number": 9,
              "seats": [
                {
                  "column": "A",
                  "currency": "EUR",
                  "price": 21.0,
                  "seatCharacteristics": ["W", "IE", "E", "L"],
                  "seatStatus": "F"
                }
              ]
            }
          ]
        }
      ]
    }
  ],
  "sessionId": "shopping-seat-fa149f406bcd4df9a1a318d230afc422"
}

响应字段说明

参数名称	类型	说明
code	Integer	系统状态码：0 = 成功，非 0 为失败
msg	String	系统消息：成功时为 null，失败时返回具体系统提示信息
cached	Boolean	是否使用缓存数据
sessionId	String	UUID：与航司通信的 session 值，可以用于加速后续动作，如下单
itineraries	Array	航线组合列表（本接口通常为空数组）
seatMapList	Array	座位图列表，按航段返回每个航段的座位信息

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

SeatMap（座位图）对象说明

seatMapList 数组中的每个元素代表一个航段的座位图，结构如下：

字段名	类型	说明
segmentIndex	Integer	航段索引（从 1 开始），对应 outboundSegments 或 inboundSegments 中的位置
journeyDirection	String	行程方向：outbound（去程）/ inbound（返程）
segment	Object	航段信息对象，包含航班号、出发/到达机场和时间
cabins	Array<Cabin>	客舱信息列表，按舱位等级排列（如商务舱在前、经济舱在后）

Segment（航段）对象

字段名	类型	说明
flightNumber	String	航班号，如 "DM200"
dptAirport	String	出发机场 IATA 三字码，如 "AUA"
arrAirport	String	到达机场 IATA 三字码，如 "CUR"
departureTime	String	出发时间，格式 YYYYMMDDHHmm，如 "202604261100"
arrivalTime	String	到达时间，格式 YYYYMMDDHHmm，如 "202604261150"

Cabin（机舱）对象

字段名	类型	说明
deck	String	甲板类型，如 "main" 表示主甲板
cabinType	String	客舱类型，可选值：Economy（经济舱）、Business（商务舱）、FirstClass（头等舱）、PremiumEconomy（高端经济舱）
cabinLayout	Object	机舱布局信息
rows	Array<Row>	座位行列表

CabinLayout（机舱布局）对象

字段名	类型	说明
columns	Array	列信息数组，描述每列的座位特性
rows	Object	行范围，包含 first（起始行号）和 last（结束行号）
exitRowPositions	Array	紧急出口行位置数组，每个对象包含 first 和 last 行号

Column（列）对象

字段名	类型	说明
designator	String	列标识符，如 "A"、"B"、"C" 等
characteristics	String	列特性代码（见座位特性说明）

Row（座位行）对象

字段名	类型	说明
number	Integer	行号
seats	Array	该行的座位列表

Seat（座位）对象

字段名	类型	示值	说明
column	String	"A"	列标识符（A、B、C 等）
seatStatus	String	"F"	座位状态 F：Free（可用） O：Occupied（已占）
seatCharacteristics	Array	["W", "I"]	座位特性数组（见下文座位特性说明）
price	BigDecimal	15.0	座位价格（该座位选座费用）
currency	String	"EUR"	价格币种

座位特性说明

seatCharacteristics 数组中的特性代码：

代码	英文	中文说明
W	Window	靠窗座位
A	Aisle	靠过道座位
M	Middle	中间座位
I	Standard	标准座位
IE	ExitRow	紧急出口排
E	ExtraLegroom	额外腿部空间
L	LimitedRecline	有限后倾

常见问题

如何理解 seatMapList 的结构？

每个航段（Segment）都有一个独立的座位图，每个座位图可包含多个舱位（cabins）。例如：

• 单程直飞：seatMapList 长度为 1，该航段可能包含 1 个或多个 cabins（如商务舱 + 经济舱）
• 单程转机（2 个航段）：seatMapList 长度为 2，每个航段各有独立的 cabins
• 往返程直飞：seatMapList 长度为 2（去程 + 回程），每个航段各有独立的 cabins

segmentIndex 从 1 开始，与请求中的 outboundSegments/inboundSegments 数组索引对应。cabins 数组中每个 Cabin 对象代表一个舱位区域，通过 cabinType 区分舱位等级。

座位状态有哪些？

• F (Free)：座位可选，未被占用
• O (Occupied)：座位已被占用，不可选择

如何识别靠窗/靠过道座位？

通过 seatCharacteristics 数组判断：

• 包含 "W"：靠窗座位
• 包含 "A"：靠过道座位
• 包含 "M"：中间座位（通常在 3-3 或 3-4-3 布局的中间列）

紧急出口座位如何识别？

包含以下特性的座位通常是紧急出口排：

• IE (ExitRow)：紧急出口排
• E (ExtraLegroom)：额外腿部空间

这些座位通常价格更高，腿部空间更大，但可能有年龄限制（如 14 岁以上）。

价格为 0 的座位是什么意思？

价格为 0 表示该座位免费可选，不需要额外付费。这种情况常见于：

• 高端舱位（商务舱、头等舱）
• 航司促销活动
• 某些会员权益

业务案例

单人单程选座查询

请求（Request）

{
  "journeyType": "OW",
  "origin": "OTP",
  "destination": "CAG",
  "departureDate": "20260116",
  "adults": 1,
  "children": 0,
  "infants": 0,
  "agent": "AXZ",
  "outboundFareFamily": "BASIC",
  "outboundSegments": [
    {
      "carrier": "XZ",
      "originAirport": "OTP",
      "destinationAirport": "CAG",
      "flightNumber": "XZ3115",
      "departureDate": "20260116"
    }
  ]
}

响应（Response）

响应包含完整的座位图，每个座位都有：

• 位置信息（行号 + 列号）
• 价格信息（price + currency）
• 状态信息（seatStatus：F/O）
• 特性信息（seatCharacteristics：靠窗/靠过道/紧急出口等）

在线查看完整示例：https://jsonhero.io/j/XmTLWK94Ae5X