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

Bitzsoft.Integrations.Finance.Invoice.Baiwang

百旺金赋发票服务实现 -- 对接百旺金穗云 SaaS 开放平台 API，提供发票全生命周期管理。

功能特性

• 完整开票能力：开具蓝字发票、红字冲销、作废（基于 IInvoiceProvider）
• 特有开票模式：IBaiwangIssueProvider 提供数电蓝字发票、数电纸票、折扣行、差额征收开票（digitalBlueInvoice / digitalPaperInvoice / discountInvoice / differentialInvoice）
• 精确查询：IBaiwangQueryProvider 按业务订单号或发票号码精确查询
• 查验与采集：IBaiwangVerifyProvider 提供新版查验、乐企查验、采集发票保存与查询，并继承 IInvoiceOcrProvider
• 企业信息：IBaiwangEnterpriseProvider 提供智能抬头查询、税控设备查询、开票终端查询、票种查询
• 进项全流程：IBaiwangInputProvider 提供进项同步、版式文件下载、勾选 / 取消勾选、入账、统计查询
• 库存管理：IBaiwangStockProvider 提供剩余票量查询、待开票号获取
• 税局登录与实人认证：IBaiwangInvoiceProvider 提供电子税务局登录、实人认证二维码与结果轮询、数电红冲结果查询
• 聚合接口：IBaiwangInvoiceProvider 一次性聚合上述全部能力

安装

.NET CLI

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

PackageReference

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

配置

appsettings.json

{
  "Finance": {
    "Invoice": {
      "Baiwang": {
        "GatewayKey": "百旺提供的网关密钥标识",
        "Secret": "双方约定的网关密钥",
        "TaxNumber": "企业税号",
        "BaseUrl": "https://api.baiwangjs.com"
      }
    }
  }
}

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

注册服务

从 IConfiguration 绑定（推荐）

using Bitzsoft.Integrations.Finance.Invoice.Baiwang;

builder.Services.AddBitzsoftBaiwangInvoice(
    builder.Configuration,
    "Finance:Invoice:Baiwang");

委托配置

builder.Services.AddBitzsoftBaiwangInvoice(options =>
{
    options.GatewayKey = "百旺提供的网关密钥标识";
    options.Secret = "双方约定的网关密钥";
    options.TaxNumber = "企业税号";
});

注册后 Provider 为 Singleton，通过 BaiwangAuthHandler 自动完成 HMAC 签名，同时注册聚合接口 IBaiwangInvoiceProvider 与各角色接口。

第三方请求日志

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

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

使用示例

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

// 注入聚合接口（含全部能力）
public class BaiwangService(IBaiwangInvoiceProvider baiwang)
{
    // 基础开票（来自 IInvoiceProvider）
    public Task<InvoiceIssueResult> IssueAsync(InvoiceIssueRequest req) => baiwang.IssueAsync(req);

    // 数电蓝字发票
    public Task<InvoiceIssueResult> IssueDigitalAsync(InvoiceIssueRequest req)
        => baiwang.IssueDigitalBlueInvoiceAsync(req);

    // 智能抬头查询
    public Task<IReadOnlyList<SmartTitleInfo>> GetTitleAsync(string keyword)
        => baiwang.GetSmartTitleAsync(keyword);
}

// 或仅注入所需角色接口
public class InputOnlyService(IBaiwangInputProvider input)
{
    public Task SyncAsync(DateTime start, DateTime end)
        => input.SyncInputInvoicesAsync(start, end);
}

核心类型一览

Provider 与注册

扩展接口

IBaiwangInvoiceProvider 还提供：QueryRedFlushResultAsync（数电红冲结果轮询）、LoginTaxBureauAsync（电子税务局登录）、GetRealPersonAuthQRCodeAsync / QueryAuthResultAsync（实人认证）。

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

依赖

相关包

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