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

Bitzsoft.Integrations.Finance.Invoice

发票管理服务抽象层 -- 定义开具、红冲、查验、查询、交付等统一接口与基础模型。

功能特性

• 全票种覆盖：传统发票（发票代码 + 发票号码）与数电票（仅发票号码）两种模式统一建模
• 核心开票能力：IssueAsync 开具蓝字发票、RedFlushAsync 红字冲销、CancelAsync 作废
• 查询与查验：QueryAsync 日期范围分页查询、VerifyAsync 真伪查验、GetDetailAsync 完整详情
• 发票交付：DeliverAsync 邮箱 / 短信推送（InvoiceDeliveryMethod）
• 能力扩展：OCR 识别（IInvoiceOcrProvider）、税收分类编码智能匹配（ITaxCodeMatchProvider）独立接口，按 is 检查按需使用
• 领域异常：InvoiceException 派生自 FinanceException，统一携带供应商名称与错误码

安装

.NET CLI

dotnet add package Bitzsoft.Integrations.Finance.Invoice

PackageReference

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

配置

本包为抽象层，不定义 Options 类，不读取配置节。各供应商的配置项由实现包定义（如诺诺 NuonuoOptions、百旺 BaiwangOptions、金蝶 KingdeeOptions）。

注册服务

本包为抽象层，ServiceCollectionExtensions 仅作命名空间占位，不提供具体注册方法。具体供应商由实现包注册，或使用聚合包一次性注册：

// 发票管理聚合包（详见聚合包文档）
using Bitzsoft.Integrations.Finance.Invoice.All;

services.AddBitzsoftInvoiceAll(configuration);

使用示例

开具发票

using Bitzsoft.Integrations.Finance.Invoice.Interfaces;
using Bitzsoft.Integrations.Finance.Invoice.Models;
using Bitzsoft.Integrations.Finance.Invoice.Enums;

public class InvoiceService
{
    private readonly IInvoiceProvider _invoice;

    public InvoiceService(IInvoiceProvider invoice) => _invoice = invoice;

    public async Task<InvoiceIssueResult> IssueAsync()
    {
        var request = new InvoiceIssueRequest
        {
            OrderNo      = "ORD20260701001",   // 销方税号下唯一，用于幂等
            InvoiceType  = InvoiceType.DigitalNormal,
            Buyer        = new BuyerInfo { /* 购方信息 */ },
            Items        =
            [
                new InvoiceItem { /* 明细行 */ }
            ],
            PushMode     = InvoiceDeliveryMethod.Email
        };

        return await _invoice.IssueAsync(request);
    }
}

查验发票

var verify = await _invoice.VerifyAsync(new InvoiceVerifyRequest
{
    InvoiceCode    = null,            // 数电票传 null
    InvoiceNumber  = "2444...",
    InvoiceDate    = new DateTime(2026, 7, 1),
    InvoiceAmount  = 11300m,          // 含税金额
    CheckCode      = "123456"         // 校验码后六位（可选）
});

交付发票

await _invoice.DeliverAsync(new InvoiceDeliveryRequest
{
    InvoiceCode   = null,
    InvoiceNumber = "2444...",
    Method        = InvoiceDeliveryMethod.EmailAndSms,
    Email         = "buyer@example.com",
    Phone         = "138..."
});

按需使用扩展能力

// OCR 识别查验一体化（供应商实现 IInvoiceOcrProvider 时可用）
if (_invoice is IInvoiceOcrProvider ocr)
{
    var result = await ocr.RecognizeAndVerifyAsync(imageBytes);
}

// 税收分类编码智能匹配（供应商实现 ITaxCodeMatchProvider 时可用）
if (_invoice is ITaxCodeMatchProvider matcher)
{
    var code = await matcher.MatchTaxCodeAsync("软件开发服务");
}

核心类型一览

接口（位于 Interfaces/）

IInvoiceProvider 方法

请求模型

响应模型

实体与枚举

依赖

相关包

• Bitzsoft.Integrations.Finance.Invoice.Nuonuo -- 诺诺发票实现
• Bitzsoft.Integrations.Finance.Invoice.Baiwang -- 百旺发票实现
• Bitzsoft.Integrations.Finance.Invoice.Kingdee -- 金蝶发票实现
• Bitzsoft.Integrations.Finance.Invoice.All -- 发票管理聚合包
• Bitzsoft.Integrations.Finance -- 财税管理公共基础
• Bitzsoft.Integrations.Compatibility -- 基础工具库