b450b512a2
- 添加 mipu-api 作为 git submodule (Claude Code Skill) - 迁移 API 文档源文件到 docs/ 目录统一维护 - 添加 Gitea Actions 工作流：tag推送自动打包docs并发布Release - Skill 运行时自动从 mipu-open Release 下载最新文档 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
164 lines
7.7 KiB
Markdown
164 lines
7.7 KiB
Markdown
<!-- 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) |
|
||
|