机票接口说明

机票业务共 4 个接口，下单流程为：搜索 → 可选验价 → 下单。

下单流程图

开发者                              开放平台
  │                                   │
  ├─ 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             │

流程说明：

搜索：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 时即完成"已支付 + 待出票"。

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 建议向用户二次确认。

supplier_changed：供应商是否切换，true 可能影响退改签规则。

注意事项

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

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

4. 创建机票订单

POST /open/v1/flight/order/create

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

幂等性

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

关键字段

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

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

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

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

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

pay_mode：支付模式，默认 user_pay（终端用户支付）。

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

响应字段

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

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

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

total_amount：订单总金额（元）。

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

订单状态

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

注意事项

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

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

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

完整流程示例

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，引导用户在 pay_expire_time 前完成支付
5. 平台收到支付回调后推送 Webhook 到 callback_url，订单推进到 paid → ticketed

下单流程图#

1. 机场搜索#

2. 机票搜索#

关键流程#

关键字段#

注意事项#

3. 机票验价#

何时调用#

关键字段#

注意事项#

4. 创建机票订单#

幂等性#

关键字段#

响应字段#

订单状态#

注意事项#

完整流程示例#

下单流程图

1. 机场搜索

2. 机票搜索

关键流程

关键字段

注意事项

3. 机票验价

何时调用

关键字段

注意事项

4. 创建机票订单

幂等性

关键字段

响应字段

订单状态

注意事项

完整流程示例