机票 API

低价日历

GET /v1/flights/price-calendar?origin=DXB&destination=LHR&departureFrom=2026-11-01&departureTo=2026-11-30 以您的币种返回该航线每天缓存中的最低票价，并注明缓存的新鲜程度。添加 returnFrom / returnTo 可获得每组日期的往返总价，添加 cabin 可限定舱位等级。该接口由我们的价格缓存提供——即时返回，且从不计为供应商搜索——因此可在真正搜索之前用它绘制日历或“最便宜日期”条。

搜索

POST /v1/flights/search：单程一个航段，往返两个，多段行程最多六个；按类型提供乘客人数；舱位和最大经停次数（maxStops）可选。使用 wait=true 时，响应会在所有供应商返回后包含全部报价；使用 wait=false 时，您会得到一个 searchId，并使用游标轮询 GET /v1/flights/search/{searchId}，直到 complete 为 true。

每条报价都包含不透明的 offerId、以您的币种计价的总额及按乘客的明细、行程 → 航段（承运人、航班号、时间、机型、舱位、行李）、票价条件摘要以及过期时间。报价在搜索会话有效期内有效（约 20 分钟）。

定价与规则

POST /v1/flights/offers/{offerId}/price 会在您提交前与供应商重新验证运价，并返回确认后的价格、税费以及航空公司要求的乘客字段（证件、出生日期、常旅客）。GET .../fare-rules 返回罚则文本；GET .../ancillaries 列出可添加到订单中的付费行李和选项。

附加服务（额外行李）

GET /v1/flights/offers/{offerId}/ancillaries 列出航空公司针对该票价提供的收费附加项——目前为额外托运行李额度，每项都带有 key、件数 / 重量和每位乘客的价格。收费意味着它们在票价之外另行计价并随订单结算，不同于报价本身所显示的免费行李额度。

如需购买，请在 POST /v1/flights/orders 中添加 ancillaries[]：每个附加项一条记录，包含 key 和 passengerIndex（passengers 中从 0 开始的索引）。它们会与订单一同定价、预订和出票，并显示在订单的票价总额中。已出票的订单不能再添加附加项；选座功能将沿用相同的模式。

{
  "offerId": "fo_7Gk2Qp9LcKM5aGqrMQOIzJko",
  "passengers": [{ "type": "ADT", "gender": "M", "firstName": "SAM", "lastName": "TRAVELLER", "dateOfBirth": "1990-05-04" }],
  "contact": { "email": "[email protected]", "phone": "+971501234567" },
  "ancillaries": [{ "key": "BAG20-1", "passengerIndex": 0 }]
}

创建订单

POST /v1/flights/orders，传入 offerId、乘客（与护照一致的姓名、类型、出生日期、国际行程所需证件）、联系人以及可选的 ancillaries[]（见上文）；并添加 Idempotency-Key。您将收到 orderId、航空公司 PNR、出票时限以及状态 held。在沙箱中，订单会进入供应商的测试系统且不收取任何费用；在生产环境中，将冻结相应的保证金。

出票

POST /v1/flights/orders/{orderId}/issue（必须提供 Idempotency-Key）出具电子客票，并返回每位乘客的票号。可随时通过 GET /v1/flights/orders/{orderId} 读取订单；状态依次为 held → issued → cancelled/refunded。

作废、取消与退款

GET /v1/flights/orders/{orderId}/refund-quote 告诉您根据票价规则取消可退还多少（当天作废通常免费）。POST /v1/flights/orders/{orderId}/cancel 执行取消；退款会记入您的保证金账本，可在开发者门户中查看。