第三方自动出票供应商协议

协议版本 v3.7。第三方 HTTP 供应商按本协议实现接口，平台在自动出票时主动调用供应商。所有渠道统一使用同一套标准协议。

# 标准流程

平台在查价前生成唯一的外采任务号 procurementNo，后续所有请求都复用这个任务号。

可选能力由渠道配置开关控制：

• supportsPnrData：开启且订单有 PNR 时，平台先查询 IBE D3 / C9，并在请求中携带 pnr、pnrContent、c9FareDetails；
• supportsQuoteVerify：是否在创单前调用验价；
• supportsOrderPay：是否在创单后、出票前调用支付。

任何可选字段没有值时，平台不会发送空字段。

# 通信约定

# 请求头

渠道鉴权模式支持 HMAC_SHA256、BEARER_TOKEN、NONE。

# HMAC-SHA256 签名

signContent = appKey + "\n" + timestamp + "\n" + nonce + "\n" + rawRequestBody

X-Signature = hexLower(HMAC_SHA256(appSecret, signContent))

rawRequestBody 是实际发送的原始 JSON 字符串。验签时必须使用收到的原始 body，不能重新格式化或重新序列化。

# 响应包络

{ "code": 0, "message": "success", "data": {} }

业务失败时应返回非成功的 code 和明确的 message。不要用 HTTP 200 加空 data 表示失败。

# 查价 POST /quote/search

平台发送订单号、行程、完整乘客列表和全部航段，主要字段如下：

响应返回报价数组 policies：

{
  "code": 0,
  "message": "success",
  "data": {
    "policies": [
      {
        "offerId": "OFFER-001",
        "supplierName": "澳洲航空直营",
        "supplierTags": ["极速出票"],
        "currency": "CNY",
        "tripType": "ONEWAY",
        "adultTicketPrice": 1150,
        "adultTaxesAndFees": 397,
        "adultSettlementPrice": 1514.65,
        "totalPrice": 1514.65,
        "adultCabin": "L",
        "remainingSeats": 3,
        "reimbursementType": "E",
        "fareType": "PUB",
        "shouldRebuild": 1,
        "ticketTimeLimit": "2026-07-28 11:00:00",
        "refundTicketRule": "按航司规定",
        "changeTicketRule": "按航司规定",
        "checkedLuggageAllowance": "1PC 23KG",
        "supplierOfferData": { "sessionId": "SESSION-001" }
      }
    ]
  }
}

# 创单、支付、出票

三个接口共用同一套订单请求结构：

• 创单：返回 supplierOrderNo，缺失时平台判定创单失败。必须按 Idempotency-Key 持久化，重复请求返回同一个订单号。
• 支付：在创单后、出票前调用，同样要求幂等。
• 出票：成功只代表已受理，平台随后立即进入查单。相同 Idempotency-Key 的重试禁止重复出票。

# 查单 POST /order/query

处理中：

{ "code": 0, "message": "success", "data": { "supplierOrderNo": "S202607280001", "status": "PROCESSING", "message": "航司出票中" } }

返回 ISSUED 时必须提供：

# 供应商状态

未知状态默认按 PROCESSING 处理。如果供应商使用其他状态名，可以在渠道配置中增加状态映射。

# 可选出票回调

POST {baseUrl}/prod-api/externalProcurement/externalOpenPlatform/callback/issue

供应商在状态变化后回调，平台随即发起一次查单。平台不直接采信回调中的票号，最终结果以 /order/query 的响应为准。

# 幂等与重试

• 国际订单在第三方 HTTP 渠道上同时只允许一个活动任务；
• 步骤失败后只允许人工重试当前步骤，不会自动创建新任务；
• 重试创单、支付、出票时，复用原任务号、供应商订单号和 Idempotency-Key；
• 已出票的任务永久禁止重新创单；
• 网络超时等情况可能触发有限次数的底层重试，供应商接口必须能安全地重复处理。

# 联调验收清单

• 关闭 PNR 资料开关时，请求中不存在 pnr、pnrContent、c9FareDetails；
• 验价、支付开关分别关闭时，流程跳过对应接口；
• 每一步返回的 supplierOfferData 能在下一步收到；
• 创单、支付、出票以 Idempotency-Key 实现强幂等；
• 查单可以安全地重复调用，并正确返回各种状态；
• 能通过 X-Request-Id、procurementNo、supplierOrderNo 定位单次调用的日志。