InvoiceIn

InvoiceIn — 示例

企业收到的任意欧洲或阿联酋（PINT AE）电子发票 → 一份规范化的 EN 16931 JSON、一份附有通俗修正提示的验证报告，以及 PDF、CSV 或 DATEV 导出文件。 单个无状态端点，不存储任何内容。

支持：XRechnung（UBL 和 CII）、EN 16931 UBL 2.1 Invoice/CreditNote、Peppol BIS Billing 3、CII D16B、ZUGFeRD 1.0 / 2.x 和 Factur-X 混合 PDF、意大利 FatturaPA 1.2、波兰 KSeF FA(2)/FA(3)、罗马尼亚 RO e-Factura（CIUS-RO）、阿联酋 PINT AE（Billing 和 Self-Billing）。

验证依据：EN 16931 验证规则集 1.3.17、XRechnung 3.0.2（KoSIT Schematron 2.6.0）、Peppol BIS Billing 3、FNFE CTC-FR 1.4.0.04（BR-FR 规则；买卖双方均在法国设立时运行）、CIUS-RO 1.0.1、OpenPeppol 的阿联酋 PINT AE 1.0.4（免费检查页面：https://invoicein.peculiar.systems/uae）、UBL、CII、FatturaPA 和 KSeF 架构；此外还会对每种格式进行算术交叉检查，并检查 Schematron 无法读取的市场惯例（自由文本中的德国 Skonto 条款、波兰 KSeF 编号）。包含版本的实时列表见 GET /v1/formats。

• 产品页面：https://invoicein.peculiar.systems（EN · DE · PL · IT · FR）
• API 参考（交互式）：https://invoicein-api.peculiar.systems/docs
• OpenAPI：https://invoicein-api.peculiar.systems/openapi.json
• Postman：公开集合 · 已发布文档 — 或导入 postman/InvoiceIn.postman_collection.json。每个请求的请求体中都已附带真实的 XRechnung，因此无需任何设置即可点击 Send
• MCP 服务：https://invoicein-api.peculiar.systems/mcp（流式 HTTP）— 已列入官方注册表，名称为 io.github.peculiar-systems/invoicein，也已列入 Smithery

此仓库包含可运行的示例、可供测试的发票样例，以及 MCP 注册表清单。服务本身不是开源的。

您发送的内容不会被存储：文档在内存中解析，响应根据文档生成。隐私（完整政策） · 条款

bridge/ 中的桥接程序是透明代理，不是第二套实现：它会镜像托管服务返回的 tools/list 内容，因此两者绝不会出现偏差。五个工具及其注解——全部为只读、非破坏性、幂等、封闭世界——位于 bridge/tools.json，并由 tests/ 检查。只读取桥接源码的静态分析器只能看到一个分发回调，看不到任何工具；这是代理的特性，不代表工具接口的实际情况。

60 秒上手

curl -X POST "https://invoicein-api.peculiar.systems/v1/invoice?include=validation&lang=en" \
  -H "X-Api-Key: $INVOICEIN_KEY" \
  -F file=@samples/factur-x-en16931.pdf

还没有密钥？不填请求头即可：每个 IP 每天可处理 20 张发票，输出相同。试用密钥（100 张发票，有效期 30 天，无需银行卡）可从产品页面获取。

响应（完整示例）：

{
  "ok": true,
  "source":  { "syntax": "UBL", "format": "peppol-bis3", "profile": "Peppol BIS Billing 3.0", "container": "xml" },
  "invoice": {                         // canonical EN 16931, field names carry BT/BG numbers in /v1/schema
    "document": { "id": "Snippet1", "issue_date": "2017-11-13", "type_code": "380", "currency": "EUR", "due_date": "2017-12-01", ... },
    "seller":   { "name": "SupplierOfficialName Ltd", "vat_id": "GB1232434", "electronic_address": { "value": "9482348239847239874", "scheme": "0088" }, ... },
    "buyer":    { ... },
    "lines":    [ { "id": "1", "quantity": 7, "unit": "DAY", "net_amount": 2800, "tax": { "category": "S", "rate": 25 }, "item": { "name": "item name" } }, ... ],
    "tax_breakdown": [ { "taxable_amount": 1325, "tax_amount": 331.25, "category": "S", "rate": 25 } ],
    "totals":   { "line_net": 1300, "charges": 25, "net": 1325, "tax": 331.25, "gross": 1656.25, "due": 1656.25 },
    "payment":  { "means_code": "30", "remittance_info": "Snippet1", "credit_transfers": [ { "iban": "IBAN32423940", "account_name": "AccountName", "bic": "BIC324098" } ] }
  },
  "validation": { "valid": true, "errors": 0, "warnings": 0,
                  "rule_sets": [ { "id": "XSD:ubl-invoice" }, { "id": "EN16931-UBL", "version": "EN 16931 validation artefacts 1.3.17" }, { "id": "Peppol-UBL" } ],
                  "issues": [] },
  "timings_ms": { "detect": 0.5, "map": 14.4, "validate": 86.0, "total": 100.8 },
  "credits": { "mode": "key", "remaining": 99 }
}

出现问题时，每条未通过的规则都会附带所请求语言的提示（示例：波兰语 KSeF FA(3)）：

{ "id": "XSD-UNEXPECTED-ELEMENT", "severity": "error", "rule_set": "XSD:fa3",
  "message": "Element '{http://crd.gov.pl/wzor/2025/06/25/13775/}Adnotacje': This element is not expected. Expected is one of ( {http://crd.gov.pl/wzor/2025/06/25/1 …",
  "hint": "XML zawiera element, którego schemat nie dopuszcza w tym miejscu. Nazwa elementu jest błędna, element należy do innego profilu/wersji (np. UBL 2.0 lub ZUGFeRD EXTENDED), jest zdublowany albo jest własnym rozszerzeniem. Usuń go lub zmień jego nazwę.",
  "who": "sender", "location": "/*/*[4]/*[8]", "line": 43 }

端点

调用	返回内容
POST /v1/invoice?include=validation,html,pdf,csv,datev&lang=en|de|pl|it|fr	在一个 JSON 中返回所有内容（额外内容以 base64/内联形式提供）
POST /v1/parse	仅返回规范 JSON
POST /v1/validate	仅返回验证报告
POST /v1/render.html · POST /v1/render.pdf	便于阅读的呈现结果，标签支持五种语言
POST /v1/export.csv?level=lines|documents	扁平 CSV
POST /v1/export.datev?skr=03|04&creditor_account=70000	DATEV Buchungsstapel（EXTF 700，cp1252）
GET /v1/formats · GET /v1/rules/{id}?lang=de · GET /v1/schema	格式 + 规则版本 · 解释规则 ID · 字段指南
GET /v1/countries	各国规定的申报格式，以及我们用于验证的格式
GET /v1/vat/{number}	欧盟 VAT 号码：先离线检查格式，再实时查询 VIES，并附带注明日期的凭证
GET /v1/peppol/{id}	对方是否已在 Peppol 发布，以及可以接收哪些内容

请求正文：使用 multipart 字段 file，或直接发送原始 XML/PDF。请发送真实的 User-Agent（Cloudflare 会以错误 1010 拒绝默认的 Python-urllib）。身份验证：使用 X-Api-Key 或 Authorization: Bearer。每张发票消耗一个额度，无论请求哪些输出；包含多张发票的文件（FatturaPA lot）按每张发票消耗一个额度。剩余额度会通过 X-Credits-Remaining 返回。

本仓库中的示例

• examples/curl.sh — 每个端点各调用一次
• examples/node.mjs — 使用 fetch + FormData，无需依赖项
• examples/python.py — 仅使用标准库
• examples/n8n-workflow.json — 邮箱附件 → InvoiceIn → JSON，可导入 n8n
• mcp/server.json — MCP 注册表清单；mcp/clients.md — Claude Desktop / Cursor 配置
• bridge/invoicein_mcp_bridge.py — 本地 stdio MCP 服务，其工具与托管服务一一对应，并转发所有调用（适用于不支持远程服务的客户端；Dockerfile 用于构建它；bridge/tools.json 是工具定义的离线副本）

示例发票

文件	内容	来源 / 许可
samples/xrechnung-3.0-ubl.xml、samples/xrechnung-3.0-cii.xml	同一张 XRechnung 3.0 发票的两种语法形式	KoSIT XRechnung testsuite，Apache-2.0
samples/peppol-bis3-base-example.xml	Peppol BIS Billing 3 基础示例	OpenPeppol，Apache-2.0
samples/factur-x-en16931.pdf	Factur-X 混合 PDF，EN 16931 配置文件	ZUGFeRD corpus（FNFE-MPE 示例），Apache-2.0
samples/ksef-fa3-przyklad-1.xml	KSeF FA(3) 官方示例第 1 号	波兰财政部，公开
samples/fatturapa-fpr01.xml	FatturaPA 1.2 官方示例 FPR01	Agenzia delle Entrate，公开

这两个 XRechnung 文件会生成相同的规范 JSON（只有语法专属的 extensions 块不同）——这正是规范模型的意义所在。

它不做什么

不进行 OCR（不含嵌入式 XML 的 PDF 会被拒绝，并返回 pdf-no-xml）。它不是 Peppol 接入点、法国 PDP、阿联酋认可服务提供商、KSeF 或 SdI 客户端：它只读取你已经收到的内容，绝不会向任何地方传输发票。对于低于 EN 16931 的 Factur-X/ZUGFeRD 配置文件（MINIMUM、BASIC WL、BASIC），只执行架构和算术检查，因为 EN 16931 规则在这些情况下只会产生无用信息。验证结果仅供参考，不构成法律建议。

许可证

本仓库中的示例采用 MIT 许可证。示例发票保留上文所列的许可证。