Bitzsoft.Integrations.ElectronicSignature.Anzhengtong 1.0.4

Bitzsoft.Integrations.ElectronicSignature.Anzhengtong

安证通（一签通 / 悦文云文档）电子签章服务实现，基于悦文云文档开放 API。

核心流程：上传文件 → 签章申请 → 获取签章 URL → 回调通知。

功能特性

• 实现 IElectronicSignatureProvider：覆盖合同发起、详情、查看、签署 URL、签署状态、回调验签统一方法
• AppId + AppSecret SHA-256 鉴权：统一签名头注入，appId、时间戳参与签名
• 回调验签：JSON body 格式，校验 appId 匹配、时间戳新鲜度（毫秒容差）、SHA-256 签名
• partial class 扩展：按业务领域拆分为 SignTasks、Documents、Office、LicenseAndAI 多个文件

安装

dotnet add package Bitzsoft.Integrations.ElectronicSignature.Anzhengtong

<PackageReference Include="Bitzsoft.Integrations.ElectronicSignature.Anzhengtong" Version="1.0.0" />

配置

{
  "Anzhengtong": {
    "AppId": "your-app-id",
    "AppSecret": "your-app-secret",
    "Version": "1.0",
    "BaseUrl": "https://your-yuewen-host:port",
    "Timeout": "00:00:30"
  }
}

注册服务

using Bitzsoft.Integrations.ElectronicSignature.Anzhengtong;

// 方式一：IConfiguration（默认读取 "Anzhengtong" 配置节）
services.AddBitzsoftAnzhengtongElectronicSignature(configuration);

或：

using Bitzsoft.Integrations.ElectronicSignature.Anzhengtong;

// 方式二：委托配置
services.AddBitzsoftAnzhengtongElectronicSignature(options =>
{
    options.AppId = "your-app-id";
    options.AppSecret = "your-app-secret";
    options.BaseUrl = "https://your-yuewen-host:port";
});

请求审计

内置 Bitzsoft.Integrations.RequestLogging 出站请求记录管道，默认 NullRequestLogStore 不持久化。

// ① 默认：启用记录管道但不持久化（日志丢弃）
services.AddBitzsoftAnzhengtongElectronicSignature(configuration);

// ② 持久化：宿主注册 IRequestLogStore 实现后，所有出站请求自动落库
services.AddRequestLogging<MyRequestLogStore>(opts =>
{
    opts.MaxInMemoryBodyBytes = 64 * 1024; // 仅控制内存/加密临时文件切换，不截断正文
    opts.SensitiveFields.Add("AppSecret");
});
services.AddBitzsoftAnzhengtongElectronicSignature(configuration);

使用示例

统一抽象

// 注入 IElectronicSignatureProvider，ProviderName == "Anzhengtong"
// 安证通流程：上传文件（base64）→ 签章申请，返回 businessId
var createResult = await provider.CreateContractAsync(new SimpleContractRequest
{
    Title = "采购合同",
    FileName = "contract.pdf",
    FileData = await File.ReadAllBytesAsync("contract.pdf"),
    SignerName = "张三",
    ExtensionParams = new Dictionary<string, object>
    {
        ["idCard"] = "110101199001011234",
        ["userType"] = "2",        // 1 企业 / 2 个人
        ["returnUrl"] = "https://app.example.com/sign-done"
    }
});

var businessId = createResult.Data!;

// 查询签署状态、获取签署页面
var status  = await provider.GetSigningStatusAsync(businessId);
var signUrl = await provider.GetSigningUrlAsync(businessId, string.Empty);

注意：安证通的 DownloadContractAsync 与 CancelContractAsync 不直接支持，下载请使用 DownloadFileBytesAsync（需 fileId），撤销由签章申请超时后自动过期处理。

扩展 API（partial class）

统一接口之外的能力通过 AnzhengtongElectronicSignatureProvider 的 partial class 方法调用：

var azt = (AnzhengtongElectronicSignatureProvider)provider;

// 通用 POST 查询
var result = await azt.QueryPostAsync(AnzhengtongApis.SignApply, body: new { /* ... */ });

扩展方法按领域拆分：

• SignTasks — 签署申请、签署结果查询、预定义签署（form 回填）
• Documents — 文件上传、水印、下载、预览、签名验证
• Office — 在线文档编辑、编辑状态查询
• LicenseAndAI — 表单回填、表单字段映射、文件比对、关键字智能提取

核心类型一览

依赖

• Bitzsoft.Integrations.Compatibility：基础工具库
• Bitzsoft.Integrations.ElectronicSignature：统一抽象
• Bitzsoft.Integrations.RequestLogging：请求审计

相关包