init: mipu-open 对外开放项目统一管理仓库

- 添加 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>
2026-05-04 12:16:08 +08:00
commit b450b512a2
38 changed files with 5473 additions and 0 deletions
--- a/docs/04-01_booking-hold.md
+++ b/docs/04-01_booking-hold.md
@@ -0,0 +1,163 @@
+<!-- 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) |
+