backstage / wutong

顺丰开放平台对接信息.md 4.39 KB

顺丰开放平台对接信息

配置位置

顺丰相关配置位于 抖音物流子项目 中：

douyin/DouyinLogistics.API/appsettings.json → "Sf" 节

配置结构（SfConfig）

配置项 说明 代码属性 当前值（占位符）
CustomerCode 顺丰客户编码（即 partnerID） SfConfig.CustomerCode your_customer_code
CheckWord 顺丰校验码（用于签名） SfConfig.CheckWord your_check_word
MonthlyAccount 顺丰月结账号 SfConfig.MonthlyAccount your_monthly_account
ApiBaseUrl API 基础地址 SfConfig.ApiBaseUrl https://sf-api.sf-express.com

注意：所有本地配置文件中的顺丰凭证均为占位符，实际生产凭证配置在服务器运行环境中（未提交到 Git）。

appsettings.json 配置示例

{
  "Sf": {
    "CustomerCode": "实际客户编码",
    "CheckWord": "实际校验码",
    "ApiBaseUrl": "https://sf-api.sf-express.com",
    "MonthlyAccount": "实际月结账号"
  }
}

相关代码文件

文件 说明
douyin/DouyinLogistics.API/Models/SfConfig.cs 顺丰配置模型类
douyin/DouyinLogistics.API/Services/SfService.cs 顺丰 API 调用服务
douyin/DouyinLogistics.API/Models/SfWaybillResponse.cs 顺丰运单响应模型
douyin/DouyinLogistics.API/Controllers/OrdersController.cs 订单控制器（调用顺丰创建运单）
douyin/DouyinLogistics.API/Services/OrderService.cs 订单服务（调用 SfService）

已对接的顺丰 API

1. 创建运单（已实现）

  • 服务代码：EXP_RECE_CREATE_ORDER
  • API 地址：POST {ApiBaseUrl}/sf-express-service/sfexpressService
  • 签名方式：SHA256( Base64(msgData) + timestamp + CheckWord ) → Base64
  • 请求格式：
{
  "partnerID": "CustomerCode",
  "requestID": "UUID",
  "serviceCode": "EXP_RECE_CREATE_ORDER",
  "timestamp": "毫秒时间戳",
  "msgData": "Base64编码的请求JSON",
  "msgDigest": "签名"
}
  • 响应示例（来自数据库 api_order_dispath.sfSendBody）：
{
  "success": true,
  "errorCode": "S0000",
  "msgData": {
    "orderId": "648498145050693",
    "originCode": "025",
    "waybillNoInfoList": [
      { "waybillType": 1, "waybillNo": "SF7444495309022" }
    ],
    "routeLabelInfo": [...]
  }
}

2. 路由查询（未实现，待对接）

  • 服务代码：EXP_RECE_SEARCH_ROUTES
  • 用途：通过快递单号查询物流轨迹
  • 需要的信息：拦截时间、拦截状态、退回单号

3. 拦截件查询（未实现，待对接）

  • 服务代码：待确认（可能是 EXP_RECE_SEARCH_INTERCEPT 或通过路由查询获取）
  • 用途：查询拦截状态和退回单号

数据库相关表

api_order_dispath（ncc_wutong 库）

存储订单发货记录和顺丰 API 响应。

字段 类型 说明
id varchar 主键
manOrderId varchar 主订单
orderId varchar 单个订单 ID
addTime datetime 发货时间
status int 状态
billNo varchar 快递单号（如 SF7444495309022）
sfSendBody text 顺丰下单 API 完整响应 JSON
sfMdBody text 顺丰面单数据
batchId varchar 批量订单 ID

wt_kdljjl（ncc_wutong 库）

快递拦截记录表（目前数据为空，无 API 自动同步）。

字段 类型 说明
F_Id 主键 主键
F_Thd 退货单 退货单号
F_Ddh 订单号 原始订单号
F_Kdgs 快递公司 如"顺丰"
F_Ljsj datetime 拦截时间
F_Ljzt 拦截状态 拦截状态
F_Ddzt 订单状态 订单状态
F_Bgzt 包裹状态 包裹状态
F_Shzt 审核状态 审核状态

缺少字段：退回单号（需新增）

发货人信息

{
  "Name": "PongGame",
  "Phone": "18014801756",
  "Address": "浦洲路39号沿海创中心A301",
  "Province": "江苏省",
  "City": "南京市",
  "District": "浦口区"
}

待办事项

  • [ ] 获取生产环境的实际 CustomerCode、CheckWord、MonthlyAccount 并补充到本文档
  • [ ] 对接顺丰路由查询接口（EXP_RECE_SEARCH_ROUTES），获取物流轨迹
  • [ ] 对接顺丰拦截查询，获取拦截时间、拦截状态
  • [ ] 在 wt_kdljjl 表中新增"退回单号"字段
  • [ ] 实现通过快递单号自动查询并填充拦截信息