<!-- mipuyun-api-doc: booking-hold -->
# booking/hold - 下单

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

## 使用场景

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

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

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

## 性能指标

> - 响应速度：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 |

### 

### 请求体

```json
{
  "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> | 是 |  | 去程航段信息，详见 [FlightSegmentRequest](07-01_flight-segment-request.md) |
| inboundSegments | Array<FlightSegmentRequest> | 否 |  | 返程航段信息往返行程为必须，详见 [FlightSegmentRequest](07-01_flight-segment-request.md) |
| outboundFareFamily | String | 是 |  | 去程FareFamily的名字 |
| inboundFareFamily | String | 否 |  | 回程FareFamily的名字仅往返程有值 |
| maximumFareThreshold | Number | **是** | 15009.69 | 最高票价阈值，超过此价格的报价将不会被接受（用于限制订单金额） |
| currency | String | **是** | "THB" | 出票币种代码，遵循ISO 4217标准，如：USD、CNY、THB、EUR等。<br>**注意**：必须为出票币种，系统不会进行任何汇率转换 |
| proxy | String | 是 |  | 本次获取航司数据采用的代理方式。如果需要指定代理国家请在代理用户后面加上国家二字码。如myproxy-US,US代表美国 |
| passengers | Array | 是 | 请查看实体定义([Passenger](07-02_passenger.md)) | 乘客信息列表，支持 1-9 名乘客（具体数量受航司限制），每个数组元素为单个乘客详情 |
| contactInfo | Object | 是 | 请查看实体定义([ContactInfo](07-03_contact-info.md)) | 联系人信息，用于接收订单通知、行程单等 |

## 

## 返回参数

探索一个响应实体：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 实体定义](08-06_fee-items.md) |

## 实体定义说明

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

### 请求参数实体

| 实体名称 | 说明 | 链接 |
| --- | --- | --- |
| FlightSegmentRequest | 航段请求对象，用于描述单段航班的核心信息 | [查看详情](07-01_flight-segment-request.md) |
| Passenger | 乘客信息对象，包括身份信息、证件信息、常旅客信息等 | [查看详情](07-02_passenger.md) |
| ContactInfo | 联系人信息对象，用于接收订单通知、行程单等 | [查看详情](07-03_contact-info.md) |

### 返回参数实体

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