Bitzsoft.Integrations.ElectronicSignature 1.0.0-alpha.10

Bitzsoft.Integrations.ElectronicSignature

电子签章抽象层 — 统一接口定义、基础模型与结果包装。

屏蔽君子签、法大大、e签宝、上上签、爱签、契约锁、安证通、腾讯电子签等供应商差异，提供一致的合同发起、签署、印章、模板与回调验签 API。

功能特性

• 统一供应商接口 IElectronicSignatureProvider：12 个异步方法覆盖合同/签署/印章/模板全生命周期，外加回调验签
• 统一回调解析 IElectronicSignatureCallbackParser：将各供应商原始 Webhook 报文解析为标准 CallbackEvent
• 配置抽象 IElectronicSignatureConfigProvider：解耦配置来源，支持从 IOptions、数据库或远程配置中心加载
• 统一结果包装 ElectronicSignatureResult<T>：携带成功标志、数据与供应商原始错误码
• 统一异常 ElectronicSignatureException：封装供应商标识、错误码与原始消息
• 不可变模型设计：集合返回 IReadOnlyList<T>，属性使用 init 保证只读

安装

dotnet add package Bitzsoft.Integrations.ElectronicSignature

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

接口

IElectronicSignatureProvider

统一的电子签章供应商接口。统一方法仅覆盖最通用的极简场景（单文件、单签署方）；复杂签署、企业签、关键字定位等请使用各供应商实现的 partial class 扩展方法。

IElectronicSignatureCallbackParser

核心模型

枚举

使用示例

抽象层本身只定义接口与模型，具体实现由各供应商包提供。以下示例假设已注册某个供应商实现：

public class ContractService(IElectronicSignatureProvider provider)
{
    public async Task<string> StartSignAsync(byte[] pdf, string signerPhone)
    {
        // 1. 创建并发起签署
        var createResult = await provider.CreateContractAsync(new SimpleContractRequest
        {
            Title = "采购合同",
            FileName = "contract.pdf",
            FileData = pdf,
            SignerName = "张三",
            SignerPhone = signerPhone
        });

        if (!createResult.IsSuccess)
            throw new ElectronicSignatureException(
                provider.ProviderName, createResult.ErrorCode, createResult.ErrorMessage);

        var contractId = createResult.Data!;

        // 2. 轮询签署状态
        var status = await provider.GetSigningStatusAsync(contractId);
        Console.WriteLine($"合同 {contractId} 当前状态：{status.Data?.Status}");

        return contractId;
    }

    public async Task DownloadAsync(string contractId)
    {
        // 3. 签署完成后下载合同
        var file = await provider.DownloadContractAsync(contractId);
        await File.WriteAllBytesAsync($"signed-{contractId}.pdf", file.Data!);
    }
}

回调验签与解析：

// Webhook 入口：先用 provider 验签，再用 parser 解析
var isValid = provider.VerifyCallback(
    signature: request.Headers["X-Signature"],
    payload: requestBody,
    callbackHeaders: request.Headers,
    queryString: request.QueryString.Value);

if (!isValid) return Results.Unauthorized();

var parser = serviceProvider.GetRequiredService<IElectronicSignatureCallbackParser>();
var evt = parser.ParseCallback(requestBody);
// evt.ContractId / evt.Status / evt.OriginalPayload

多供应商解析

同一应用注册多个供应商时，通过 ProviderName 路由到目标实现：

var providers = serviceProvider.GetServices<IElectronicSignatureProvider>();
var qiyuesuo = providers.First(p => p.ProviderName == "Qiyuesuo");

依赖

• Bitzsoft.Integrations.Compatibility：基础工具库

相关包