机票接口说明

机票业务共 9 个接口，覆盖搜索、验价、下单、支付、订单管理、取消/退票全流程。

下单主链路为：搜索 → 可选验价 → 创建订单 → 发起支付。

接口总览

#	方法	路径	用途
1	GET	`/open/v1/flight/airport/search`	机场联想搜索（IATA/中文名/拼音）
2	POST	`/open/v1/flight/search`	航班列表查询（搜索阶段）
3	POST	`/open/v1/flight/pricing`	验价（换可下单 offer_id）
4	POST	`/open/v1/flight/order/create`	创建订单（幂等）
5	POST	`/open/v1/flight/order/pay`	发起支付（user_pay / enterprise_credit / monthly_settle）
6	POST	`/open/v1/flight/order/detail`	订单详情（含 PNR / 票号 / 退票费等）
7	POST	`/open/v1/flight/order/list`	订单列表（分页 + 状态/日期过滤）
8	POST	`/open/v1/flight/order/cancel-fee`	查询取消/退票手续费
9	POST	`/open/v1/flight/order/cancel`	取消订单或发起退票

下单流程图

开发者                              开放平台
  │                                   │
  ├─ search ───────────────────────► │
  │  ◄── flights + search_offer_id（可选 offer_id）─┤
  │                                   │
  │  （cabin 可直下则拿到 offer_id；否则继续验价）
  │                                   │
  ├─ pricing（携带 search_offer_id）─► │
  │  ◄── offer_id + total_fare ──────┤
  │                                   │
  ├─ order/create ─────────────────► │
  │  （offer_id、乘机人、联系人、         │
  │    out_trade_no、pay_mode）         │
  │  ◄── system_no + 待支付信息 ───────┤
  │      （user_pay 时附 checkout_url）  │
  │                                   │
  ├─ order/pay ────────────────────► │
  │                                   │
  │  · user_pay：返回 pay_params，用户去支付
  │  · enterprise_credit / monthly_settle：
  │    直接扣款/记账，订单转为已支付待出票
  │  ◄── pay_params / 支付成功响应 ────┤
  │                                   │
  │  （user_pay 支付完成后，平台异步推进订单）
  │  ◄═══ Webhook 推送订单状态 ════════┤
  │       paid → ticketed             │
  │                                   │
  │（可选）order/detail / order/list 查询订单
  │（可选）order/cancel-fee + order/cancel 取消/退票

流程说明：

搜索：search 一定会返回 search_offer_id；舱位可直下时会同时返回 offer_id。

验价：pricing 把 search_offer_id 换成可下单的 offer_id，并刷新实时价格、税费和乘客报价。

下单：order/create 先按 <app_id, out_trade_no> 做幂等，成功后返回 system_no 及待支付信息。

支付：3 种支付模式——user_pay（微信/支付宝）、enterprise_credit（扣余额）、monthly_settle（月结）。

支付成功：user_pay 支付完成后由平台异步推进订单，并通过 Webhook 推送状态；授信/月结在 order/pay 时即完成"已支付 + 待出票"。

管理 / 取消：order/detail、order/list 用于查询；order/cancel-fee + order/cancel 用于取消或退票。

1. 机场搜索

GET /open/v1/flight/airport/search

根据 IATA/ICAO 代码、中文名或拼音模糊匹配机场，用于输入框联想。

用途：辅助接口，帮助用户选择出发/到达机场。不要放在主链路上反复调用。

Query 参数：keyword（必填，如 深圳 / SZX / bao'an）

2. 机票搜索

POST /open/v1/flight/search

根据出发/到达城市、日期查询航班列表，支持舱位、航司、直飞筛选。

关键流程

每条航班的每个舱位都会返回一个 search_offer_id。

如果舱位同时返回了 offer_id 且 pricing_required = false，可直接下单，跳过验价。

否则需先调用验价接口用 search_offer_id 换取 offer_id。

关键字段

cabins[].search_offer_id：始终返回，用于后续验价或直下。

cabins[].offer_id：可直下时返回，10 分钟有效。

cabins[].pricing_required：false 表示可直下，true 表示需先验价。

cabins[].lowest_price：该舱位最低价（元），含票价 + 机建 + 燃油，不含服务费。

cabins[].baggage_rule / change_rule / refund_rule：行李/改签/退票规则，文本描述。

注意事项

往返查询：trip_type = roundtrip 时必须传 return_date；tag 控制返程匹配规则（lowest_price / same_supplier）。

机场 vs 城市：优先传 from_airport_code / to_airport_code（精确到机场）；不传时用 from_code / to_code（城市三字码）。

直飞筛选：通过 cabins[].stop_count = 0 判断是否直飞，API 不提供直飞筛选参数。

3. 机票验价

POST /open/v1/flight/pricing

支付前校验价格、舱位、退改签规则，返回可下单 offer_id（10 分钟有效）。

何时调用

搜索结果 cabins[].pricing_required = true 时；

距离搜索时间较久，希望确认价格仍有效时；

往返航班联合下单前的最终确认。

关键字段

offer_id：去程可下单令牌，10 分钟有效。

return_offer_id：返程可下单令牌（往返时返回）。

expired_at：offer_id 过期时间（北京时间），超时需重新验价。

total_fare：去程乘客合计总价（元）。

combined_total_fare：往返合计总价（元，仅往返时返回）。

price_changed：与搜索结果相比价格是否变化，true 建议向用户二次确认。

passenger_fares[]：分乘客的票面价 / 机建 / 燃油 / 服务费明细。

注意事项

offer_id 过期后需重新验价，不可直接下单。

price_changed = true 时应向终端用户展示最新价格并确认。

4. 创建机票订单

POST /open/v1/flight/order/create

基于 offer_id + 乘客信息 + 联系人创建订单。

幂等性

幂等键为 <app_id, out_trade_no>。同一 out_trade_no 重复请求只会创建一笔订单，重复调用直接返回已存在订单的 system_no（user_pay 模式同时返回原 checkout_url）。

关键字段

out_trade_no：商户订单号（必填），幂等键，建议格式 {merchant_prefix}_{timestamp}_{seq}。

offer_id：去程 offer_id（必填），来自搜索或验价。

return_offer_id：返程 offer_id（往返时必填）。

passengers：乘客信息列表，字段与验价一致。

contact：联系人信息（姓名、手机、邮箱）。

pay_mode：支付模式，默认 user_pay（终端用户支付）。可选 enterprise_credit（企业授信扣款）/ monthly_settle（月结记账）。

external_user_id / external_user_name / cost_center / approval_id：企业差旅场景的用户 / 成本中心 / 审批单透传字段，原样落库便于对账。

callback_url：订单状态回调地址（HTTPS），平台会在订单状态变化时推送 Webhook（格式见 Webhook 文档）。

need_invoice / invoice_address：是否开票及邮寄地址。

响应字段

system_no：平台订单号，全局唯一。

status：订单状态，初始为 pending_pay。

pay_expire_time：支付截止时间（北京时间），默认下单后 15 分钟，超时自动关单。

total_amount：订单总金额（元）。

pnr：编码，下单时可能为空，出票后补回。

checkout_url：托管收银台地址，仅 pay_mode=user_pay 时返回。可直接将该链接交给终端用户完成微信 / 支付宝 H5 支付。

订单状态

status	含义
`pending_pay`	待支付
`paid`	已支付，待出票
`ticketed`	已出票
`canceled`	已取消
`refunded`	已退款
`failed`	出票失败

注意事项

下单到支付的窗口默认 15 分钟，超时由平台自动关单（status = canceled）。

如果第一次请求超时，建议使用相同 out_trade_no 重试，利用幂等性避免重复下单。

callback_url 需在接入方实现签名校验，防止伪造回调（具体签名算法见 Webhook 文档）。

5. 发起支付

POST /open/v1/flight/order/pay

按 pay_mode 分支处理订单支付：user_pay 走微信 / 支付宝 SDK，授信 / 月结直接扣款记账。

关键字段

system_no：必填，订单号（来自 order/create）。

pay_type：必填，支付方式。可选值：wechat_h5 / wechat_jsapi / wechat_native / wechat_app / wechat_mini / alipay_app / alipay_h5。

openid：微信 JSAPI / 小程序必填。

client_ip：微信 H5 必填，鉴权时已自动注入应用上下文 IP，按需覆盖即可。

return_url：支付宝 H5 同步跳转地址。

响应字段（按 pay_type 不同）

pay_type=wechat_jsapi → pay_params: { prepay_id, app_id, time_stamp, nonce_str, package, sign_type, pay_sign }

pay_type=wechat_h5 → pay_params: { mweb_url }

pay_type=wechat_app → pay_params: { app_id, partner_id, prepay_id, package_value, nonce_str, time_stamp, sign }

pay_type=wechat_mini → pay_params: { app_id, time_stamp, nonce_str, package, sign_type, pay_sign }

pay_type=wechat_native→ pay_params: { code_url }

pay_type=alipay_app → pay_params: { order_str }

pay_type=alipay_h5 → pay_params: { pay_url }

注意事项

pay_mode=user_pay 时，更推荐直接把 order/create 返回的 checkout_url 交给终端用户，托管收银台已处理收银选择 + 微信 H5 / 支付宝 H5 跳转。

pay_mode=enterprise_credit 时，调用本接口会立即扣减企业余额并把订单推进到 paid，无需用户支付。

pay_mode=monthly_settle 时，记账成功后订单同样进入 paid，月底统一对账结算。

6. 订单详情

POST /open/v1/flight/order/detail

按平台订单号或商户订单号查询订单完整信息，包括状态、支付状态、出票状态、PNR、票号、退票费等。

关键字段

system_no / out_trade_no：二选一传入。out_trade_no 仅可查询当前 app 自己创建的订单。

响应中包含 status / status_text、pay_status / pay_status_text、flight_status / flight_status_text 三组状态码 + 文本，便于前端展示。

flight_info：航班信息（航班号、航司、起降机场、起降时间、舱位）。

passengers / contact：乘机人和联系人。

total_amount / refund_fee / refund_amount：订单总金额、已退票费、已退金额。

can_cancel：当前是否仍可取消。

can_refund：当前是否仍可退票（已出票订单）。

estimated_refund_fee：预估退票费（已出票时由查询接口返回）。

refund_rule：结构化退改规则，含 current（当前时间节点的费率/手续费/可退金额/概要）和 stages[]（分阶段时间节点列表，标注 is_current / is_past / no_refund），便于前端按阶梯展示退改政策。

注意事项

已出票订单查详情时，平台会主动同步供应商最新状态（PNR / 票号 / 出票状态）回写本地，方便接入方拿到最新数据。

7. 订单列表

POST /open/v1/flight/order/list

分页查询当前 app 下的机票订单。

关键字段

external_user_id：可选，按接入方用户/员工ID过滤（推荐作为按用户查询的过滤条件，查询性能最优）。

contact_phone：可选，按联系人手机号过滤。

out_trade_no：可选，按商户订单号过滤。

status：可选，按订单状态过滤。

start_date / end_date：可选，按下单日期过滤。

page / page_size：分页参数，page_size 默认 10，最大 100。

多个过滤条件之间为 AND 关系。按接入方用户查询时，external_user_id 需在下单时通过 order/create 一并传入，否则未携带该字段的历史订单查不到，可改用 contact_phone 兜底。

响应字段

total：总数。

page_info：分页信息。

orders[]：订单列表项，包含：

订单标识：system_no / out_trade_no

航班信息：flight_no / airline / cabin_class

行程：dep_city / dep_airport_name / dep_time、arr_city / arr_airport_name / arr_time（depart_time 为兼容旧字段，等同 dep_time）

金额：total_amount

状态：status / status_text、pay_status、flight_status / flight_status_text

其他：pnr / created_at

8. 查询取消手续费

POST /open/v1/flight/order/cancel-fee

取消前查询可退金额和手续费，确认后再调用 order/cancel。

关键字段

order_id：必填，平台订单号。

响应字段

refundable：是否可退。

refund_amount：可退金额（元）。

cancel_fee：手续费（元）。

refund_rule：退票规则文本（如「起飞前 2 小时退票收取票面 50%」）。

注意事项

未支付订单：refundable=true / cancel_fee=0，可直接取消。

已出票订单：会调用供应商接口拉取最新退改规则；部分供应商需联系客服处理。

9. 取消 / 退票

POST /open/v1/flight/order/cancel

未支付或未出票时取消订单；已出票时发起退票，计算退票费和退款金额。

关键字段

system_no：必填，订单号。

reason：可选，取消原因（透传给供应商）。

响应字段

action：cancel（直接取消）/ refund（已出票走退票流程）。

status：处理后状态（canceled / refunding 等）。

refund_fee / refund_amount：退票手续费 / 退款金额（元）。

message：用户可读的提示文案。

注意事项

未支付订单：直接本地取消，无需调供应商。

已支付未出票：调供应商取消，退款 3-7 个工作日到账。

已出票：进入退票流程，需供应商审核（参见对应供应商规则）；订单状态推进至 refunding 或 refunded。

已完成 / 已退款的订单不允许再取消。

完整流程示例

1. 调用 search，拿到 flights[].cabins[]
2. 判断 cabins[].pricing_required：
   - false → 直接用 cabins[].offer_id 下单
   - true  → 调用 pricing 换取 offer_id
3. 调用 order/create，携带 offer_id + 乘客 + 联系人 + out_trade_no
4. 成功后拿到 system_no（user_pay 模式还会返回 checkout_url）
5. 引导用户在 pay_expire_time 前完成支付：
   - user_pay：跳转 checkout_url，或调用 order/pay 自行集成 SDK
   - enterprise_credit / monthly_settle：调用 order/pay 直接扣款 / 记账
6. 平台收到支付回调后推送 Webhook 到 callback_url，订单推进到 paid → ticketed
7. 出票后通过 order/detail 拿到 PNR / 票号；如需退订，按 order/cancel-fee → order/cancel 流程处理

接口总览#

下单流程图#

1. 机场搜索#

2. 机票搜索#

关键流程#

关键字段#

注意事项#

3. 机票验价#

何时调用#

关键字段#

注意事项#

4. 创建机票订单#

幂等性#

关键字段#

响应字段#

订单状态#

注意事项#

5. 发起支付#

关键字段#

响应字段（按 pay_type 不同）#

注意事项#

6. 订单详情#

关键字段#

注意事项#

7. 订单列表#

关键字段#

响应字段#

8. 查询取消手续费#

关键字段#

响应字段#

注意事项#

9. 取消 / 退票#

关键字段#

响应字段#

注意事项#

完整流程示例#

接口总览

下单流程图

1. 机场搜索

2. 机票搜索

关键流程

关键字段

注意事项

3. 机票验价

何时调用

关键字段

注意事项

4. 创建机票订单

幂等性

关键字段

响应字段

订单状态

注意事项

5. 发起支付

关键字段

响应字段（按 pay_type 不同）

注意事项

6. 订单详情

关键字段

注意事项

7. 订单列表

关键字段

响应字段

8. 查询取消手续费

关键字段

响应字段

注意事项

9. 取消 / 退票

关键字段

响应字段

注意事项

完整流程示例