标准外采开放接口

本接口用于出票供应商主动拉单：系统按出票规则生成外采任务，供应商定时拉取待出票任务，确认接单，出票后回传票号、PNR 和价格。

当前版本 v1.0 只覆盖出票业务，不包括改签和退票。如果希望由平台主动调用供应商接口，请参阅[第三方自动出票供应商协议](/docs/agent/supplier-protocol)。

对接流程

系统根据出票规则生成外采任务，状态为 PENDING；
供应商调用拉单接口获取待出票任务；
供应商调用接单接口确认处理，并绑定自己的订单号；
供应商完成出票后调用回调接口，回传结果；
系统回填采购单、票号、出票状态和订单日志。

基础信息

项目	约定
接口前缀	`{baseUrl}/prod-api/externalProcurement/openapi/v1/issue/orders`
请求格式	`Content-Type: application/json`
鉴权	Header 中传 `X-External-Token: 供应商Token`

/prod-api 是生产 Nginx 的 API 前缀。如果网关已自动补该前缀，不要重复拼接。Token 由我方分配，供应商只能访问自己渠道下的任务。

统一响应

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

code	说明
`0`	成功
`401`	Token 为空、无效或账号未启用
`404`	外采任务不存在，或不属于当前供应商
`500`	参数错误、状态不支持、业务处理失败

任务状态

状态	含义	说明
`PENDING`	待接单	供应商可拉取
`ACCEPTED`	已接单	供应商已确认接单
`PROCESSING`	出票中	供应商处理中
`ISSUED`	出票完成	终态
`FAILED`	出票失败	终态
`CANCELLED`	已取消	终态

终态任务不能再次接单。已出票的任务重复回调 ISSUED 时按幂等处理。

拉取待出票订单

POST /externalProcurement/openapi/v1/issue/orders/pull

拉取当前供应商渠道下状态为 PENDING 的任务。

{ "limit": 20 }

字段	类型	必填	说明
`limit`	number	否	单次拉取数量，默认 20，最大 100

响应 data 是任务数组：

{
  "code": 0,
  "msg": "success",
  "data": [
    {
      "procurementNo": "EP202605270001",
      "orderSerialNo": "SO202605270001",
      "purchaseChannelCode": "STANDARD_EXTERNAL_ISSUE",
      "supplierOrderNo": null,
      "status": "PENDING",
      "orderType": "ISSUE",
      "tripType": "ONEWAY",
      "currency": "HKD",
      "totalPrice": 918.27,
      "contact": { "name": "张三", "mobile": "13800000000", "email": "test@example.com" },
      "passengers": [
        {
          "passengerId": 10001,
          "name": "ZHANG/MEIMEI",
          "ageType": "ADT",
          "birthday": "1990-01-01",
          "gender": "F",
          "cardType": "PP",
          "cardNum": "EQ119181",
          "cardExpired": "2030-01-01",
          "cardIssuePlace": "CN",
          "nationality": "CN"
        }
      ],
      "segments": [
        {
          "segmentId": 20001,
          "routeNo": 1,
          "depAirport": "HKG",
          "arrAirport": "BKK",
          "depTime": "2026-06-01 10:30:00",
          "arrTime": "2026-06-01 13:00:00",
          "fltNum": "HX765",
          "cabin": "Y",
          "carrier": "HX",
          "baggage": 20,
          "baggageNumber": 1
        }
      ],
      "createdAt": "2026-05-27T01:00:00"
    }
  ]
}

确认接单

POST /externalProcurement/openapi/v1/issue/orders/accept

{ "procurementNo": "EP202605270001", "supplierOrderNo": "407900" }

字段	类型	必填	说明
`procurementNo`	string	是	我方外采任务号
`supplierOrderNo`	string	是	供应商订单号

接单成功后任务变为 ACCEPTED。幂等规则：

同一任务用同一 supplierOrderNo 重复接单，按同一次接单处理；
同一任务已绑定其他 supplierOrderNo 时拒绝；
任务已是 ISSUED、FAILED、CANCELLED 时不能接单。

查询任务详情

GET /externalProcurement/openapi/v1/issue/orders/{procurementNo}

响应结构与拉单接口中的单个任务对象相同。

出票结果回调

POST /externalProcurement/openapi/v1/issue/orders/callback

出票成功、失败或处理中状态变化时调用。

{
  "procurementNo": "EP202605270001",
  "supplierOrderNo": "407900",
  "status": "ISSUED",
  "pnr": "W73YFC",
  "bigPnr": "MUABCD",
  "totalPrice": 918.27,
  "currency": "HKD",
  "tickets": [
    {
      "passengerId": 10001,
      "ticketNo": "1601234567890",
      "ticketPrice": 752.98,
      "tax": 165.29,
      "payPrice": 918.27
    }
  ],
  "message": "出票成功"
}

字段	类型	必填	说明
`procurementNo`	string	是	我方外采任务号
`supplierOrderNo`	string	否	供应商订单号，已接单任务建议必传
`status`	string	是	`PROCESSING`、`ISSUED`、`FAILED`、`CANCELLED`
`pnr` / `bigPnr`	string	否	PNR 与航司大编码，出票成功时建议传
`totalPrice` / `currency`	number / string	否	采购总价与币种
`tickets`	array	出票成功必传	票号明细
`message`	string	否	处理说明或失败原因

tickets[] 字段：

字段	必填	说明
`passengerId`	否	我方乘客 ID，优先用于匹配
`passengerName` / `certNo`	否	无 `passengerId` 时用于匹配乘客
`ticketNo`	是	票号
`pnr` / `bigPnr`	否	乘客级 PNR / 大编码，非空时优先于订单级
`ticketPrice` / `sellingPrice` / `tax` / `buildPrice` / `fuelPrice` / `payPrice`	否	票面、销售、税费、机建、燃油、实付

回调处理规则：

ISSUED：回填采购信息、票号、出票时间，并把订单推进为出票完成；
FAILED：只更新任务失败状态和原因，不会把订单改为出票成功；
CANCELLED / PROCESSING：更新任务状态；
回调中的 supplierOrderNo 与已绑定的订单号不一致时拒绝。

标准外采开放接口

# 对接流程

# 基础信息

# 统一响应

# 任务状态

# 拉取待出票订单

# 确认接单

# 查询任务详情

# 出票结果回调