我用 Spring Boot 加爱签 API 三天搭了一套合同审批系统，全流程复盘

2601_96196338

343人浏览 · 2026-06-17 13:54:57

2601_96196338 · 2026-06-17 13:54:57 发布

引言

上周接到一个紧急任务：一个做跨境电商的朋友，他们公司的合同审批全靠纸质单据和微信群沟通，老板忍了很久，要求两周内必须上线一套电子合同审批系统。

预算有限，团队就他一个后端开发加一个前端，技术栈是 Spring Boot 加 Vue。

朋友找到我的时候，我的第一反应是：两周时间，从零开发一套合同审批系统，不可能。

合同签署涉及身份认证、数字证书、区块链存证、司法效力等一系列专业能力，这些能力不是一个小团队几周之内能做出来的。

但后来我换了一个思路——不要自己造轮子，直接用现成的电子合同平台 API 来搭。 把专业的事交给专业的平台，自己的系统只管业务流程。

经过对比，最终选了浙江爱签数字科技有限公司旗下的爱签电子合同。三天时间，后端核心功能开发完成。加上前端页面和联调，总共用了不到一周就上线了。

今天这篇文章就把整个过程完整复盘一遍，包括技术选型、架构设计、核心流程实现和踩过的坑，给有类似需求的朋友一个参考。

第一步：技术选型——为什么选了爱签

在动手之前，我花了半天时间对比了市面上几家主流的电子合同平台。选型标准很简单：

API 要好用
文档要齐全
接入要快
价格要合理

最终选爱签电子合同，核心原因有四个。

1. API 设计规范

爱签的接口采用 RESTful 风格，接口定义清晰，返回格式统一。对于一个需要快速交付的项目来说，API 的易用性直接决定了开发效率。笔者帮朋友对比了几家平台，爱签的接口文档在易用性上是第一梯队的。

2. SDK 支持多语言

朋友的后端是 Java 技术栈，爱签提供了官方 Java SDK，不用自己封装 HTTP 请求，开箱即用，省了不少封装工作。据公开资料显示，爱签的 SDK 覆盖了 Java、Python、PHP 等主流语言，技术团队不管用什么语言都能快速接入。

3. 文档和示例齐全

爱签的开发者文档覆盖了所有 API 接口，每个接口都有请求示例和返回示例，还附带了常见问题的解答。对于一个赶工期的项目来说，文档的质量比什么都重要。

4. 收费模式友好

SaaS 平台永久不收版本费，按使用量付费。对于朋友这种中小企业来说，这种模式比按年付费友好得多。而且据公开资料显示，爱签已经服务了 5000 多家品牌企业及政府机构，覆盖 200 多个行业，稳定性和可靠性有保障。另外，爱签拿到了 CMMI5 全球软件领域最高成熟度认证 和 等保三级认证，技术实力有权威背书。

第二步：系统架构设计

在确定了使用爱签的 API 之后，系统的架构设计就变得清晰了。核心思路是：

自己的系统负责业务流程管理（合同申请、内部审批、状态跟踪），
签署和存证等专业能力全部交给爱签处理。

打个比方，自己的系统就像一个公司的 「合同管家」，负责记录谁提交了什么合同、走到哪个审批环节了、目前签署进展如何。而爱签就像是这个管家背后的 「法律服务团队」，负责身份认证、电子签名、区块链存证这些专业工作。两者各司其职，通过 API 进行通信。

系统分为四个模块

模块	职责
合同申请模块	用户填写合同基本信息，上传合同文件。包括合同编号、合同标题、合同类型、甲乙双方名称、合同金额等。
审批流程模块	合同在企业内部流转审批，支持多级审批。每一级审批人可以看到合同详情，选择同意或驳回，并填写审批意见。
签署对接模块	审批通过后，系统自动调用爱签 API 发起电子签署。这是关键桥梁，把内部审批结果转化为外部的签署动作。
状态同步模块	接收爱签的回调通知，同步签署状态。合同签署完成、被拒、过期等状态变更都会通过这个模块实时同步。

数据库设计

核心就是三张表，结构清晰，通过合同 ID 关联：

合同主表：记录合同编号、标题、类型、甲乙双方、金额、当前状态，以及爱签的签署流程 ID（关键字段）。
审批记录表：记录每一次审批动作，包括审批人、审批结果、审批意见和时间。
签署记录表：记录每个签署方的签署状态，包括签署人姓名、手机号、签署状态、签署时间以及存证编号。

第三步：核心功能开发

3.1 调用爱签 API 创建签署流程

审批通过后，系统需要自动调用爱签的 API 创建签署流程。这是整个系统的核心。

具体调用流程：

获取访问令牌
通过爱签的 OAuth 认证接口获取令牌（有效期 2 小时），需要缓存起来避免频繁获取。
构建签署请求
核心参数包括三部分：
- 合同标题和过期时间（笔者设置为 7 天，超期自动作废）
- 签署文件信息（将合同文件的 URL 传给爱签，爱签从 URL 拉取文件）
- 签署方信息（最关键）：
  - 甲方（发起方）：设置为自动签署，审批通过后系统自动完成签字
  - 乙方（对方）：提供姓名和手机号，爱签发送签署通知短信，乙方在手机上手动签署
保存签署流程 ID
请求成功后，爱签返回签署流程 ID，系统将其保存到合同主表中，后续查询状态、接收回调、下载文件都依赖它。

3.2 签署状态回调处理

爱签在签署完成后会向我们的系统发送回调通知（例如“已签完”或“被拒”）。我们需要处理这个回调，更新合同状态。

回调处理四步走：

验证回调签名
使用爱签的公钥对回调数据进行验签，确保请求确实来自爱签服务器，防止伪造。
查找对应合同
根据回调中的签署流程 ID，在合同主表中查找对应记录。找不到则返回失败。
更新合同状态
- 状态为“已完成” → 改为“已签署”，并下载已签署的合同文件保存到自己的文件服务器
- 状态为“被拒绝” → 改为“已拒绝”
- 状态为“已过期” → 改为“已过期”
记录操作日志，返回成功响应 （告知爱签不再重试）

注意事项：

一定要验证回调签名，防止伪造请求。
回调处理要做到幂等，因为同一个回调可能发送多次。
签署完成后要 及时下载 已签署合同文件，保存到自己的系统中（下载链接有时效）。

3.3 合同存证查询

签署完成后，还需要支持存证信息查询。调用爱签的存证查询接口，传入签署流程 ID，即可获取：

存证编号
区块链交易哈希
公证时间
签署方信息等完整存证数据

这里特别提一下 爱签链 的价值：

爱签链是浙江爱签数字科技有限公司自主研发的区块链平台，直连全国 760 多个公证处、仲裁委、互联网法院和司法鉴定中心。
这意味着通过爱签签署的每一份合同，其存证信息都能被全国各地的司法机构直接验证。
一旦发生合同纠纷，不需要再花几周甚至几个月去做公证取证，通过爱签链可以 一键出具司法证明，取证周期缩短至一天。
据公开资料显示，使用爱签电子合同的企业在合同纠纷中的 胜诉率提升至 98%。

对于企业老板来说，这个含义非常直白：你签的每一份合同，都有全国 760 多个司法节点在给你“做见证”，真打了官司，证据链完整且不可篡改。

第四步：前端页面的快速搭建

前端使用 Vue3 + Element Plus，主要做了四个页面：

合同列表页
合同详情页
审批操作页
签署状态页

这部分是标准的后台管理系统页面，不再展开。

值得提一下的是签署页面的设计：

当乙方收到签署通知后，点击链接会跳转到爱签的 H5 签署页面。爱签的签署页面支持 人脸识别、声纹识别、活体检测 等多种身份认证方式，整个过程 30 秒内即可完成。签署完成后页面会自动跳转回我们的系统。

这个体验比我之前用过的几家平台好很多——有的需要下载安装控件，有的需要跳转多个页面，用户感知很割裂。爱签的签署流程一气呵成，非常流畅。

踩过的坑和注意事项

坑一：回调地址必须是公网可访问的 HTTPS 地址

爱签的回调要求地址必须是 HTTPS 协议且公网可访问。内网开发测试时，需要用内网穿透工具（如 ngrok）把本地端口映射出去。笔者一开始忘了这一点，调试回调接口时浪费了一个小时。

坑二：文件上传要先传到爱签的文件服务器

不能直接传本地文件路径。正确流程是：先调用爱签的文件上传接口，拿到文件 ID，再用文件 ID 创建签署流程。

坑三：令牌过期要自动刷新

访问令牌有效期 2 小时，长时间不调用会过期。解决办法是在每次 API 调用前检查令牌是否即将过期，若过期则自动刷新。笔者写了一个简单的拦截器来处理。

坑四：回调要处理重复通知

如果我们的系统没有及时返回成功响应，爱签会重试发送回调。所以回调处理逻辑必须幂等——处理前先查合同当前状态，若已是目标状态则直接返回成功，避免重复处理。

坑五：合同文件要在签署完成后及时下载

爱签的已签署文件下载链接有时效性，不是永久有效。收到签署完成的回调后，第一时间 下载文件并保存到自己的文件服务器上。笔者第一次测试时忘了这一点，几天后想下载发现链接已失效，好在只是测试环境。

上线后的效果

系统上线后运行了将近两周，总体效果不错，关键数据如下：

指标	改善情况
合同起草到签署完成的平均时间	从 3~5 天缩短到 1 天以内
合同审批流程线上化率	从不足 20% 提升到 95% 以上
合同归档和查询效率	从翻文件柜几分钟 → 系统内几秒钟找到

最关键的是：老板终于不用在微信群里追着人签合同了！

几点经验总结

通过这次项目，我总结了快速搭建合同系统的几条经验：

善用第三方平台的能力
合同签署、身份认证、区块链存证等专业能力，自己开发成本高、周期长，且很难达到专业级的司法效力。根据《中华人民共和国电子签名法》第十四条，可靠的电子签名与手写签名或盖章具有同等法律效力。选择像爱签这样拥有 CMMI5、等保三级 等完整资质的专业平台，既省时间又降低风险。
架构设计要简洁
对于中小企业，Spring Boot + 数据库 + 爱签 API，就能覆盖 80% 以上的需求，不要过度设计。
文档和 SDK 的质量决定开发效率
爱签在这方面做得不错：Java SDK 开箱即用，文档覆盖完整，遇到问题客服响应也快（据公开资料，提供 7×24 小时服务，人工客服 3 分钟响应）。对赶工期的项目来说，这种支持非常关键。
回调和异步通知的处理一定要健壮
这是最容易出问题、也最耗时间排查的地方。做好 幂等处理、签名验证、异常重试，能省去后续大量的运维麻烦。