mipu-open/docs/04-01_booking-hold.md

booking/hold - 下单

下单(booking/hold) API 说明文档

使用场景

1. 用户在航班验价通过后，确认预订意向，提交乘客与联系人信息以生成正式订单

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

1. 未通过验价接口（checkRoute）获取有效 offerId 时（此场景需先调用验价接口，确保价格与航线有效性）
2. 验价接口返回的 offerId 已过期（通常与支付截止时间关联，过期后需重新验价获取新 offerId）
3. 乘客信息、证件信息未完整填写或格式错误时（应先校验信息合法性，避免接口调用失败）

性能指标

• 响应速度：98% 的请求响应速度 < 15000ms（因需实时对接航司数据，响应速度明显慢于搜索接口）

请求说明

请求地址	https://${endpoint}/booking/hold
请求方法	POST

请求参数

Header

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

请求体

{
  "orderId": "abbc4b57fb75",
  "journeyType": "OW",
  "origin": "MIL",
  "destination": "CAG",
  "departureDate": "20251118",
  "adults": 1,
  "children": 0,
  "infants": 0,
  "agent": "u2web",
  "proxy": "myproxy-us",
  "outboundFareFamily": "promo",
  "inboundFareFamily": "",
  "maximumFareThreshold": 15009.69,
  "currency": "THB",
  "outboundSegments": [
    {
      "carrier": "SL",
      "originAirport": "PHS",
      "destinationAirport": "DMK",
      "flightNumber": "SL557",
      "departureDate": "20251119"
    }
  ],
  "inboundSegments": [
  ],
  "passengers": [
    {
      "firstName": "first",
      "lastName": "last",
      "passengerType": "ADT",
      "dateOfBirth": "19970616",
      "gender": "M",
      "documentNumber": "E12343214",
      "documentType": "PP",
      "documentIssuePlace": "CN",
      "documentExpirationDate": "20260731",
      "nationality": "CN",
      "mobile": "0086-18923726222",
      "frequentFlyerNumber": "",
      "frequentFlyerCarrier": ""
    }
  ],
  "contactInfo": {
    "firstName": "san",
    "lastName": "zhang",
    "address": "dfdsaqqq",
    "phoneCountryCode": "0086",
    "phone": "18912345678",
    "email": "san.zhang@gmail.com",
    "postCode": "310006",
    "city": "hangzhou",
    "province": "zejiang",
    "country": "CN"
  }
}

参数详情

参数名称	类型	是否必选	示例值（默认值）	说明
orderId	String	是	abbc4b57fb75	你系统内的订单号，返回的有效报价唯一标识，用于关联待下单的航线与价格
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的名字仅往返程有值
maximumFareThreshold	Number	是	15009.69	最高票价阈值，超过此价格的报价将不会被接受（用于限制订单金额）
currency	String	是	"THB"	出票币种代码，遵循ISO 4217标准，如：USD、CNY、THB、EUR等。 注意：必须为出票币种，系统不会进行任何汇率转换
proxy	String	是		本次获取航司数据采用的代理方式。如果需要指定代理国家请在代理用户后面加上国家二字码。如myproxy-US,US代表美国
passengers	Array	是	请查看实体定义(Passenger)	乘客信息列表，支持 1-9 名乘客（具体数量受航司限制），每个数组元素为单个乘客详情
contactInfo	Object	是	请查看实体定义(ContactInfo)	联系人信息，用于接收订单通知、行程单等

返回参数

探索一个响应实体：https://jsonhero.io/j/pPOhukgKMcln/editor

参数名称	类型	示例值	说明
code	Integer	0	系统状态码：0 = 成功，非 0 = 失败
msg	String	null	系统消息：成功时为 null，失败时返回具体错误提示（如 “证件有效期不足”“航司订单创建超时”）
pnr	String	000000	仅同步模式会响应PNR信息注意对于不支持Hold的航司，我们也会实施与航司进行交互，并将动作完成在支付前一步，这种情况也可以返回000000
pnrExpiryTime	String	YYYYMMDDHHMMSS20251225121212	hold到的PNR有效期，此处时间为UTC 0时区格式。
status	String		* 异步模式，且进行中为进行中,失败，成功 * 同步模式，为完成，失败，成功
orderId	String		入参给的orderId
feeItems	Array	参考Feeitems实体	从航司处获取的报价细项拆分feeItems 实体定义

实体定义说明

本接口涉及的实体对象定义如下：

请求参数实体

实体名称	说明	链接
FlightSegmentRequest	航段请求对象，用于描述单段航班的核心信息	查看详情
Passenger	乘客信息对象，包括身份信息、证件信息、常旅客信息等	查看详情
ContactInfo	联系人信息对象，用于接收订单通知、行程单等	查看详情

返回参数实体

实体名称	说明	链接
Itinerary	行程组合信息，包含去程和返程航段列表	查看详情
FlightFare	票价信息对象，描述不同乘客类型的费用构成	查看详情
SegmentElement	航段响应对象，描述单段航班的详细信息	查看详情
FreeBaggage (freeAncillaryList)	免费行李额元素，描述每个航段每种乘客类型的免费行李配额	查看详情
RefundRule (refundRules)	退改规则对象，描述航班的退改签政策（预留字段，暂未提供）	查看详情
FlightPolicy	航班政策对象，包含行李、退改等政策信息	查看详情
AncillaryProduct	附加产品对象，描述付费行李等附加服务	查看详情
feeItems	费用明细对象，拆分航班预订的各类费用	查看详情