Files

杨柳杰 b450b512a2 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

11 KiB

Raw Blame History

booking/query - 订单查询

订单查询(booking/query) API 说明文档

使用场景

查询订单的详细信息和当前状态

在支付完成后查询订单确认状态

在客服系统中查询订单详情

获取订单的完整行程、乘客和费用信息

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

查询不存在的订单 ID

查询不属于当前客户的订单（clientCode 不匹配）

性能指标

响应速度：98% 的请求响应速度 < 500ms

接口成功率：> 99.5%

请求说明

请求地址	https://${endpoint}/booking/query
请求方法	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"
}

参数详情

参数名称	类型	是否必选	示例值（默认值）	说明
orderId	String	是	abbc4b57fb75	客户的订单号，用于查询订单详情

返回参数

成功响应

{
  "orderId": "abbc4b57fb75",
  "requestId": "req-12345",
  "agentCode": "u2web",
  "status": "CONFIRMED",
  "payStatus": "PAID",
  "origin": "MIL",
  "destination": "CAG",
  "journeyType": "OW",
  "pnr": "ABC123",
  "pnrExpiryTime": "2025-12-25T12:00:00Z",
  "feeItems": {
    "baseFare": 100.00,
    "taxes": 50.50,
    "total": 150.50,
    "currency": "EUR"
  },
  "passengers": [
    {
      "lastName": "Rossi",
      "firstName": "Mario",
      "passengerType": "ADT",
      "adult": true,
      "child": false,
      "infant": false,
      "dateOfBirth": "1980-01-15",
      "gender": "M",
      "documentType": "PASSPORT",
      "documentNumber": "AA1234567",
      "ancillaries": []
    }
  ],
  "segments": [
    {
      "airline": "AZ",
      "flightNo": "AZ1234",
      "dptAirport": "MIL",
      "arrAirport": "CAG",
      "dptTime": "2025-11-18T10:30:00Z",
      "arrTime": "2025-11-18T12:15:00Z",
      "equipment": "A320"
    }
  ],
  "credential": null,
  "promoCode": "SAVE10",
  "createTime": "2024-11-15T10:00:00Z",
  "updateTime": "2024-11-15T10:30:00Z",
  "retryCount": 3,
  "retriedCount": 0
}

错误码说明

本接口可能返回以下错误码：

错误码	错误名称	说明	处理建议
42005	BOOKING_NOT_FOUND	订单不存在	请检查 orderId 是否正确，或订单是否属于当前客户
41003	PRICE_CHANGED	票价高于预期	航司侧价格已变动，请检查响应中的 feeItems 获取最新价格，引导用户确认是否继续

失败响应

订单不存在 (42005)

{
  "code": 42005,
  "msg": "Booking not found"
}

票价变动 (41003)

{
  "code": 41003,
  "msg": "Price changed. Please check the latest price in feeItems.",
  "data": {
    "orderId": "abbc4b57fb75",
    "feeItems": {
      "baseFare": 110.00,
      "taxes": 52.50,
      "total": 162.50,
      "currency": "EUR"
    }
  }
}

响应字段说明

基本字段

参数名称	类型	说明
orderId	String	客户的订单号
requestId	String	请求 ID
agentCode	String	代理商代码
status	String	订单状态（见下方状态说明）
payStatus	String	支付状态（见下方支付状态说明）
origin	String	出发地 IATA 3 字码
destination	String	到达地 IATA 3 字码
journeyType	String	行程类型 OW：单程 RT：往返

PNR 相关

参数名称	类型	说明
pnr	String	航司 PNR 码（订座记录编号）
pnrExpiryTime	String	PNR 有效期，ISO 8601 格式（UTC 0 时区）

费用信息

参数名称	类型	说明
feeItems	Map	费用明细（原始 JSON 对象）详见：feeItems 实体定义

乘客和航班

参数名称	类型	说明
passengers	Array<BookingPassenger>	乘客信息列表（见 BookingPassenger 定义）
segments	Array<BookingSegment>	航班段列表（见 BookingSegment 定义）

其他信息

参数名称	类型	说明
credential	Object	订单凭据信息
promoCode	String	促销码
createTime	DateTime	订单创建时间，ISO 8601 格式
updateTime	DateTime	订单最后更新时间，ISO 8601 格式
retryCount	Integer	可重试的次数
retriedCount	Integer	已经重试的次数

状态说明

订单状态 (status)

状态	说明
PENDING	订单处理中，等待航司确认
CONFIRMED	订单已确认，PNR 已生成
CANCELLED	订单已取消
FAILED	订单失败

支付状态 (payStatus)

状态	说明
UNPAID	未支付
PENDING	支付处理中
PAID	已支付
REFUNDED	已退款
FAILED	支付失败

数据来源说明

本接口返回的数据优先从 responseJson 字段解析，如果 responseJson 为空或解析失败（code 不是 0 且 feeItems/passengers/segments 均为空），则从 holdResponse 字段回退获取。

业务流程

订单查询场景

1. 客户下单（booking/hold）→ 获取 orderId
         ↓
2. 客户选择支付方式并支付（booking/payment）
         ↓
3. 查询订单状态（booking/query）→ 确认订单状态
         ↓
4. 如需要，可以取消订单（booking/cancel）

常见问题

如果订单不存在会返回什么？

接口会返回错误响应，code 为 40401，msg 为 "Booking not found"。这种情况通常由以下原因造成：

orderId 错误或不存在
订单属于其他客户（clientCode 不匹配）
订单已过期或被删除

status 和 payStatus 有什么区别？

status：订单的整体状态（PENDING/CONFIRMED/CANCELLED/FAILED）
payStatus：订单的支付状态（UNPAID/PENDING/PAID/REFUNDED/FAILED）

feeItems 返回什么结构？

feeItems 是一个原始的 Map 对象，直接从航司响应的 JSON 中解析。

详细的字段说明请参考：feeItems 实体定义

passengers 和 segments 的详细定义是什么？

BookingPassenger（乘客信息）

参数名称	类型	说明
lastName	String	乘客姓
firstName	String	乘客名
passengerType	String	乘客类型（ADT/CHD/INF）
adult	Boolean	是否为成人
child	Boolean	是否为儿童
infant	Boolean	是否为婴儿
dateOfBirth	String	出生日期
gender	String	性别（M/F）
documentType	String	证件类型（如 PASSPORT）
documentNumber	String	证件号码
ancillaries	Array	附加服务列表

BookingSegment（航班段信息）

参数名称	类型	说明
airline	String	航司代码（IATA 2 字码）
flightNo	String	航班号（如 AZ1234）
dptAirport	String	出发机场 IATA 3 字码
arrAirport	String	到达机场 IATA 3 字码
dptTime	String	出发时间，ISO 8601 格式
arrTime	String	到达时间，ISO 8601 格式
equipment	String	机型（如 A320、B737）

什么时候会从 holdResponse 回退数据？

当 responseJson 满足以下任一条件时，会从 holdResponse 回退 feeItems/passengers/segments：

responseJson 为空
responseJson 解析失败
code 不是 0 且 feeItems/passengers/segments 均为空

这确保了即使订单最终状态失败，也能获取到 hold 阶段的数据。

遇到票价变动错误 (PRICE_CHANGED) 怎么办？

当接口返回错误码 41003 (PRICE_CHANGED) 时，表示航司侧票价高于预期。这种情况通常发生在：

下单后到支付前，航司调整了票价
库存紧张导致票价上涨
促销活动价格已过期

处理流程：

1. 接收到 41003 错误响应
         ↓
2. 从响应的 data.feeItems 中获取最新价格
         ↓
3. 向用户展示价格变动信息
         ↓
4. 询问用户是否继续
         ↓
5a. 用户同意 → 重新调用 booking/hold 使用新价格
         ↓
5b. 用户拒绝 → 取消订单流程

关键点：

错误响应中的 feeItems 包含最新的价格明细
需要用户明确确认后才能继续交易

业务案例

查询已确认的订单

请求（Request）

{
  "orderId": "abbc4b57fb75"
}

响应（Response）

{
  "orderId": "abbc4b57fb75",
  "agentCode": "u2web",
  "status": "CONFIRMED",
  "payStatus": "PAID",
  "origin": "MIL",
  "destination": "CAG",
  "journeyType": "OW",
  "pnr": "ABC123",
  "passengers": [
    {
      "lastName": "Rossi",
      "firstName": "Mario",
      "passengerType": "ADT"
    }
  ],
  "segments": [
    {
      "airline": "AZ",
      "flightNo": "AZ1234",
      "dptAirport": "MIL",
      "arrAirport": "CAG",
      "dptTime": "2025-11-18T10:30:00Z",
      "arrTime": "2025-11-18T12:15:00Z"
    }
  ],
  "createTime": "2024-11-15T10:00:00Z",
  "updateTime": "2024-11-15T10:30:00Z"
}

查询往返程订单

请求（Request）

{
  "orderId": "rt-order-12345"
}

响应（Response）

{
  "orderId": "rt-order-12345",
  "journeyType": "RT",
  "origin": "MIL",
  "destination": "CAG",
  "status": "CONFIRMED",
  "payStatus": "PAID",
  "pnr": "XYZ789",
  "passengers": [
    {
      "lastName": "Rossi",
      "firstName": "Mario",
      "passengerType": "ADT"
    },
    {
      "lastName": "Bianchi",
      "firstName": "Luca",
      "passengerType": "ADT"
    }
  ],
  "segments": [
    {
      "airline": "AZ",
      "flightNo": "AZ1234",
      "dptAirport": "MIL",
      "arrAirport": "CAG",
      "dptTime": "2025-11-18T10:30:00Z",
      "arrTime": "2025-11-18T12:15:00Z"
    },
    {
      "airline": "AZ",
      "flightNo": "AZ5678",
      "dptAirport": "CAG",
      "arrAirport": "MIL",
      "dptTime": "2025-11-25T14:00:00Z",
      "arrTime": "2025-11-25T15:45:00Z"
    }
  ],
  "createTime": "2024-11-15T10:00:00Z",
  "updateTime": "2024-11-15T10:30:00Z"
}

11 KiB Raw Blame History Unescape Escape

booking/query - 订单查询

订单查询(booking/query) API 说明文档

使用场景

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

性能指标

请求说明

请求参数

Header

请求体

参数详情

返回参数

成功响应

错误码说明

失败响应

订单不存在 (42005)

票价变动 (41003)

响应字段说明

基本字段

PNR 相关

费用信息

乘客和航班

其他信息

状态说明

订单状态 (status)

支付状态 (payStatus)

数据来源说明

业务流程

订单查询场景

常见问题

如果订单不存在会返回什么？

status 和 payStatus 有什么区别？

feeItems 返回什么结构？

passengers 和 segments 的详细定义是什么？

BookingPassenger（乘客信息）

BookingSegment（航班段信息）

什么时候会从 holdResponse 回退数据？

遇到票价变动错误 (PRICE_CHANGED) 怎么办？

业务案例

查询已确认的订单

请求（Request）

响应（Response）

查询往返程订单

请求（Request）

响应（Response）

11 KiB

Raw Blame History