Bitzsoft.Integrations.Finance.Invoice.Kingdee 1.0.0-alpha.10

Bitzsoft.Integrations.Finance.Invoice.Kingdee

金蝶发票云服务实现 -- 对接金蝶发票云（票易通 / Piaozone）开放平台 API，提供发票全生命周期管理。

功能特性

• 完整开票能力：开具蓝字发票、红字冲销、作废（基于 IInvoiceProvider）
• 机动车与二手车：IKingdeeIssueProvider 提供机动车销售统一发票、二手车销售统一发票的开具 / 查询 / 红冲
• 数电异步开票：IKingdeeIssueProvider.IssueDigitalAsync 提交异步数电开票任务并通过 QueryDigitalAsyncResultAsync 轮询结果
• 红字信息表：IKingdeeIssueProvider.ApplyRedLetterAsync / QueryRedLetterAsync 支持增值税专用发票红冲前的红字信息表申请与查询
• 辅助查询：税控设备信息、票种信息、授信额度、电子发票库存、税收分类编码查询
• 企业级查询：IKingdeeQueryProvider 提供销项 / 进项发票的企业级批量查询
• 批量查验与 OCR：IKingdeeVerifyProvider 提供批量异步查验、批量 OCR 识别、批量识别并查验一体化（继承 IInvoiceOcrProvider）
• 进项抵扣闭环：IKingdeeInputProvider 提供税款所属期查询、进项采集、勾选 / 取消勾选、统计生成 / 撤回 / 确认、进项查询
• 聚合接口：IKingdeeInvoiceProvider 通过 Issue / Query / Verify / Input 属性聚合上述能力

安装

.NET CLI

dotnet add package Bitzsoft.Integrations.Finance.Invoice.Kingdee

PackageReference

<PackageReference Include="Bitzsoft.Integrations.Finance.Invoice.Kingdee" Version="1.0.0" />

配置

appsettings.json

{
  "Finance": {
    "Invoice": {
      "Kingdee": {
        "AppId": "金蝶提供的 AppId",
        "AppSecret": "双方约定的 AppSecret",
        "TaxNo": "企业税号",
        "BaseUrl": "https://api.kingdee.com/piaozone"
      }
    }
  }
}

含 AppSecret 等敏感信息，严禁序列化、日志输出或暴露给前端。

注册服务

从 IConfiguration 绑定（推荐）

using Bitzsoft.Integrations.Finance.Invoice.Kingdee;

builder.Services.AddBitzsoftKingdeeInvoice(
    builder.Configuration,
    "Finance:Invoice:Kingdee");

委托配置

builder.Services.AddBitzsoftKingdeeInvoice(options =>
{
    options.AppId = "金蝶提供的 AppId";
    options.AppSecret = "双方约定的 AppSecret";
    options.TaxNo = "企业税号";
});

注册后 Provider 为 Singleton，通过 KingdeeAuthHandler 自动注入令牌，同时注册聚合接口 IKingdeeInvoiceProvider、抽象接口 IInvoiceProvider / IInvoiceOcrProvider 与各角色接口。

第三方请求日志

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

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

使用示例

using Bitzsoft.Integrations.Finance.Invoice.Kingdee;
using Bitzsoft.Integrations.Finance.Invoice.Models;

// 注入聚合接口，通过属性访问各能力域
public class KingdeeService(IKingdeeInvoiceProvider kingdee)
{
    // 基础开票（来自 IInvoiceProvider）
    public Task<InvoiceIssueResult> IssueAsync(InvoiceIssueRequest req) => kingdee.IssueAsync(req);

    // 数电异步开票
    public async Task<InvoiceIssueResult> IssueDigitalAsync(InvoiceIssueRequest req)
    {
        var task = await kingdee.Issue.IssueDigitalAsync(req);
        // 轮询直到完成（实际应用中可间隔轮询）
        var result = await kingdee.Issue.QueryDigitalAsyncResultAsync(task.TaskId);
        return result.ToIssueResult();
    }

    // 进项勾选
    public Task TickAsync(IEnumerable<string> ids) => kingdee.Input.TickInvoiceAsync(ids);
}

// 或直接注入所需角色接口
public class VerifyOnlyService(IKingdeeVerifyProvider verify)
{
    public Task<string> BatchVerifyAsync(IEnumerable<InvoiceVerifyRequest> reqs)
        => verify.VerifyMultipleAsync(reqs);
}

核心类型一览

Provider 与注册

扩展接口

同时实现抽象层接口：IInvoiceProvider、IInvoiceOcrProvider。

金蝶特有模型（位于 Models/）

依赖

相关包

• Bitzsoft.Integrations.Finance.Invoice -- 发票管理抽象层
• Bitzsoft.Integrations.Finance.Invoice.All -- 发票管理聚合包
• Bitzsoft.Integrations.Finance.All -- 财税管理全量聚合包
• Bitzsoft.Integrations.Compatibility -- 基础工具库
• Bitzsoft.Integrations.RequestLogging -- 出站请求记录