Bitzsoft.Integrations.Finance.Tax.QiXiangYun 1.0.0-alpha.10

Bitzsoft.Integrations.Finance.Tax.QiXiangYun

企享云税务服务实现 -- 对接企享云开放平台 API，提供订购管理、企业授权与异步任务能力。

功能特性

• 订购管理：产品订购（SubscribeProductAsync）、取消订购（CancelSubscribeAsync），按税号 + 产品代码维护服务订购关系
• 企业授权：获取已授权企业列表（GetEnterpriseListAsync），返回税号、企业名称与授权状态
• 通知回调保护：供应商签名规范未配置时拒绝确认服务异常通知和税局维护消息，避免将未经验证的回调误报为成功
• 异步任务管理：QiXiangYunAsyncTaskManager 封装发起任务 → 轮询 → 超时处理的标准模式，可配置轮询间隔与超时上限
• 自动鉴权：QiXiangYunAuthHandler 自动注入 access_token 与 appId 请求头
• 配置校验：启动期校验 AppId / AppSecret 必填、BaseUrl 合法 URI、轮询与超时参数合理

安装

.NET CLI

dotnet add package Bitzsoft.Integrations.Finance.Tax.QiXiangYun

PackageReference

<PackageReference Include="Bitzsoft.Integrations.Finance.Tax.QiXiangYun" Version="1.0.0" />

配置

appsettings.json

{
  "Finance": {
    "Tax": {
      "QiXiangYun": {
        "AppId": "企享云提供的 AppId",
        "AppSecret": "双方约定的 AppSecret",
        "BaseUrl": "https://api.qixiangyun.com",
        "CallbackBaseUrl": "https://yourapp.com/qxy/callback",
        "AsyncPollIntervalMs": 3000,
        "AsyncTimeoutMs": 60000,
        "HttpTimeoutSeconds": 30
      }
    }
  }
}

注册服务

从 IConfiguration 绑定

using Bitzsoft.Integrations.Finance.Tax.QiXiangYun;

builder.Services.AddBitzsoftQiXiangYunTax(
    builder.Configuration.GetSection("Finance:Tax:QiXiangYun"));

注意：当前 AddBitzsoftQiXiangYunTax 仅提供 Action<QiXiangYunOptions> 委托重载。从配置节绑定时，可使用 services.Configure<QiXiangYunOptions>(configuration.GetSection(...)) 后再调用委托重载，或通过 Bitzsoft.Integrations.Finance.All 聚合包统一注册。

委托配置

builder.Services.AddBitzsoftQiXiangYunTax(options =>
{
    options.AppId = "企享云提供的 AppId";
    options.AppSecret = "双方约定的 AppSecret";
    options.BaseUrl = "https://api.qixiangyun.com";
    options.AsyncPollIntervalMs = 3000;
    options.AsyncTimeoutMs = 60000;
});

第三方请求日志

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

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

使用示例

using Bitzsoft.Integrations.Finance.Tax.QiXiangYun.Common;

public class QxyService
{
    private readonly QiXiangYunCommonProvider _common;

    public QxyService(QiXiangYunCommonProvider common) => _common = common;

    // 获取已授权企业列表
    public async Task<IReadOnlyList<QiXiangYunEnterprise>> GetEnterprisesAsync(CancellationToken ct)
    {
        var result = await _common.GetEnterpriseListAsync(ct);
        return result.Success ? result.Data!.enterprises : Array.Empty<QiXiangYunEnterprise>();
    }

    // 订购产品
    public async Task<string> SubscribeAsync(string taxNumber, string productCode, CancellationToken ct)
    {
        var resp = await _common.SubscribeProductAsync(new QiXiangYunSubscribeRequest
        {
            taxNumber   = taxNumber,
            productCode = productCode,
            startDate   = "2026-07-23",
            endDate     = "2027-07-23"
        }, ct);
        return resp.Data?.orderNo ?? "";
    }
}

核心类型一览

以上业务 Provider 与模型当前为 internal，主要通过聚合包或抽象接口使用。

依赖

相关包

• Bitzsoft.Integrations.Finance.Tax -- 税务管理抽象层
• Bitzsoft.Integrations.Finance.All -- 财税管理全量聚合包（含本实现）
• Bitzsoft.Integrations.Compatibility -- 基础工具库
• Bitzsoft.Integrations.RequestLogging -- 出站请求记录