物流单据上传

接口信息

POST /payment/{apiKey}/tracking/upload

• 路径参数：apiKey（商户 API Key）

请求参数

参数名	类型	必填	参与签名	说明
merchantId	String	是	是	商户号
trackingList	Array	是	是	物流单据列表
sign	String	是	否	签名

trackingList 数组元素

字段	类型	必填	说明
orderId	String	条件必填	系统交易单号（与 relationId 至少传一个）
relationId	String	条件必填	商家关联 ID（与 orderId 至少传一个）
trackingNo	String	是	物流单号
trackingChannel	String	是	物流渠道（如：顺丰速运、DHL、FedEx）
trackUrl	String	否	物流追踪链接

响应参数

字段	类型	说明
data.successCount	Integer	成功上传数量
data.failedCount	Integer	失败数量
data.failedOrders	Array	失败的订单号列表
data.sign	String	返回结果签名（用于验证返回数据真实性）

返回签名验证

响应中的 data.sign 可用于校验返回数据未被篡改：

1. 提取 data 对象中所有字段值（排除 sign 字段本身）
2. 按字段名首字母升序排序
3. 依次拼接所有字段值
4. 末尾追加商户 SecretId
5. SHA-256 加密后与 data.sign 对比

请求示例

{
  "merchantId": "MERCHANT_001",
  "trackingList": [
    {
      "orderId": "TRD_20231201_001",
      "trackingNo": "SF1234567890",
      "trackingChannel": "SF Express",
      "trackUrl": "https://www.sf-express.com/tracking/SF1234567890"
    },
    {
      "relationId": "SHOP_ORDER_12345",
      "trackingNo": "DHL9876543210",
      "trackingChannel": "DHL"
    }
  ],
  "sign": "calculated_signature_here"
}

响应示例

{
  "rtn_code": "0000",
  "rtn_msg": "Upload successful",
  "success": true,
  "data": {
    "successCount": 2,
    "failedCount": 0,
    "failedOrders": [],
    "sign": "5097d223b249d4512a6103ce06568f2ddbfff8716c14c8465be1e543b842dc4e"
  }
}