VeriFactu

verifactu-mcp

在 PyPI 上的名称为 verifactu-keyflint-mcp（名称 verifactu-mcp 属于另一个项目）。

面向为 gestorías、会计师和开票软件团队提供服务的 AI Agent 构建的西班牙发票合规 MCP 服务。离线且无状态：不会存储任何内容，也不会向 AEAT 发送任何内容。

• 审计 VERI*FACTU 链：按照 AEAT 规定，重新计算每条记录（ alta 和 anulació）的 SHA-256 指纹（huella），并检查每条记录是否链接到上一条记录。支持 JSON 记录，也支持任何开票程序导出的 XML（根据官方 SuministroLR.xsd 验证）。
• AEAT 税务二维码：为 VERI*FACTU 和非 VERI*FACTU 系统生成 URL 和 PNG/SVG 图像（纠错级别 M），支持生产或测试门户，并提供打印规则。
• Facturae 3.2.2：根据普通数据（总额、增值税明细、IRPF 预扣税、recargo de equivalencia、FACe 的 DIR3 代码、IBAN）生成发票，并验证任何 Facturae 文件：官方 XSD、FACe 算术检查、NIF、DIR3 角色和签名是否存在。

指纹代码已根据 AEAT 发布的三个参考向量进行测试。

工具

工具	积分	功能
validate_invoice_chain	3	审计记录链（JSON，最多 20,000 条）：指纹、链接、PrimerRegistro、重复项、未知发票的作废记录、时间戳、NIF/日期/金额/TipoFactura 格式。continues_from 用于分段审计记录链。
validate_verifactu_xml	3	对导出的 XML（RegFactuSistemaFacturacion、SOAP 信封，或任何包含 RegistroAlta/RegistroAnulacion 的 XML）执行相同审计，并进行 XSD 验证。
verifactu_hash	1	计算单条记录的指纹，并显示实际参与哈希计算的字符串。
generate_verifactu_qr	1	税务二维码 URL、图像和打印规则。
build_facturae	3	根据普通发票数据生成 Facturae 3.2.2 XML（未签名），并通过 XSD 验证。
validate_facturae	2	检查 Facturae 文件的 XSD、算术、NIF、DIR3 和签名。
verifactu_calendar	免费	当前有效期限和 BOE 中尚待处理的事项，并附来源。
check_qr_url、validate_nif、pricing、credits_balance	免费	辅助工具。

无法读取或无效的输入不会收费；已收费后失败的工具会退还积分。

安装

Claude Desktop / Claude Code / Cursor（mcpServers 条目）：

{
  "verifactu": {
    "command": "uvx",
    "args": ["--from", "verifactu-keyflint-mcp", "verifactu-mcp"],
    "env": { "KEYFLINT_LICENSE": "LIC-..." }
  }
}

托管（一个服务，多个买家）：使用 verifactu-mcp --http 或 Dockerfile；每个请求都需携带 Authorization: Bearer LIC-...。

环境变量：KEYFLINT_LICENSE、KEYFLINT_URL、KEYFLINT_PUBLIC_KEYS、KEYFLINT_CHECKOUT_URL、 VERIFACTU_PRICES（例如 validate_invoice_chain=5,build_facturae=4）、VERIFACTU_MAX_BYTES（默认值为 10 MB）。

可视化卡片（MCP Apps）

在 Claude、ChatGPT、VS Code 和 Goose 中，每个付费工具和 credits_balance 都会在聊天中呈现为交互式卡片：显示带充值进度条和购买按钮的积分余额，或结果摘要（关键数据、问题、表格预览和已扣积分）。它是 ui://verifactu/card.html 资源，独立运行且不访问网络。其他客户端仍会收到与之前相同的 JSON。

法律状态（截至 2026-11-05 已核查）

• VERI*FACTU（RD 1007/2023、Orden HAC/1177/2024；日期依据 RD-ley 15/2025）：企业所得税纳税人自 2027 年 1 月 1 日起适用，其他所有纳税人自 2027 年 7 月 1 日起适用。Hacienda 于 2026 年 10 月 5 日宣布将进一步延至 2028 年 10 月，但尚未在 BOE 发布。适用 SII 的纳税人和各自治法区不在适用范围内。
• 强制 B2B 电子发票（RD 238/2026、Orden HAC/1028/2026）：营业额超过 800 万欧元的企业自 2027 年 10 月 6 日起适用，其余企业自 2028 年 10 月 6 日起适用；格式为 UBL、CII、EDIFACT 或 Facturae，符合 EN 16931 标准。
• 通过 FACe 向公共行政机构开具的发票必须带有 XAdES 签名的 Facturae。

verifactu_calendar 会返回这些信息及其来源。请务必在 BOE 中确认。

范围与限制

• 这不是开票系统（SIF）：它不保存记录，不向 AEAT 发送任何内容，也不能替代生产商的 declaración responsable。可用它检查 SIF 生成的内容，或准备数据。
• build_facturae 生成的是未签名的 XML。发送到 FACe 或 B2B 平台前，需使用开票方的证书对其进行签名（XAdES-EPES）。更正发票（InvoiceClass OR）和批次目前仅进行验证，尚未生成。
• 如果存储的指纹只有在移除金额末尾的零后才匹配，则会报告警告（correcta_sin_ceros）：记录中的金额写法与 XML 不同。

来源

• AEAT，《Detalle de las especificaciones técnicas para generación de la huella o hash de los registros de facturación》（参考向量见 tests/test_core.py）。
• AEAT，《Características del QR y especificaciones del servicio de cotejo》。
• AEAT Web 服务架构 SuministroLR.xsd / SuministroInformacion.xsd，以及 Facturaev3_2_2.xsd（facturae.gob.es）；这些文件与 W3C xmldsig 架构一同打包在 src/verifactu_mcp/schemas/ 中。

开发

pip install -e '.[test]'
pytest -q

Business Source License 1.1。源代码可用；用于生产环境需要 KeyFlint 许可证（或仅限非商业用途）。每个版本在发布四年后转为 Apache 2.0。详见 LICENSE。随附的 XSD 文件归其发布方（AEAT、Ministerio de Hacienda、W3C）所有。