Bitzsoft.Integrations.Express.SfLegal 1.0.1

Bitzsoft.Integrations.Express.SfLegal

顺丰函证通法律函件寄递服务实现 -- 面向律师事务所、会计师事务所等企业的法律函件全生命周期管理。

功能特性

• 实现 ISfLegalDocumentProvider 独立接口（非 IExpressProvider），与通用物流服务互不冲突
• 支持法律函件创建、寄递追踪、签收确认、全流程记录查询
• 认证方式：月结卡号 + CustomerCode + CheckWord，签名 = Base64(MD5(data + timestamp + checkWord))
• 法律函件状态自动推断（签收 / 拒收 / 退回 / 异常）
• 统一异常处理，供应商错误码自动映射为 ExpressException

安装

.NET CLI

dotnet add package Bitzsoft.Integrations.Express.SfLegal

PackageReference

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

配置

appsettings.json

{
  "Express": {
    "SfLegal": {
      "MonthlyCardNo": "你的月结卡号",
      "CustomerCode": "你的顾客编码",
      "CheckWord": "你的校验码",
      "BaseUrl": "https://sfapi.sf-express.com",
      "HttpClientName": "SfLegal"
    }
  }
}

注册服务

从 IConfiguration 绑定（推荐）

using Bitzsoft.Integrations.Express.SfLegal;

builder.Services.AddBitzsoftSfLegal(
    builder.Configuration.GetSection("Express:SfLegal"));

委托配置

builder.Services.AddBitzsoftSfLegal(options =>
{
    options.MonthlyCardNo = "your_card_no";
    options.CustomerCode = "your_code";
    options.CheckWord = "your_check_word";
});

请求审计

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

// ① 默认：启用记录管道但不持久化（日志丢弃）
services.AddBitzsoftSfLegal(options => { /* ... */ });

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

使用示例

创建法律函件寄递任务

using Bitzsoft.Integrations.Express.Interfaces;
using Bitzsoft.Integrations.Express.Models;

public class LegalService
{
    private readonly ISfLegalDocumentProvider _provider;

    public LegalService(ISfLegalDocumentProvider provider) => _provider = provider;

    public async Task ShipAsync(ExpressContact sender, ExpressContact receiver)
    {
        var request = new LegalDocumentShipmentRequest
        {
            Sender = sender,
            Receiver = receiver,
            DocumentType = "律师函",
            Title = "催收律师函",
            CaseNumber = "CASE-2026-001"
        };

        LegalDocumentShipmentResult result =
            await _provider.CreateDocumentShipmentAsync(request);
        Console.WriteLine($"函件ID: {result.DocumentId}, 运单号: {result.TrackingNumber}");
    }
}

查询函件寄递状态

LegalDocumentTrackingResult result =
    await _provider.TrackDocumentAsync(documentId);
Console.WriteLine($"状态: {result.Status}, 运单号: {result.TrackingNumber}");

// 确认签收
await _provider.ConfirmReceiptAsync(documentId);

// 获取全流程记录
LegalDocumentFullRecord record = await _provider.GetFullRecordAsync(documentId);
Console.WriteLine($"创建 {record.CreatedTime}, 寄出 {record.SentTime}, 签收 {record.SignedTime}");

核心类型一览

支持的操作

依赖

注意事项

• 顺丰函证通具体 API 文档需在 顺丰开放平台 注册并申请服务权限后获取
• 需绑定月结卡号的 IUOP 账号
• ISfLegalDocumentProvider 独立注册，可与 IExpressProvider 并存（如顺丰查询 + 函证通寄递）

相关包

• Bitzsoft.Integrations.Express -- 抽象层
• Bitzsoft.Integrations.Express.All -- 聚合包
• Bitzsoft.Integrations.Express.Kdniao -- 快递鸟
• Bitzsoft.Integrations.Compatibility -- 基础工具库