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 幂等更新并排队归档。
收款账户证明及账户变更中的开户名称按实际银行卡持卡人姓名填写，不要求与营业执照或公司全称一致；签署主体和公司全称仍单独维护。
签署完成后只归档文件，不自动启用收款账户；账户、生效日期和收款人仍须财务复核。
证件补充默认关闭，仅适用于授权委托书与公司主体变更。收款账户变更没有证件上传入口。
授权委托书按需发送三份独立 PDF：主文件、身份证正反面合页推送单、银行卡正反面合页推送单。主体变更按需增加一份独立营业执照盖章推送单，共四份。
每张证件推送单仅有一处固定签署位置，分配给页面选定的证件签署方；营业执照要求企业盖章。主文件原有签署顺序保持不变。
原始图片、推送单原文与已签文件存入私有业务存储；文件 ID、路径和 SHA-256 放在原任务的加密 payload 内，无需数据库迁移。
同一流程中的文件按 fileId 匹配并分别回传归档；缺少任一推送单时不能标记归档成功，可通过现有同步或归档任务重试。任务行支持逐份预览和下载。
证件单张 JPG / PNG 上限 10 MB，宽高上限 5000 像素。多图请求需要 PHP 与生产入口 Nginx 的请求总量上限均为 64 MB；更新入口配置前备份并核对现有配置，保留其他配置。

配置步骤

在本地 runtime/.env 或受控部署环境中配置，禁止提交到 Git：

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 订阅，以及短信/邮件和企业签署服务开通。

联调步骤

在页面“协议签署 → 发起签章”选择文件类型，填写该类型专属字段和对方实名绑定的手机号/邮箱。
点击“推送至E签宝”，确认本地任务进入“待签署”，并记录任务的 business_no、fileId、signFlowId。
在沙箱签署页完成实名认证、签字或盖章；验证单页和多页文件的签章位置。
模拟或等待 SIGN_FLOW_COMPLETE：只有 signFlowStatus=2 才会下载已签 PDF 和完成证书。
检查任务变为“已签署并归档”，下载原文、已签协议和证书，核对哈希值。
不发回调时使用任务行的“同步状态”按钮验证主动查单补偿；重复点击推送或重复回调不得产生第二个 signFlowId。

安全审计要点

业务单号、文件 ID、流程 ID 分开保存；发起前有唯一键，超时后不得直接重发。
回调使用恒定时间比较和时间戳窗口，先验签再解析；回调状态不能把已完成状态回退为处理中。
原文和归档文件存私有 uploads 盘并校验 SHA-256；临时下载地址只在服务端短时使用。
个人证件和账号字段采用加密 cast 存储；权限仅允许管理员发起、同步和下载。
企业名称不能作为模糊账号匹配依据；应在 E签宝实名账号确认后填写手机号/邮箱。
电子签署完成不等于财务数据生效，收款账户变更必须保留人工复核和原档案电话核验。

真实环境上线前

使用密钥管理系统或受控环境变量保存正式 Secret，并完成轮换/吊销流程。
配置公网 HTTPS、出口 IP 白名单和回调来源 IP 白名单。
为签章坐标、个人/企业签署、拒签/撤销/过期、下载 URL 过期和回调丢失分别留存验收记录。

4.6 KiB Raw Blame History Unescape Escape