# dss-java-sdk
**Repository Path**: fadada-cloud/dss-java-sdk
## Basic Information
- **Project Name**: dss-java-sdk
- **Description**: Fadada DSS Java SDK
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: 1.3.2
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 1
- **Forks**: 1
- **Created**: 2024-07-18
- **Last Updated**: 2025-12-17
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
# 法大大 DSS Java SDK 说明
## 简介
法大大数字签名套件（专属版）（Digital Signature Suite），简称 DSS。DSS 定位为电子签章工具，旨在为客户提供电子签名开放服务能力，帮助客户通过接口灵活实现各种业务目标。
DSS通过API与EUI（可集成页面）的形式为客户提供电子签相关产品集成服务。通过与企业的各种数字化业务系统深度集成，实现合同签署由纸质签署到线上签署的数字化转型，从而帮助企业签约提效、降低合同管理成本，为企业的签署业务保驾护航。
法大大 DSS Java SDK 是一个用于与法大大数字签名套件（DSS）进行快速集成的开发工具包。
## 依赖环境
- **JDK 版本**：1.8 或以上
- **构建工具**：Maven 3.x
- **依赖库**：
- `com.google.code.gson:gson`
- `org.slf4j:slf4j-reload4j`
- `org.bouncycastle:bcprov-jdk18on`（用于 SM 加密算法支持）
## 安装说明
### Maven 引入
在您的 `pom.xml` 文件中添加以下依赖：
```xml
io.gitee.fadada-cloud
dss-java-sdk
1.3.2-8
org.slf4j
slf4j-reload4j
2.0.17
org.bouncycastle
bcpkix-jdk18on
1.82
com.google.code.gson
gson
2.13.2
```
### 手动安装
您也可以将 SDK 的 JAR 包手动安装到本地 Maven 仓库：
```bash
Maven中央仓库地址：https://central.sonatype.com/artifact/io.gitee.fadada-cloud/dss-java-sdk
直接引入Jar（上传到本地私有仓库），下载发行版（选择最新版下载）： https://gitee.com/fadada-cloud/dss-java-sdk/releases
```
## 初始化 SDK 客户端
在调用任何 API 之前，您需要先初始化 SDK 客户端：
```java
// DSS API地址，具体项目经理提供为准，参数做成配置项可进行配置
private static final String host = "https://dss-uat.fadada.com";
// DSS API应用ID，具体项目经理提供为准，参数做成配置项可进行配置
private static final String appId = "123456";
// DSS API应用秘钥，具体项目经理提供为准，参数做成配置项可进行配置
private static final String appSecret = "lqdn***w3u5rQCLznHz******hs8Es";
// 初始化
DssApiSdkFactory.init(host, appId, appSecret);
// 当有明确的传输安全要求时，可使用加密方式初始化（SM4、AES、SM2、RSA），两种初始化方式二选一
// rsaDssPublicKey（公钥）、rsaPrivateKey（私钥），参数做成配置项可进行配置
// 公私钥生成详见接口文档：https://dss.fadada.com/docs/doc-6762321（按文档生成配置后，还找项目经理将appId设置成支持数据传输加密模式）
// DssApiSdkFactory.init(host, appId, appSecret, "SM4", rsaDssPublicKey, rsaPrivateKey);
```
## 业务方法调用示例
基于DSS接口的灵活组装调用，可充分满足业务场景的签署需求，并能确保良好的用户体验，这里展示最小对接示例。
### 1. 申请证书
参考接口文档：https://dss.fadada.com/docs/doc-6424695
```java
// 从 DssApiSdkFactory 中获取 ZxcaApiClient 实例，用于调用豸信CA相关接口
ZxcaApiClient zxcaApiClient = DssApiSdkFactory.zxcaApiClient;
// 创建个人证书申请请求对象
RaCertApplyPersonRequest raCertApplyPersonRequest = new RaCertApplyPersonRequest();
// 设置申请人真实姓名
raCertApplyPersonRequest.setRealName("张三");
// 设置申请人证件类型，此处为身份证
raCertApplyPersonRequest.setIdCertType("identity_card");
// 设置申请人身份证号码
raCertApplyPersonRequest.setIdCertNo("110101199003076666");
// 豸信CA配置的认证方案ID，为空时使用默认方案，配置多个方案时可通过该参数指定，建议将该参数作为配置项进行配置
raCertApplyPersonRequest.setPlanId("1928260135212888064");
// 调用 ZxcaApiClient 的 raCertApplyPerson 方法发起个人证书申请请求，并获取响应结果
DssResponse certApplyInfoResponseDssResponse = zxcaApiClient.raCertApplyPerson(raCertApplyPersonRequest);
// 判断证书申请是否成功
if (certApplyInfoResponseDssResponse.isSuccess()) {
// 若申请成功，从响应结果中获取证书申请响应对象
CertApplyInfoResponse certApplyInfoResponse = certApplyInfoResponseDssResponse.getData();
// 打印个人证书编号，用于后续签署时使用
System.out.println("个人证书编号：" + certApplyInfoResponse.getRsaCertInfo().getCertificateId());
} else {
// 若申请失败，打印失败信息
System.out.println("证书申请失败：" + certApplyInfoResponseDssResponse.getMessage());
}
```
### 2. 制作印章
参考接口文档：https://dss.fadada.com/docs/doc-5322939
```java
// 从 DssApiSdkFactory 中获取 SealApiClient 实例，用于调用印章相关接口
SealApiClient sealApiClient = DssApiSdkFactory.sealApiClient;
// 创建个人印章创建请求对象
SealCreateRequest sealRequest = new SealCreateRequest();
// 设置印章显示的文本内容
sealRequest.setSealText("张三");
// 设置印章的样式，此处为rectangle_frame（矩形带框）样式
sealRequest.setSealStyle("rectangle_frame");
// 设置印章盖章规格，签署时印章盖章的尺寸（单位：毫米mm）
sealRequest.setSealSize("rectangle_30_16");
// 设置印章颜色，默认红色，遵循RGB16 进制颜色码，如#FFFFFF
sealRequest.setSealColor("#FFFFFF");
// 调用 SealApiClient 的 createPerson 方法发起创建个人印章请求，并获取响应结果
DssResponse response = sealApiClient.createPerson(sealRequest);
// 判断个人印章创建是否成功
if (response.isSuccess()) {
// 若创建成功，从响应结果中获取印章样式信息响应对象
SealStyleInfoResponse sealStyleInfoResponse = response.getData();
// 打印创建成功的个人印章ID，用于后续签署时使用
System.out.println("个人印章ID：" + sealStyleInfoResponse.getSealId());
} else {
// 若创建失败，打印失败信息
System.out.println("制作个人印章失败：" + response.getMessage());
}
```
### 3. 文件上传
参考接口文档：https://dss.fadada.com/docs/doc-6465577
```java
// 从 DssApiSdkFactory 中获取 FileTransferClient 实例，用于调用文件传输相关接口
FileTransferClient fileTransferClient = DssApiSdkFactory.fileTransferClient;
// 创建文件上传请求对象
FileUploadRequest request = new FileUploadRequest();
// 设置要上传的文件名称
request.setFileName("d.pdf");
// 设置要上传的文件，Demo使用本地文件路径，实际按照业务需求选择文件流或Url上传
request.setFile(new FileItem("C:\\temp\\d.pdf"));
// 调用 FileTransferClient 的 filePreUpload 方法发起文件预上传请求，并获取响应结果
DssResponse response = fileTransferClient.filePreUpload(request);
// 判断文件预上传是否成功
if (response.isSuccess()) {
// 若上传成功，从响应结果中获取文件信息响应对象
FileGetFileInfoResponse fileGetFileInfoResponse = response.getData();
// 打印上传成功后的文件ID，用于后续签署时使用
System.out.println("文件上传ID：" + fileGetFileInfoResponse.getFileId());
} else {
// 若上传失败，打印失败信息
System.out.println("文件上传失败：" + response.getMessage());
}
```
### 4. 文件签署
```java
// 从 DssApiSdkFactory 中获取 FileSignClient 实例，用于调用文件签署相关接口
FileSignClient fileSignClient = DssApiSdkFactory.fileSignClient;
// 创建文件签署请求对象
FileSignSignRequest fileSignSignRequest = new FileSignSignRequest();
// 设置业务自定义签署交易号，确保唯一性，用于后续查询签署状态等操作
fileSignSignRequest.setTransactionId("lqdnQUZw3u5rQCLznHz7fEvuzdjhs8Es");
// 设置文件ID，为上传文件接口返回的文件ID
fileSignSignRequest.setFileId("492338925252648960_cpdf");
// 创建签章信息列表
List sealInfos = new ArrayList<>();
// 创建一个签章信息对象
DocSignSealInfo sealInfo = new DocSignSealInfo();
// 设置签章对应的证书ID，为申请证书接口返回的证书ID
sealInfo.setCertificateId("492056864220815360");
// 设置印章ID，为制作印章接口返回的印章ID
sealInfo.setSealId("478516737198579712");
// 设置签署规则类型为指定位置签署
sealInfo.setRuleType(SignRuleTypeEnum.LOCATION_SIGN.getReadValue());
// 创建一个定位坐标对象
LocateCoordinate locateCoordinate = new LocateCoordinate();
// 设置签章所在的页码
locateCoordinate.setPageNum(1);
// 设置签章在页面上的 X 坐标
locateCoordinate.setX(100.0);
// 设置签章在页面上的 Y 坐标
locateCoordinate.setY(200.0);
// 将定位坐标添加到签章信息对象中
sealInfo.setLocateCoordinates(Arrays.asList(locateCoordinate));
// 将签章信息添加到签章信息列表中
sealInfos.add(sealInfo);
// 将签章信息列表设置到文件签署请求对象中
fileSignSignRequest.setSealInfos(sealInfos);
// 调用文件签署接口发起文件签署请求，并获取响应结果
DssResponse fileSignSignResponseDssResponse = fileSignClient.fileSignSign(fileSignSignRequest);
// 判断文件签署是否成功
if (fileSignSignResponseDssResponse.isSuccess()) {
// 若签署成功，从响应结果中获取文件签署响应对象
FileSignSignResponse fileSignSignResponse = fileSignSignResponseDssResponse.getData();
// 打印签署成功后的文件 URL
System.out.println("文件签署成功文件url：" + fileSignSignResponse.getFileUrl());
} else {
// 若签署失败，打印失败信息
System.out.println("文件签署失败：" + fileSignSignResponseDssResponse.getMessage());
}
```
### 5. 申请出证报告
参考接口文档：https://dss.fadada.com/docs/doc-5322935
```java
// 从 DssApiSdkFactory 中获取 ReportClient 实例，用于调用报告出证相关接口
ReportClient reportClient = DssApiSdkFactory.reportClient;
// 创建报告出证申请请求对象
ReportApplyRequest reportApplyRequest = new ReportApplyRequest();
// 设置需要出证的文件 ID，该 ID 是文件签署成功的文件唯一标识
reportApplyRequest.setFileId("492338925252648960_cpdf");
// 设置业务侧自定义的出证申请编号
reportApplyRequest.setOutApplyNo("oyqyMGDaDCmffYf6");
// 设置报告类型，此处指定为fddEleDataValid（《法大大电子数据验证报告》）
reportApplyRequest.setReportType("fddEleDataValid");
// 调用 ReportClient 的 apply 方法发起报告出证申请请求，并获取响应结果
DssResponse reportApplyResponse = reportClient.apply(reportApplyRequest);
// 判断报告出证申请是否成功
if (reportApplyResponse.isSuccess()) {
// 若申请成功，从响应结果中获取报告出证申请响应对象
ReportApplyResponse reportApplyResponseData = reportApplyResponse.getData();
// 打印出证申请的批次号，可用于后续查询出证状态
System.out.println("出证申请批次号：" + reportApplyResponseData.getApplyBatchNo());
} else {
// 若申请失败，打印失败信息
System.out.println("出证申请失败：" + reportApplyResponse.getMessage());
}
```