53 lines
3.5 KiB
Markdown
53 lines
3.5 KiB
Markdown
# E签宝协议签署接入说明
|
||
|
||
## 已实现范围
|
||
|
||
- 五份原始文件使用独立类型和字段映射：`account-proof`、`account-change`、`entity-change`、`shared-contract`、`authorization`。
|
||
- 每次发起先在 `business_courier_agreement_signatures` 落库，生成唯一 `business_no` 和 `idempotency_key`，再生成 PDF、上传文件并创建签署流程。
|
||
- 保存 `fileId`、`signFlowId`、模板版本、原文哈希、签署文件哈希和完成证书哈希。
|
||
- 回调复用现有 E签宝验签入口，校验原始 Body、时间戳、AppId 和 HmacSHA256；协议回调按流程 ID 幂等更新并排队归档。
|
||
- 收款账户证明及账户变更中的开户名称按实际银行卡持卡人姓名填写，不要求与营业执照或公司全称一致；签署主体和公司全称仍单独维护。
|
||
- 签署完成后只归档文件，不自动启用收款账户；账户、生效日期和收款人仍须财务复核。
|
||
|
||
## 配置步骤
|
||
|
||
在本地 `runtime/.env` 或受控部署环境中配置，禁止提交到 Git：
|
||
|
||
```dotenv
|
||
ESIGN_ENVIRONMENT=sandbox
|
||
ESIGN_BASE_URL=https://smlopenapi.esign.cn
|
||
ESIGN_APP_ID=替换为沙箱AppId
|
||
ESIGN_APP_SECRET=替换为沙箱AppSecret
|
||
ESIGN_NOTIFY_URL=https://你的公网域名/integrations/esign/callback
|
||
ESIGN_CALLBACK_TOLERANCE_SECONDS=900
|
||
ESIGN_TIMEOUT=20
|
||
```
|
||
|
||
正式环境单独使用 `https://openapi.esign.cn`、正式 AppId/AppSecret、独立 Webhook 和独立数据库记录。不要把沙箱凭证切换到生产域名，也不要在日志中输出 Secret、完整手机号、邮箱、身份证号或临时下载 URL。
|
||
|
||
在 E签宝开放平台完成：企业认证、SaaS API V3 应用、出口 IP 白名单、Webhook、`SIGN_FLOW_COMPLETE` 订阅，以及短信/邮件和企业签署服务开通。
|
||
|
||
## 联调步骤
|
||
|
||
1. 在页面“协议签署 → 发起签章”选择文件类型，填写该类型专属字段和对方实名绑定的手机号/邮箱。
|
||
2. 点击“推送至E签宝”，确认本地任务进入“待签署”，并记录任务的 `business_no`、`fileId`、`signFlowId`。
|
||
3. 在沙箱签署页完成实名认证、签字或盖章；验证单页和多页文件的签章位置。
|
||
4. 模拟或等待 `SIGN_FLOW_COMPLETE`：只有 `signFlowStatus=2` 才会下载已签 PDF 和完成证书。
|
||
5. 检查任务变为“已签署并归档”，下载原文、已签协议和证书，核对哈希值。
|
||
6. 不发回调时使用任务行的“同步状态”按钮验证主动查单补偿；重复点击推送或重复回调不得产生第二个 `signFlowId`。
|
||
|
||
## 安全审计要点
|
||
|
||
- 业务单号、文件 ID、流程 ID 分开保存；发起前有唯一键，超时后不得直接重发。
|
||
- 回调使用恒定时间比较和时间戳窗口，先验签再解析；回调状态不能把已完成状态回退为处理中。
|
||
- 原文和归档文件存私有 `uploads` 盘并校验 SHA-256；临时下载地址只在服务端短时使用。
|
||
- 个人证件和账号字段采用加密 cast 存储；权限仅允许管理员发起、同步和下载。
|
||
- 企业名称不能作为模糊账号匹配依据；应在 E签宝实名账号确认后填写手机号/邮箱。
|
||
- 电子签署完成不等于财务数据生效，收款账户变更必须保留人工复核和原档案电话核验。
|
||
|
||
## 真实环境上线前
|
||
|
||
- 使用密钥管理系统或受控环境变量保存正式 Secret，并完成轮换/吊销流程。
|
||
- 配置公网 HTTPS、出口 IP 白名单和回调来源 IP 白名单。
|
||
- 为签章坐标、个人/企业签署、拒签/撤销/过期、下载 URL 过期和回调丢失分别留存验收记录。
|