Mitzh.Invoice.Api 1.0.0

Mitzh.Invoice.Api

基于 ASP.NET Core 8 的离线发票识别服务，提供 Swagger、同步文件/流、XML 内容及可选后台任务接口。以 .NET 工具包发布，命令名 mitzh-invoice-api，不是可引用的类库包；在 C# 中嵌入解析请安装 Mitzh.Invoice.Core。

安装与启动

本机需有 .NET 8 SDK（工具安装）和 ASP.NET Core 8 Runtime（服务运行）。

dotnet tool install --global Mitzh.Invoice.Api --version 1.0.0
$env:Limits__ApiKey = 'replace-with-your-own-key'
mitzh-invoice-api --urls http://127.0.0.1:5088

默认 Production 要求设置 API key。可用 --Limits:ApiKey=...、环境变量或 .NET 常规配置设置参数，建议环境变量。Swagger 地址：http://127.0.0.1:5088/swagger/index.html，Authorize 填入 key，不添加 Bearer 前缀。

工具包含配套中文 OCR 模型；扫描 PDF 另外安装本机 pdftoppm 并加入 PATH，或设置 $env:Limits__PdfToPpm 为完整路径。原生文字 PDF/XML/OFD 无需 PDF 图片渲染程序。模型可由 Limits__DetModel、Limits__ClsModel、Limits__RecModel、Limits__Dictionary 覆盖。

上传文件

curl.exe -H "X-Api-Key: replace-with-your-own-key" -F "file=@D:\invoices\sample.pdf" http://127.0.0.1:5088/api/invoices/recognize

文件流（不要求 multipart 或文件名）：

curl.exe -H "X-Api-Key: replace-with-your-own-key" -H "Content-Type: application/octet-stream" --data-binary "@D:\invoices\sample.ofd" http://127.0.0.1:5088/api/invoices/recognize

XML 内容：

$headers = @{ 'X-Api-Key' = 'replace-with-your-own-key' }
$body = @{ xml = Get-Content -Raw 'D:\invoices\sample.xml' } | ConvertTo-Json
Invoke-RestMethod -Method Post -Uri 'http://127.0.0.1:5088/api/invoices/recognize/xml' -Headers $headers -ContentType 'application/json; charset=utf-8' -Body $body

C# HTTP 客户端：

using System.Net.Http.Json;
using Mitzh;

using var client = new HttpClient { BaseAddress = new Uri("http://127.0.0.1:5088") };
client.DefaultRequestHeaders.Add("X-Api-Key", "replace-with-your-own-key");
await using var input = File.OpenRead(@"D:\invoices\sample.pdf");
using var content = new StreamContent(input);
using var response = await client.PostAsync("/api/invoices/recognize", content);
var result = await response.Content.ReadFromJsonAsync<InvoiceResponse<InvoiceModel>>();
if (result?.Code != 0)
{
    throw new InvalidOperationException(result?.Msg ?? "API request failed.");
}
InvoiceModel invoice = result.Data;

public sealed record InvoiceResponse<T>(int Code, string Msg, T Data);

客户端引用 Mitzh.Invoice.Core 仅用于 InvoiceModel 类型；远程服务执行识别，客户端不必加载模型。

响应与接口

成功为 {"code":0,"msg":null,"data":...}；失败为 {"code":1,"msg":"异常信息或校验说明","data":null}，同时保留 HTTP 400/401/404/413/415/422/429/500/503/504。解析字段缺失可能返回成功并带 warnings，仍需复核。

进程内后台任务和疑似查重不持久化；默认 20 MiB/30 页/120 秒，4 个并发上传。临时数据默认写入操作系统临时目录 Mitzh.Invoice.Api，可设置 Limits__TempDirectory。远程部署请配置 AllowedHosts、HTTPS 反向代理与访问控制；默认绑定本机。

解析不代表数字签名验证或税务验真。 模型、第三方库及外部 Poppler 各自遵守其许可证。完整源码、格式规范及调用说明：Mitzh/InvoiceParser。