对外接口文档

版本：1.3
更新日期：2026-09-08

测试域名：https://test.yunpsk.com

1. 鉴权方式

所有接口（注册接口除外）通过 URL Query Parameter 传递鉴权信息：

参数	类型	必填	说明
`appKey`	String	是	平台分配的应用Key
`timestamp`	String	是	Unix时间戳（秒或毫秒），5分钟内有效
`sign`	String	是	HMAC-SHA256 签名

签名规则

将所有参数（除 sign 外）按 key 字典序排序
拼接为 key1value1key2value2... 格式
如有 JSON body，计算 body 的 SHA-256 哈希，追加 bodyHash{hash值}
使用 HMAC-SHA256(appSecret, 拼接字符串) 计算签名
结果转为小写 hex 字符串

签名示例（Java）

java

TreeMap<String, String> params = new TreeMap<>();
params.put("appKey", "your_app_key");
params.put("timestamp", String.valueOf(System.currentTimeMillis() / 1000));
String sign = PlatformSignUtil.generateSign(params, appSecret, bodyHash);

2. 统一响应格式

json

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

错误码说明

范围	说明
0	成功
-1	通用错误
9001-9006	鉴权错误
2001-2005	订单/注册错误
3001	门店错误
4001-4004	财务/平台配置错误
5001-5003	支付/余额查询错误

详细错误码

错误码	说明	使用场景
9001	签名验证失败	鉴权
9002	timestamp已过期或格式错误	鉴权
9003	appKey无效或平台已禁用	鉴权
9004	缺少必要参数	鉴权
9006	该平台已暂停接单	鉴权
2001	订单不存在 / platformCode已存在	订单查询/注册
2002	订单状态不允许操作 / 手机号已注册	订单操作/注册
2003	订单号重复 / 追加金额必须大于0	订单创建/加小费
2004	询价失败 / 余额不足	询价/加小费
2005	下单失败 / 并发提交冲突	订单创建
3001	门店不存在 / 平台配置不存在	门店/骑手查询
4001	余额不足	扣款
4002	充值金额必须大于0	充值
4004	平台配置不存在或未绑定商户	财务/门店
5001	创建支付失败	充值
5002	生成二维码失败	充值
5003	查询余额失败	余额查询

3. 订单接口

3.1 门店询价

POST /api/platformA/order/storeInquiry

根据门店地址和收件地址计算配送费和预计送达时间。

请求参数（JSON Body）：

参数	类型	必填	说明
thirdStoreId	String	是	三方门店ID
recipientName	String	是	收件人姓名
recipientPhone	String	是	收件人电话
recipientAddress	String	是	收件人地址
recipientLng	String	是	收件人经度
recipientLat	String	是	收件人纬度
totalWeight	Integer	否	物品重量(千克)
businessType	Integer	否	业务类型（1=帮送, 2=帮买, 3=万能服务，4=帮取，5=1对1专送），默认1
prebook	Integer	否	是否即时单（0=即时单，1=预约单），默认0
expectedPickupTime	Long	否	预计取件时间（Unix时间戳秒），预约单必填

响应参数：

参数	类型	说明
predictDeliveryTime	Long	预计送达时间（Unix时间戳秒）
actualFee	Double	预计收入金额(元)
deliveryFee	Double	配送费用(元)
deliveryDistance	Double	配送距离(公里)

请求示例：

json

{
  "thirdStoreId": "STORE_001",
  "recipientName": "张三",
  "recipientPhone": "13800138000",
  "recipientAddress": "北京市朝阳区建国路88号",
  "recipientLng": "116.461",
  "recipientLat": "39.908",
  "totalWeight": 1000,
  "businessType": 1,
  "prebook": 0
}

响应示例：

json

{
  "code": 0,
  "message": "success",
  "data": {
    "predictDeliveryTime": 1693500000,
    "actualFee": 12.50,
    "deliveryFee": 12.50,
    "deliveryDistance": 5.2
  }
}

3.2 地址询价

POST /api/platformA/order/addressInquiry

根据发件地址和收件地址计算配送费和预计送达时间。

请求参数（JSON Body）：

参数	类型	必填	说明
senderLng	String	是	发件人经度
senderLat	String	是	发件人纬度
recipientLng	String	是	收件人经度
recipientLat	String	是	收件人纬度
totalWeight	Integer	否	物品重量(千克)
businessType	Integer	否	业务类型，默认1
prebook	Integer	否	是否即时单，默认0
expectedPickupTime	Long	否	预计取件时间（Unix时间戳秒）

响应参数： 同门店询价

3.3 创建订单（简易版）

POST /api/platformA/order/create

创建配送订单，不包含定价计算。适用于已有自己的定价逻辑、只需系统配送的场景。

请求参数（JSON Body）：

参数	类型	必填	说明
thirdOrderId	String	是	三方订单号（幂等键，重复提交返回相同结果）
senderName	String	是	发件人姓名
senderPhone	String	是	发件人电话
senderAddress	String	是	发件人地址
senderLng	String	否	发件人经度
senderLat	String	否	发件人纬度
receiverName	String	是	收件人姓名
receiverPhone	String	是	收件人电话
receiverAddress	String	是	收件人地址
receiverLng	String	否	收件人经度
receiverLat	String	否	收件人纬度
itemDescription	String	否	物品描述
itemWeight	String	否	物品重量(千克)
remark	String	否	订单备注
callbackUrl	String	否	订单状态回调地址，传入后会自动更新平台配置

响应参数：

参数	类型	说明
orderId	String	内部订单ID
thirdOrderId	String	三方订单号
status	Integer	订单状态（2=已支付待接单）
statusDesc	String	状态描述
createTime	String	创建时间

业务规则：

thirdOrderId 为幂等键，重复提交返回相同订单
不包含定价计算，配送费由调用方自行确定
如需系统自动定价，请使用门店下单或地址下单接口

3.4 门店下单

POST /api/platformA/order/createStoreOrder

基于门店地址创建配送订单，取件地址从门店获取，包含定价计算。

请求参数（JSON Body）：

参数	类型	必填	说明
thirdOrderId	String	是	三方订单号（幂等键，重复提交返回相同结果）
thirdStoreId	String	是	三方门店ID
recipientName	String	是	收件人姓名
recipientPhone	String	是	收件人电话
recipientAddress	String	是	收件人地址
recipientLng	String	是	收件人经度
recipientLat	String	是	收件人纬度
totalWeight	Integer	否	物品重量(千克)
goodsDetails	String	否	物品明细(JSON格式)
businessType	Integer	否	业务类型，默认1
prebook	Integer	否	是否即时单，默认0
expectedPickupTime	Long	否	预计取件时间（Unix时间戳秒）
tipFee	Double	否	小费(元)
orderRemark	String	否	订单备注
callbackUrl	String	否	订单状态回调地址，传入后会自动更新平台配置

响应参数：

参数	类型	说明
orderId	String	内部订单ID
thirdOrderId	String	三方订单号
status	Integer	订单状态（2=已支付待接单）
statusDesc	String	状态描述
deliveryFee	Double	配送费用(元)
deliveryDistance	Double	配送距离(公里)
predictDeliveryTime	Long	预计送达时间（Unix时间戳秒）

请求示例：

json

{
  "thirdOrderId": "ORD_20260831_001",
  "thirdStoreId": "STORE_001",
  "recipientName": "李四",
  "recipientPhone": "13900139000",
  "recipientAddress": "北京市海淀区中关村大街1号",
  "recipientLng": "116.310",
  "recipientLat": "39.956",
  "totalWeight": 500,
  "goodsDetails": "[{\"name\":\"文件\",\"count\":1}]",
  "businessType": 1,
  "tipFee": 5.0,
  "orderRemark": "请尽快送达"
}

响应示例：

json

{
  "code": 0,
  "message": "success",
  "data": {
    "orderId": "202608310001",
    "thirdOrderId": "ORD_20260831_001",
    "status": 2,
    "statusDesc": "已支付待接单",
    "deliveryFee": 15.0,
    "deliveryDistance": 8.5,
    "predictDeliveryTime": 1693503600
  }
}

业务规则：

thirdOrderId 为幂等键，重复提交返回相同订单
需先调用询价接口获取配送费
系统会自动从门店获取取件地址

3.5 地址下单

POST /api/platformA/order/createAddressOrder

基于发件地址创建配送订单，发件和收件地址都从请求获取，包含定价计算。

请求参数（JSON Body）：

参数	类型	必填	说明
thirdOrderId	String	是	三方订单号（幂等键）
senderLng	String	是	发件人经度
senderLat	String	是	发件人纬度
senderAddress	String	否	发件人地址
senderName	String	否	发件人姓名
senderPhone	String	否	发件人电话
recipientName	String	是	收件人姓名
recipientPhone	String	是	收件人电话
recipientAddress	String	是	收件人地址
recipientLng	String	是	收件人经度
recipientLat	String	是	收件人纬度
totalWeight	Integer	否	物品重量(千克)
goodsDetails	String	否	物品明细(JSON格式)
businessType	Integer	否	业务类型，默认1
prebook	Integer	否	是否即时单，默认0
expectedPickupTime	Long	否	预计取件时间（Unix时间戳秒）
tipFee	Double	否	小费(元)
orderRemark	String	否	订单备注
callbackUrl	String	否	订单状态回调地址，传入后会自动更新平台配置

响应参数： 同门店下单

业务规则：

与门店下单类似，但发件地址从请求获取
适用于非门店场景的点对点配送

3.6 取消订单

POST /api/platformA/order/cancel

取消指定订单。

请求参数（JSON Body）：

参数	类型	必填	说明
thirdOrderId	String	是	三方订单号
cancelReason	String	否	取消原因

响应参数：

参数	类型	说明
orderId	String	内部订单ID
thirdOrderId	String	三方订单号
status	Integer	订单状态（1=已取消）
statusDesc	String	状态描述

业务规则：

已取消的订单重复调用返回成功（幂等）
只有 status ≤ 4 的订单可取消
已支付的订单会自动退款

3.7 查询取消费用

POST /api/platformA/order/queryCancelFee

取消订单前预览取消费用，用于向用户展示取消影响。

请求参数（JSON Body）：

参数	类型	必填	说明
thirdOrderId	String	是	三方订单号

响应参数：

参数	类型	说明
thirdOrderId	String	三方订单号
cancelFee	Double	取消费用(元)
refundAmount	Double	预计退款金额(元)
reason	String	费用说明

业务规则：

取消费用根据订单状态和时间计算
与实际取消接口使用相同的罚金计算逻辑
仅用于预览，不会实际取消订单

3.8 加小费

POST /api/platformA/order/addTip

为已有订单追加小费，小费金额累计叠加。

请求参数（JSON Body）：

参数	类型	必填	说明
thirdOrderId	String	是	三方订单号
tipFee	Double	是	小费金额(元)，必须大于0

响应参数：

参数	类型	说明
orderId	String	内部订单ID
thirdOrderId	String	三方订单号
tipFee	Double	本次小费金额(元)
totalPrice	Double	订单总金额(元，含小费)

业务规则：

小费为累加模式，多次调用会叠加
支付方式：预充值余额优先，不足部分走信用扣款
使用行级锁保证并发安全
骑手佣金会同步更新

3.9 查询订单

GET /api/platformA/order/query?thirdOrderId={thirdOrderId}

查询单个订单详情。

请求参数（Query）：

参数	类型	必填	说明
thirdOrderId	String	是	三方订单号

响应参数：

参数	类型	说明
orderId	String	内部订单ID
thirdOrderId	String	三方订单号
status	Integer	订单状态
statusDesc	String	状态描述
riderName	String	骑手姓名
riderPhone	String	骑手电话
createTime	String	创建时间
grabTime	String	接单时间
pickupTime	String	取件时间
deliverTime	String	送达时间
totalPrice	BigDecimal	订单总金额
senderName	String	发件人姓名
senderPhone	String	发件人电话
senderAddress	String	发件人地址
receiverName	String	收件人姓名
receiverPhone	String	收件人电话
receiverAddress	String	收件人地址

3.10 查询订单列表

GET /api/platformA/order/list?status={status}&page={page}&pageSize={pageSize}

分页查询订单列表。

请求参数（Query）：

参数	类型	必填	说明
status	Integer	否	订单状态筛选
page	Integer	否	页码，默认1
pageSize	Integer	否	每页条数，默认20

响应参数：

参数	类型	说明
list	Array	订单列表
total	Long	总条数
page	Integer	当前页码
pageSize	Integer	每页条数

4. 门店接口

4.1 创建门店

POST /api/platformA/store/create

创建新门店。

请求参数（JSON Body）：

参数	类型	必填	说明
thirdStoreId	String	是	三方门店ID
storeName	String	是	门店名称
storePhone	String	是	门店电话
storeAddress	String	是	门店地址
storeLng	String	否	门店经度
storeLat	String	否	门店纬度
contactName	String	否	联系人姓名
contactPhone	String	否	联系人电话

响应参数：

参数	类型	说明
storeId	Long	内部门店ID
thirdStoreId	String	三方门店ID（即内部门店ID）
storeName	String	门店名称

业务规则：

thirdStoreId 由调用方指定，作为门店的唯一标识
重复创建相同 thirdStoreId 的门店返回已有门店信息（幂等）
创建成功后，后续下单接口可通过该 thirdStoreId 使用门店取件地址

4.2 查询门店

GET /api/platformA/store/query?thirdStoreId={thirdStoreId}

查询门店详情。

响应参数：

参数	类型	说明
storeId	Long	内部门店ID
thirdStoreId	String	三方门店ID
storeName	String	门店名称
storePhone	String	门店电话
storeAddress	String	门店地址
status	Integer	门店状态（0=待审核，1=正常，2=审核失败）
createTime	String	创建时间

4.3 修改门店

POST /api/platformA/store/modify

修改门店信息。

请求参数（JSON Body）：

参数	类型	必填	说明
thirdStoreId	String	是	三方门店ID
storeName	String	否	门店名称
storePhone	String	否	门店电话
storeAddress	String	否	门店地址
status	Integer	否	门店状态

响应参数：

参数	类型	说明
storeId	Long	内部门店ID
thirdStoreId	String	三方门店ID
storeName	String	门店名称
updateTime	String	更新时间

5. 骑手接口

5.1 查询骑手

GET /api/platformA/rider/query?thirdOrderId={thirdOrderId}

根据订单号查询该订单分配的骑手信息。

请求参数（Query）：

参数	类型	必填	说明
thirdOrderId	String	是	三方订单号

响应参数：

参数	类型	说明
riderId	Long	骑手ID
name	String	骑手姓名
phone	String	骑手电话
avatarUrl	String	头像URL
orderStatus	Integer	接单状态（1=接单中，其他=休息中）
orderStatusDesc	String	状态描述
totalOrders	Integer	总订单数
city	String	所在城市
lng	Double	骑手经度（实时位置）
lat	Double	骑手纬度（实时位置）

6. 财务接口

6.1 充值

POST /api/platformA/finance/recharge

为三方平台商户账户充值，系统生成微信Native支付二维码。

请求参数（JSON Body）：

参数	类型	必填	说明
amount	BigDecimal	是	充值金额(元)，必须大于0
thirdTradeNo	String	是	三方交易流水号
remark	String	否	备注

响应参数：

参数	类型	说明
rechargeNo	String	充值单号（用于查询状态）
qrCodeUrl	String	微信Native支付二维码图片URL（OSS地址，30分钟有效）

请求示例：

json

{
  "amount": 100.00,
  "thirdTradeNo": "TRADE_20260908_001",
  "remark": "商户充值"
}

响应示例：

json

{
  "code": 0,
  "message": "success",
  "data": {
    "rechargeNo": "RCH1788831662639256",
    "qrCodeUrl": "https://your-bucket.oss-cn-xxx.aliyuncs.com/qrcode/recharge/RCH1788831662639256.png?Expires=..."
  }
}

业务规则：

生成微信Native支付二维码，用户微信扫码支付
二维码URL有效期30分钟，过期需重新发起充值
支付成功后系统自动回调加钱到商户钱包
无需额外配置回调地址，系统自动处理

6.2 查询余额

GET /api/platformA/finance/balance

查询三方平台商户账户余额。

响应参数：

参数	类型	说明
balance	BigDecimal	账户余额(元)
freezeAmount	BigDecimal	冻结金额(元)
availableAmount	BigDecimal	可用余额(元)

7. 订单状态码

状态码	说明
1	已取消
2	已支付待接单
3	已接单待到店
4	已到店待取件
5	已取件配送中
6	已送达
7	已完成

8. 回调机制

订单状态变更时，系统会主动回调三方平台。

回调配置

在 platform_config 表中配置 callbackUrl 字段。

回调请求

Content-Type: application/json

请求头：

Header	说明
`X-Callback-Id`	回调ID，用于幂等去重
`X-Timestamp`	时间戳（秒）
`X-Sign`	HMAC-SHA256 签名（签名规则同鉴权，对 body 做 SHA-256 后参与签名）

请求体：

json

{
  "callbackId": "回调ID",
  "orderNo": "内部订单号",
  "orderId": "内部订单ID",
  "thirdOrderNo": "三方订单号",
  "status": 6,
  "statusDesc": "已送达",
  "riderName": "骑手姓名",
  "riderPhone": "骑手电话",
  "callbackTime": "2026-08-31 15:30:00"
}

回调响应

三方平台需返回 {"code": 0} 表示接收成功。

重试机制

最多重试 5 次
间隔递增：1分钟, 5分钟, 15分钟, 30分钟, 60分钟
首次回调后超过 1 小时停止重试
超过重试次数后记录日志

对外接口文档 ​

1. 鉴权方式 ​

签名规则 ​

签名示例（Java） ​

2. 统一响应格式 ​

错误码说明 ​

详细错误码 ​

3. 订单接口 ​

3.1 门店询价 ​

3.2 地址询价 ​

3.3 创建订单（简易版） ​

3.4 门店下单 ​

3.5 地址下单 ​

3.6 取消订单 ​

3.7 查询取消费用 ​

3.8 加小费 ​

3.9 查询订单 ​

3.10 查询订单列表 ​

4. 门店接口 ​

4.1 创建门店 ​

4.2 查询门店 ​

4.3 修改门店 ​

5. 骑手接口 ​

5.1 查询骑手 ​

6. 财务接口 ​

6.1 充值 ​

6.2 查询余额 ​

7. 订单状态码 ​

8. 回调机制 ​

回调配置 ​

回调请求 ​

回调响应 ​

重试机制 ​

对外接口文档

1. 鉴权方式

签名规则

签名示例（Java）

2. 统一响应格式

错误码说明

详细错误码

3. 订单接口

3.1 门店询价

3.2 地址询价

3.3 创建订单（简易版）

3.4 门店下单

3.5 地址下单

3.6 取消订单

3.7 查询取消费用

3.8 加小费

3.9 查询订单

3.10 查询订单列表

4. 门店接口

4.1 创建门店

4.2 查询门店

4.3 修改门店

5. 骑手接口

5.1 查询骑手

6. 财务接口

6.1 充值

6.2 查询余额

7. 订单状态码

8. 回调机制

回调配置

回调请求

回调响应

重试机制