第三方开放平台 - 订单接口接入文档

版本记录

版本号	更新日期	更新内容	更新人
v1.0	2026-05-22	初始版本	技术部

一、概述

本文档为第三方系统接入我方供应链开放平台提供详细说明。通过本文档，第三方开发者可以了解如何：

进行接口签名和验签

调用供应链开放平台相关接口

处理回调通知

排查常见问题

适用对象

第三方系统开发者

渠道商技术对接人员

接口协议

协议: HTTPS

数据格式: JSON

字符编码: UTF-8

二、接入准备

2.1 获取接入凭证

接入前需要向我方申请以下信息:

businessId: 商户编号(用于身份标识)

RSA公钥: 用于请求验签(请妥善保管)

2.2 生成 RSA 密钥对

如果您还没有 RSA 密钥对，请前往渠道商平台获取私钥。

注意事项

平台生成的公钥会自动帮用户配置，用户请在平台下载私钥。

如果您的代码（如 Java 的 BASE64Decoder）需要直接读取私钥文件，则私钥文件也必须进行清理头尾标识。

删除 -----BEGIN PUBLIC KEY-----

删除 -----END PUBLIC KEY-----

只保留中间的 Base64 编码内容

私钥安全：私钥文件请妥善保管，不要泄露给他人。

2.2 环境配置

环境	基础URL
生产环境	https://zhiyu.mid.aiteyixia.cn

三、签名规则

3.1 签名机制说明

所有接口调用都需要进行签名验证，以确保请求的完整性和安全性。我方采用 RSA + MD5 的签名方式。

3.2 请求 Header 参数

调用接口时，需要在 HTTP 请求头中携带以下参数：

参数名	类型	必填	说明	示例
Signature-Type	String	否	签名类型，默认为 RSA	RSA
Timestamp	Long	是	请求时间戳（毫秒），与服务器时间误差需在 ±5分钟内	1716364800000
Signature-Data	String	是	签名数据(请查看签名规则)	a1b2c3d4e5f6...
businessId	String	是	商户编号	C11112033827767895863296

3.3 签名计算步骤

步骤	操作
步骤 1	将请求参数对象转换为 JSON 字符串
步骤 2	对 JSON 字符串进行 MD5 加密
步骤 3	使用 RSA 私钥对 MD5 值进行签名
步骤 4	将签名结果进行 Base64 编码
步骤 5	将签名数据放入请求 Header 的 `Signature-Data` 字段

GET 请求签名规范

1. 签名规则

GET 请求，签名对象是 URL 查询参数的原始值。

本例场景：将 orderSn 参数值（即 orderId 字符串）作为原始数据进行签名(目前仅有单参数的为get请求)

核心原则：直接使用参数的原始字符串值，不进行任何额外处理

注意：对于不需要参数的请求，请将 businessId 的原始数据进行签名

2. GET 签名流程

提取查询参数值 → 使用RSA私钥签名 → Base64编码
示例代码：

// 1. 获取参数原始值 
String orderId = "ORD20250615001";
// 2. 使用RSA私钥进行SHA256withRSA签名 
PrivateKey privateKey = loadPrivateKey(THIRD_PRIVATE_KEY_PATH); 
String signature = signByPrivateKey(privateKey, orderId);

3.4 Java 签名示例代码

以下示例展示 POST 接口签名和调用方式：

GET 接口签名示例：

四、通用响应格式

4.1 返回值统一声明

所有接口的返回值都遵循统一的格式：
返回结果为JSON格式，该文档主要对一些公共参数做简要说明，公共参数在具体的API文档中后续将不再进行复述，在每个接口的API文档中，将仅针对data字段做详细说明。

4.2 字段说明

字段	类型	说明
code	Integer	状态码，20000-成功，其他-失败
message	String	响应消息描述
data	Object	业务数据，具体结构见各接口说明

4.3 状态码说明

通用状态码

状态码	说明	处理建议
20000	请求成功	-
20006	参数错误	检查请求参数格式和必填项
20008	签名验证失败	检查签名算法和密钥配置
20010	参数无效	检查参数值的合法性
20011	参数已存在	检查是否重复提交（幂等性）

用户相关状态码

状态码	说明	处理建议
30003	该用户不存在	检查商户编码（businessId）是否正确

商品相关状态码

状态码	说明	处理建议
40000	商品不存在	检查商品ID是否在系统中
40001	商品状态异常	检查商品上架状态和库存
40041	选品分组不存在	检查分组ID是否正确

订单相关状态码

状态码	说明	处理建议
50002	订单已存在	检查订单号是否重复提交
50003	创建订单失败	联系技术支持排查系统问题
50004	订单状态异常	检查订单当前状态是否符合操作要求
50006	账户余额不足	充值后重新下单
50008	下单分账失败	检查账号余额或联系技术支持排查分账服务
50010	订单不存在	检查订单号是否正确
50012	地址不可达	检查收货地址是否在配送范围内
50013	售后状态异常	检查售后单当前状态是否符合操作要求
50016	售后记录不存在	检查售后单ID是否正确
50017	订单已存在	检查订单号是否重复提交

其他相关状态码

状态码	说明	触发条件	处理建议
90001	手机号输入有误	检查收货人电话格式是否正确
90004	第N张图片大小超过限制（最大5MB）	单张图片 > 5MB	压缩图片后重新上传（推荐压缩至 2-3MB）
90005	图片上传失败，第N张	OSS 上传返回空 URL	检查网络连接，稍后重试

状态码分类规则：

20xxx：通用状态码（签名、参数等）

30xxx：用户模块

40xxx：商品模块

50xxx：订单模块

90xxx：其他工具模块

第三方接口特殊说明：

所有接口均需进行签名验证（Signature-Type、Timestamp、Signature-Data）

时间戳发送时间内5分钟，过期将返回签名验证失败

部分接口支持幂等性控制，避免重复提交

订单相关操作需传递 businessId（商户编码）进行身份识别

处理建议：

客户端收到错误状态码后，应优先检查请求参数和签名

签名验证失败（20008）需检查密钥配置和签名算法

业务逻辑错误应根据具体提示调整请求参数

所有错误响应均包含详细错误信息，便于定位问题

公共信息

第三方开放平台 - 订单接口接入文档#

版本记录#

一、概述#

适用对象#

接口协议#

二、接入准备#

2.1 获取接入凭证#

2.2 生成 RSA 密钥对#

注意事项#

2.2 环境配置#

三、签名规则#

3.1 签名机制说明#

3.2 请求 Header 参数#

3.3 签名计算步骤#

GET 请求签名规范#

1. 签名规则#

2. GET 签名流程#

3.4 Java 签名示例代码#

四、通用响应格式#

4.1 返回值统一声明#

4.2 字段说明#

4.3 状态码说明#

通用状态码#

用户相关状态码#

商品相关状态码#

订单相关状态码#

其他相关状态码#