接口规则

接口概述

本文档定义了数字农人开放平台面向 服务商 / KA 商户 的 API 接口规范。服务商可通过调用平台接口，将相关能力集成至自有或第三方业务系统。

适用对象

已完成数字农人开放平台入驻的服务商及 KA 商户。

业务时序图

B2C（收购企业采购农产品）

B2C（收购企业采购农产品）主要适用于采购企业收购农产品场景。

在该场景中，采购企业需先在数字农人平台注册成为 B2C 场景的采购商，并开通微众银行和乐企联用。随后，采购企业向自然人支付农产品收购款，农户确认收款（也可授权免确认）后，系统自动开具农产品收购发票。

B2C 业务时序图

B2S（收购企业销售农产品）

B2S（收购企业销售农产品）主要适用于收购企业销售农产品场景。

在该场景中，收购企业已在数字农人平台注册成为 B2C 场景的采购商，并已开通微众银行和乐企联用。购买方企业通过线上打款到收购企业的微众公户，系统基于收购企业的微众银行收款流水进行充值记账。随后，购买方企业线上下单，收购企业完成记账扣款并同步开具销售发票。

B2S 业务时序图

B2B（自产农产品销售）

B2B（自产农产品销售）主要适用于小微企业（合作社、集体户等）自产农产品销售场景。

在该场景中，采购企业已在数字农人平台注册成为采购商，并开通微众银行。小微企业通过数字农人开通乐企联用，以具备自产农产品销售能力。系统通过采购企业线下确认货物、线上下单支付，小微企业自动完成收款并开具自产农产品销售发票。

B2B 业务时序图

签名加密

为保证接口请求的完整性与防篡改，平台采用 国密 SM2 非对称加密 及签名验签机制。

整体流程

请求参数 SM2 加密 → 拼接签名字符串 → SM2 私钥签名 → 发送请求 → SM2 解密响应

公共参数

以下参数需统一放入请求 Headers 中：

参数名	类型	必填	说明
`timestamp`	String	是	当前系统时间戳
`serviceid`	String	是	服务商 ID，由数农开放平台分配
`appid`	String	是	应用 ID
`sign`	String	是	请求签名（SM2）

密钥配置

平台与服务商之间采用 双向公钥交换：

方向	操作	用途
服务商 → 平台	服务商提供公钥给平台	平台用于验签和加密响应数据
平台 → 服务商	平台提供公钥给服务商	服务商用于参数加密

参数加密

请求参数需使用 平台公钥 进行 SM2 加密后传输：

① 准备原始参数（JSON 格式）：

json

{"a": "A", "b": "B"}

② 使用平台公钥进行 SM2 加密，得到密文：

text

BHMqkVfDKyf66xfbX2xYpW8s6IirfsJ8sPmhpRMzlxVM...

③ 将密文放入请求 body 的 data 字段：

json

{
  "data": "BHMqkVfDKyf66xfbX2xYpW8s6IirfsJ8sPmhpRMzlxVM..."
}

平台侧处理

平台收到请求后，使用平台私钥进行 SM2 解密获取原始参数。

请求签名

签名字符串按以下规则 顺序拼接：

text

{请求路径}{时间戳}serviceid={服务商ID}appid={应用ID}sm2={加密后参数}

示例：

要素	值
请求路径	`/open-api/customer/test`
时间戳	`1744363006`
服务商 ID	`10002`
应用 ID	`sna19a2hnsefjc8o3h`

拼接结果：

text

/open-api/customer/test1744363006serviceid=10002appid=sna19a2hnsefjc8o3hsm2=BHMqkVfDKyf66xfb...

使用服务商 SM2 私钥对该字符串签名，将签名结果放入 Headers 的 sign 字段。平台使用服务商公钥进行验签。

小程序跳转签名

用于小程序跳转场景，签名规则与接口签名略有不同 — 请求路径替换为跳转路径，加密数据替换为外部 ID：

text

{跳转路径}{时间戳}serviceid={服务商ID}appid={应用ID}sm2={外部ID}

示例：

text

/pages/authentication/personAuth1744363006serviceid=10002appid=sna19a2hnsefjc8o3hsm2=123456

响应结果解密

所有接口响应中 data 字段均为 SM2 加密密文，需使用平台提供的公钥进行解密。

加密响应：

json

{
  "msg": "成功",
  "code": 200,
  "data": "BGjXwXHoFKpz7fd47c7RCrPL9DQDVNw551aE/ON1GWgb..."
}

解密后：

json

{
  "msg": "成功",
  "code": 200,
  "data": {
    "status": "NOT_AUDIT"
  }
}

接入指引

接口规范

项目	规范
传输协议	HTTPS，确保数据传输安全
请求方式	POST，Content-Type 为 `application/json`（除接口特别说明外）
字符编码	UTF-8（除接口特别说明外）

环境信息

环境	域名地址
测试环境	`https://sn-gateway-test.gc365.com/sznr-v2`
生产环境	`https://sn-gateway.gc365.com/sznr-v2`

注意

测试环境与生产环境的数据完全隔离，请勿混用。上线前请确保已切换至生产环境域名。

SDK 接入

平台提供 Java SDK，封装了请求签名、SM2 加解密等底层逻辑，开发者无需关注加密细节，直接调用业务方法即可。

环境要求

JDK 1.8+
Maven 3.x

安装依赖

下载 SDK JAR 包并引入项目：

v1.3.3 2026-05-07 下载 sznr-sdk-java-1.3.3.jar

新增下单前查询需要上传的证明材料接口
创建采购订单支持采购商员工手机号、转账备注，以及按证明类型指定需要上传的农户证明材料

v1.3.1 2026-04-29 下载 sznr-sdk-java-1.3.1.jar

查询服务商资金明细接口新增关联业务单号字段

v1.3.0 2026-04-21 下载 sznr-sdk-java-1.3.0.jar

增加 B2B 接口
优化 B2C 接口

v1.2.1 2026-04-16 下载 sznr-sdk-java-1.2.1.jar

优化查询农户数农码返回字段

v1.2.0 2026-04-13 下载 sznr-sdk-java-1.2.0.jar

订单红冲结果接口问题修复
新增批量查询农户数农码接口

v1.1.8 2026-04-10 下载 sznr-sdk-java-1.1.8.jar

B2C 取消订单接口参数调整

v1.1.7 2026-04-07 下载 sznr-sdk-java-1.1.7.jar

发票类接口请求参数和响应字段与服务端对齐
红冲接口参数调整为 reasonEnum / reason
红冲结果查询响应字段更新

v1.1.5 2026-03-20 下载 sznr-sdk-java-1.1.5.jar

新增批量发票查询下载接口

v1.1.4 2026-03-18 下载 sznr-sdk-java-1.1.4.jar

修复查询企业账户余额参数

v1.1.3 2026-03-17 下载 sznr-sdk-java-1.1.3.jar

修正企业注册参数

v1.1.2 2026-03-16 下载 sznr-sdk-java-1.1.2.jar

查询农户数农码调用方法更新为 B2CSupplier.querySupplierInfo
新增企业注册审核结果回调

v1.1.1 2026-03-11 下载 sznr-sdk-java-1.1.1.jar

查询企业注册结果新增字段 industryEndTime
新增邀请企业绑定应用接口

v1.1.0 2026-03-06 下载 sznr-sdk-java-1.1.0.jar

新增查询事中风控事件结果、查询事后风控事件结果接口
新增事中风控事件回调、事后风控事件回调

方式一：上传至私有 Maven 仓库（推荐）

将 JAR 包部署到企业私服后，在 pom.xml 中直接引用：

xml

<dependency>
    <groupId>com.gc365.sznr</groupId>
    <artifactId>sznr-sdk-java</artifactId>
    <version>1.3.3</version>
</dependency>

方式二：安装到本地 Maven 仓库

通过 mvn install:install-file 命令将 JAR 包安装到本地仓库：

bash

mvn install:install-file \
  -Dfile=sznr-sdk-java-1.3.3.jar \
  -DgroupId=com.gc365.sznr \
  -DartifactId=sznr-sdk-java \
  -Dversion=1.3.3 \
  -Dpackaging=jar

安装完成后，在 pom.xml 中正常引用即可：

xml

<dependency>
    <groupId>com.gc365.sznr</groupId>
    <artifactId>sznr-sdk-java</artifactId>
    <version>1.3.3</version>
</dependency>

方式三：本地 JAR 引入

将下载的 JAR 文件放入项目的 lib 目录，并在 pom.xml 中添加本地依赖：

xml

<dependency>
    <groupId>com.gc365.sznr</groupId>
    <artifactId>sznr-sdk-java</artifactId>
    <version>1.3.3</version>
    <scope>system</scope>
    <systemPath>${project.basedir}/lib/sznr-sdk-java-1.3.3.jar</systemPath>
</dependency>

初始化配置

在应用启动时完成一次性配置，后续所有 API 调用自动使用该配置：

java

import com.gc365.sznr.sdk.config.EntpayConfig;
import com.gc365.sznr.sdk.config.EnvironmentEnum;

// SM2 密钥（请替换为实际分配的密钥）
String platformPublicKey  = "04940...（平台公钥，SM2 十六进制，65字节）";
String appid              = "sna19a2hnsefjc8o2h";
String servicePublicKey   = "04e9d...（服务商公钥，SM2 十六进制，65字节）";
String servicePrivateKey  = "96427...（服务商私钥，SM2 十六进制，32字节）";

// 初始化
EntpayConfig.setNormalMode(
    9000L,                // 服务商 ID
    appid,                // 应用 ID
    platformPublicKey,    // 平台公钥
    servicePublicKey,     // 服务商公钥
    servicePrivateKey     // 服务商私钥
);

// 设置环境（SANDBOX 测试环境 / PRODUCTION 生产环境）
EntpayConfig.setEnv(EnvironmentEnum.SANDBOX);

调用示例

以 创建采购订单 为例：

java

import com.gc365.sznr.sdk.api.b2c.B2COrders;
import com.gc365.sznr.sdk.model.b2c.OrdersCreateV2Param;
import com.gc365.sznr.sdk.model.b2c.OrdersCreateV2Param.NeedProofsAndCertificates;
import com.gc365.sznr.sdk.model.b2c.OrdersCreateV2Param.Product;
import com.gc365.sznr.sdk.model.b2c.OrdersCreateV2;
import com.gc365.sznr.sdk.exception.SznrException;
import java.math.BigDecimal;
import java.util.Collections;

// 构建商品
Product product = Product.builder()
    .goodTypeNames("畜禽产品>生皮>生牛皮")
    .productManagementName("生牛皮")
    .expectNumber(new BigDecimal("100"))
    .expectUnits("斤")
    .expectUnitPrice(new BigDecimal("5.00"))
    .expectPrice(new BigDecimal("500.00"))
    .taxRate(new BigDecimal("0.09"))
    .qualitySpec("一级品")
    .postMode(0)
    .purchaseDistrictId("330102")
    .purchaseAddress("浙江省杭州市上城区某某街道123号")
    .demand("新鲜采摘，当日配送")
    .build();

// 构建请求参数
OrdersCreateV2Param param = OrdersCreateV2Param.builder()
    .businessNo("BIZ" + System.currentTimeMillis())
    .snCode("SN123456")
    .customerName("XX食品有限公司")
    .customerUscc("91990101000032766Y")
    .payMode(1)
    .totalPrice(new BigDecimal("500.00"))
    .products(Collections.singletonList(product))
    .invoiceRemark("测试发票备注")
    .transferRemark("测试转账备注")
    .needProofsAndCertificates(NeedProofsAndCertificates.builder()
        .selfProducedCertificate(false)
        .build())
    .build();

try {
    OrdersCreateV2 result = B2COrders.createV2(param);
    System.out.println("订单号: " + result.getPurchaseOrderNo());
} catch (SznrException e) {
    System.err.println("请求失败: " + e.getMessage());
}

回调验签

当业务状态变更时，平台会主动推送回调通知。服务商需提供一个 HTTP 接口接收回调，并使用 SDK 进行验签：

java

import com.gc365.sznr.sdk.notify.NotifyHandler;
import com.gc365.sznr.sdk.notify.NotifyModel;
import com.gc365.sznr.sdk.config.EntpayConfig;

@ResponseBody
@PostMapping("/callback-notify")
public String callbackNotify(
        @RequestBody String body,
        @RequestHeader("sign") String sign,
        @RequestHeader("timestamp") String timestamp) throws Exception {

    // 验签并解析回调数据（body 必须是原始报文，不可预处理）
    String path = "/callback-notify";
    NotifyModel model = NotifyHandler.handlerWebhook(
        body, sign,
        EntpayConfig.getServiceId(),
        EntpayConfig.getAppid(),
        path, timestamp,
        NotifyModel.class,
        EntpayConfig.getPlatformPublicKey()
    );

    // 获取业务数据
    String data = model.getData();

    // TODO 执行业务逻辑

    // 返回成功响应
    return "{\"code\":0,\"message\":\"SUCCESS\"}";
}

注意

回调验签时，body 参数必须是接收到的 原始报文，不可提前进行反序列化、排序等操作，否则会导致验签失败。

注册类接口

订单类接口

发票类接口

账户类接口

服务商账户接口

风控接口

业务回调

订单类接口

发票类接口

订单类接口

发票类接口

账户类接口

接口规则

接口概述

业务时序图

B2C（收购企业采购农产品）

B2S（收购企业销售农产品）

B2B（自产农产品销售）

签名加密

公共参数

密钥配置

参数加密

请求签名

响应结果解密

接入指引

接口规范

环境信息

SDK 接入

环境要求

安装依赖

初始化配置

调用示例

回调验签

接口规则 ​

接口概述 ​

业务时序图 ​

B2C（收购企业采购农产品） ​

B2S（收购企业销售农产品） ​

B2B（自产农产品销售） ​

签名加密 ​

公共参数 ​

密钥配置 ​

参数加密 ​

请求签名 ​

响应结果解密 ​

接入指引 ​

接口规范 ​

环境信息 ​

SDK 接入 ​

环境要求 ​

安装依赖 ​

初始化配置 ​

调用示例 ​

回调验签 ​

接口规则

接口概述

业务时序图

B2C（收购企业采购农产品）

B2S（收购企业销售农产品）

B2B（自产农产品销售）

签名加密

公共参数

密钥配置

参数加密

请求签名

响应结果解密

接入指引

接口规范

环境信息

SDK 接入

环境要求

安装依赖

初始化配置

调用示例

回调验签