Bitzsoft.Integrations.ElectronicSignature.Tencent 1.0.0-alpha.7

Bitzsoft.Integrations.ElectronicSignature.Tencent

腾讯电子签电子签章服务实现，基于腾讯电子签自建应用 API 和腾讯云 TC3-HMAC-SHA256 签名。

功能特性

• 支持腾讯电子签自建应用 API 调用
• 支持上传 PDF 并创建签署流程
• 支持查询合同详情、签署状态、文件下载 URL
• 支持获取 H5 签署链接、撤销合同流程
• 支持查询企业印章和流程模板
• 支持企业角色、员工、SSO 员工和客户系统 OpenId 绑定相关接口
• 支持按调用传入租户上下文，覆盖 Operator 和集团代理企业 Agent
• 提供 InvokeAsync 调用腾讯电子签原生 Action

安装

dotnet add package Bitzsoft.Integrations.ElectronicSignature.Tencent

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

配置

{
  "ElectronicSignature": {
    "Tencent": {
      "SecretId": "your-secret-id",
      "SecretKey": "your-secret-key",
      "OperatorUserId": "operator-user-id",
      "Endpoint": "ess.tencentcloudapi.com",
      "FileEndpoint": "file.ess.tencent.cn",
      "Region": "ap-guangzhou"
    }
  }
}

注册服务

using Bitzsoft.Integrations.ElectronicSignature.Tencent;

services.AddBitzsoftTencentElectronicSignature(configuration);

或：

using Bitzsoft.Integrations.ElectronicSignature.Tencent;

services.AddBitzsoftTencentElectronicSignature(options =>
{
    options.SecretId = "your-secret-id";
    options.SecretKey = "your-secret-key";
    options.OperatorUserId = "operator-user-id";
});

第三方请求日志

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

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

// ② 持久化：宿主注册 IRequestLogStore 实现后，所有出站请求自动落库
services.AddRequestLogging<MyRequestLogStore>(opts =>
{
    opts.MaxBodyLength = 8192;
    opts.SensitiveFields.Add("mySecret");
});
services.AddBitzsoftTencentElectronicSignature(configuration);

使用示例

统一抽象

var result = await provider.CreateContractAsync(new SimpleContractRequest
{
    Title = "采购合同",
    FileName = "contract.pdf",
    FileData = await File.ReadAllBytesAsync("contract.pdf"),
    SignerName = "张三",
    SignerPhone = "13800000000",
    ExtensionParams = new Dictionary<string, object>
    {
        ["ComponentPage"] = 1,
        ["ComponentPosX"] = 360,
        ["ComponentPosY"] = 640,
        ["ComponentWidth"] = 100,
        ["ComponentHeight"] = 40
    }
});

腾讯电子签完整发起流程

var tencent = (TencentElectronicSignatureProvider)provider;
var flow = await tencent.CreateFlowByFilesAsync(new TencentCreateFlowByFilesRequest
{
    Tenant = new TencentTenantContext
    {
        OperatorUserId = "operator-user-id",
        ProxyOrganizationId = "member-organization-id"
    },
    FlowName = "采购合同",
    FlowType = "采购合同",
    Files =
    [
        new TencentUploadFileRequest
        {
            FileName = "contract.pdf",
            FileData = await File.ReadAllBytesAsync("contract.pdf")
        }
    ],
    Approvers =
    [
        new TencentFlowApprover
        {
            ApproverType = 3,
            OrganizationName = "示例企业",
            ApproverName = "张三",
            ApproverMobile = "13800000000",
            NotifyType = "NONE",
            SignComponents =
            [
                new TencentSignComponent
                {
                    ComponentType = "SIGN_SEAL",
                    ComponentValue = "seal-id",
                    FileIndex = 0,
                    ComponentPage = 1,
                    ComponentPosX = 160,
                    ComponentPosY = 260,
                    ComponentWidth = 100,
                    ComponentHeight = 100
                }
            ]
        }
    ]
});

员工和客户系统 OpenId 映射

await tencent.CreateIntegrationEmployeesAsync(
[
    new TencentEmployeeRequest
    {
        OpenId = "biz-user-10001",
        DisplayName = "张三",
        Mobile = "13800000000",
        RoleIds = ["role-id"]
    }
]);

await tencent.BindEmployeeUserIdWithClientOpenIdAsync(new TencentUserOpenIdBindingRequest
{
    UserId = "tencent-user-id",
    OpenId = "biz-user-10001"
});

实现状态

注意事项

• 腾讯电子签 UploadFiles 使用文件服务域名，正式环境默认为 file.ess.tencent.cn
• CreateContractAsync 只覆盖统一抽象的极简场景，复杂签署方、审批、关键字定位、模板控件和租户上下文请使用 CreateFlowByFilesAsync 或 InvokeAsync
• CreateFlowByFiles 发起后会扣减合同额度，撤销返还规则以腾讯电子签官方文档为准
• H5 签署链接需要传入腾讯电子签返回的 RecipientId，可从 CreateFlowByFilesAsync 返回值或 DescribeFlowInfo 中获取
• 业务系统用户 ID 不等于腾讯电子签 UserId；需要使用员工创建、SSO 员工或 OpenId 绑定接口完成映射

依赖

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

相关包

相关文档

• 腾讯电子签自建应用 API 概览
• 请求结构
• 签名方法 v3