gofact

gofact

🇫🇷 法语版本

小型 Go 二进制程序，可将可直接打印的 HTML 发票转换为 Factur-X：符合规范的 PDF/A-3，其中嵌入了 CII EN 16931 XML；还可选择将其提交至法国电子发票平台（PDP — 合作数字化平台）。

专为法国自由职业者或小型企业开具发票而构建（适应法国电子发票改革），并以 Claude Code 插件的形式提供，附带 creer-facture 技能。

流程

JSON  ──EN 16931 rules──▶  rejected if non-compliant (before producing anything)
      ──gofact──────────▶  factur-x.xml (CII EN 16931)
HTML  ──headless Chrome─▶  PDF          (identical to Ctrl+P output, backgrounds included)
PDF + XML ──pure Go─────▶  Factur-X     (PDF/A-3 + VERBATIM embedding of the XML)
Factur-X  ──self-check──▶  re-read      (structure + integrity of the embedded XML)

原样嵌入——重要。 XML 按字节级原样嵌入。 如果组装器通过自身模型重新序列化 XML，扩展字段就会丢失，尤其是 PDP 电子路由地址（BT-34/BT-49）。 gofact 不会触碰其生成的 XML。

系统依赖项

只需要浏览器。

• Chrome、Edge、Brave 或 Chromium — HTML → PDF 渲染

可在 Linux、macOS 和 Windows 上自动检测（Windows 预装了 Edge，因此无需额外操作）。会跳过沙盒化软件包——snap、flatpak——因为它们无法读取 gofact 提供的临时文件。若要指定特定可执行文件： GOFACT_CHROME 或 -chrome。

PDF/A-3 组装由 Go（pdfcpu）完成：无需 Ghostscript、Java，也无需首次运行时下载。sRGB ICC 配置文件已嵌入二进制文件。

合规性

在两个不同时间点进行两项检查：

• EN 16931 业务规则，在生成任何内容之前应用于模型。gofact 会拒绝开具已知不合规的发票，并报告规则标识符（BR-50、BR-CO-15……）以及需要修正的字段。
• PDF 自检，在写入后进行：重新读取文件，验证 Factur-X 结构（/AF、/OutputIntents、XMP、/EmbeddedFiles），并将嵌入的 XML 与生成的 XML 逐字节比较。

深度 PDF/A-3b 合规性通过 Mustang 调用 veraPDF 验证，在持续集成中进行——绝不在用户的机器上运行：

GOFACT_ORACLE_HTML=facture.html go test -tags=ci ./internal/facturx

构建

go build -o gofact .
go test ./...

配置

不会硬编码身份信息或密钥。 发票开具方、付款 IBAN 和 PDP 凭据均来自环境变量。

cp .env.example .env    # then fill in your own values

gofact 按以下顺序加载变量，且绝不会覆盖已定义的变量：-env 指定的文件；否则为 ./.env；然后是 $XDG_CONFIG_HOME/gofact/.env（默认路径为 ~/.config/gofact/.env）。.env 已加入 Git 忽略列表——切勿提交。

变量	用途
GOFACT_SELLER_NAME	销售方名称。除非 JSON 中包含 seller 块，否则为必填项。
GOFACT_SELLER_SIRET / GOFACT_SELLER_SIREN	法国法定标识符（BT-30）。SIREN 根据 SIRET 推导。
GOFACT_SELLER_VAT_NUMBER	欧盟内部 VAT 号码（BT-31）。适用 293 B 免税制度时留空 ⇒ BT-32 = SIREN。
GOFACT_SELLER_EMAIL	销售方电子邮件。
GOFACT_SELLER_ADDRESS / _POSTAL_CODE / _CITY / _COUNTRY	邮寄地址（国家/地区默认为 FR）。
GOFACT_SELLER_ELECTRONIC_ADDRESS / _SCHEME	Peppol 路由 BT-34。留空 ⇒ SIREN，方案为 0225。
GOFACT_PAYEE_IBAN	收款方 IBAN（BT-84）。留空 ⇒ 发票中省略。
GOFACT_VAT_EXEMPTION_MENTION / _CODE	默认免税说明和代码（293 B）。
SUPERPDP_CLIENT_ID / SUPERPDP_CLIENT_SECRET / SUPERPDP_BASE	PDP 凭据（机密信息），仅用于 -send。

未配置销售方时，gofact 会明确报错，而不是开具不完整的发票。仍可在每张发票对应的 JSON 中覆盖所有值。

MCP 服务——与 AI 对话即可开具发票

gofact mcp 会将开票功能作为**本地 MCP 服务（stdio）**提供：在 Claude Desktop、Claude Code、LM Studio 或任何 MCP 客户端中，只需说“给 ACME 开一张 发票，2 天，每天 600 欧元”即可。AI 是交互界面；gofact 则确保编号（连续的法定 序列，采用锁定和事务性分配）、符合 EN 16931 标准并完成归档——一切都在本地进行。

# Register in Claude Code, for example:
claude mcp add gofact -- /path/to/gofact mcp

工具：list_organizations、get_organization、init_organization、 update_organization、 search_client、get_invoice_template、preview_next_number、list_invoices、 create_invoice、send_invoice（唯一具有破坏性的工具——提交至 PDP， 需要明确确认）、get_invoice_status。提示词：nouvelle-facture。

组织（开票实体）= 一个独立目录：.env 中的身份信息、numerotation.json 登记簿、journal.ndjson 审计日志、首次开票时冻结的发票模板，以及发票本身。CLI 管理命令：gofact org list | init | show。工具响应绝不会泄露任何机密。

用法（CLI）

# Simplest form: -data and -out derived from the HTML file name
gofact -html "2026011 - Client.html"
#   → reads "2026011 - Client.json", writes "2026011 - Client.pdf"

# Explicit paths + XML dump for debugging
gofact -html f.html -data f.json -out f.pdf -xml f.xml

# Options
-env <path>       # explicit .env file
-validate=false   # skip the self-check of the produced PDF
-chrome <path>    # force the Chrome executable
-q                # quiet (errors only)

Factur-X 生成成功时退出码为 0（使用 -validate 时，还须符合规范）。

提交至 PDP（SuperPDP）

gofact 会通过 SuperPDP 提交 Factur-X PDF（OAuth2 客户端凭据）。

# generate then submit in one command
gofact -html f.html -send -poll
# submit an already-generated PDF
gofact send -pdf f.pdf -poll

PDP 要求发票卖方 = 已通过身份验证的账户所属公司（法定标识符 BT-30）， 且开票方和收票方都必须具有电子路由地址 （BT-34/BT-49，方案 0225）。参见下文的 electronic_address。-poll 会显示 生命周期（fr:200 已提交 → fr:201 已开具 → fr:202 已接收）。

JSON 格式（附属文件）

所有金额均以分为单位（整数）。卖方、IBAN、增值税制度和法国法定声明 都有默认值（来自环境）——JSON 只包含会变化的内容。

{
  "number": "2026011",
  "type": "invoice",
  "issue_date": "2026-06-29",
  "buyer_reference": "D2026004",
  "buyer": {
    "name": "ACME SAS",
    "siret": "55208131700015",
    "email": "[email protected]",
    "address": "1 rue de la Paix",
    "postal_code": "75002",
    "city": "Paris",
    "country_code": "FR"
  },
  "lines": [
    { "name": "Développement", "unit": "day", "quantity": "2.00",
      "unit_price_ht_cents": 60000, "amount_ht_cents": 120000 }
  ]
}

可选字段：due_date（默认为“收到时”，即开票日期）、 delivery_date（默认为开票日期）、currency（默认为 EUR）、vat （默认为免税类别 293 B；标准增值税请设置 {"exempt": false, "rate_pct": "20.00"}）、 seller、iban、title（发票主题，记录在登记簿中）、notes。

备注：法国的三项法定声明——逾期付款罚金（PMD）、 追偿费用（PMT）、折扣（AAB）——始终会生成（BR-FR-05）。notes 会在此基础上追加内容：不带 subject_code 的备注会作为一般信息 （AAI）发送；带有 PMD、PMT 或 AAB 的备注则会替换对应代码的默认声明。任何规范都不能将这些声明移除：否则生成会被拒绝。

PDP 路由：seller/buyer 接受 electronic_address（BT-34/BT-49）和 electronic_address_scheme（例如 "0225"）。PDP 根据这些地址路由， 而不是根据邮政地址。如果未声明地址，则会使用从 SIRET 推导出的 SIREN 和方案 0225 为双方路由；仅当不存在法定标识符时才会使用电子邮件（EM）——目录中不包含此地址，且此时 send_invoice 会拒绝提交。示例（覆盖卖方信息）：

"seller": {
  "name": "Studio Exemple", "siren": "123456789",
  "electronic_address": "123456789", "electronic_address_scheme": "0225"
}

安装

预编译二进制文件（GitHub 发布版，无需工具链）：

curl -fsSL https://raw.githubusercontent.com/kolapsis/gofact/main/install.sh | sh
gofact install -yes    # registers the MCP server in the detected clients

gofact install 会检测 Claude Desktop、Claude Code、LM Studio 和 Cursor，显示计划写入的内容（默认采用试运行模式），修改前备份每个文件，并且不会在未使用 -force 的情况下覆盖有差异的条目。Windows：install.ps1。

包管理器——cask 和清单都位于此仓库，因此需要使用显式 URL（Homebrew 的简写 brew tap 形式要求仓库名称为 homebrew-*；Homebrew core 和 Scoop 主存储桶都设有知名度门槛，而 gofact 尚未达到该门槛）：

brew tap kOlapsis/gofact https://github.com/kOlapsis/gofact
brew install kOlapsis/gofact/gofact

scoop bucket add gofact https://github.com/kOlapsis/gofact
scoop install gofact

Claude Code 插件——此仓库也是一个插件：包含 creer-facture 技能和声明的 MCP 服务：

/plugin marketplace add kolapsis/gofact
/plugin install gofact@gofact

从源代码构建：go build -o gofact .

组织数据存放在本地目录（身份信息、注册信息、发票）中——不会在此处进行版本控制：这些目录包含真实数据。为兼容历史技能，仍支持 GOFACT_INVOICES_DIR。

已知限制

• 渲染依赖 Blink 浏览器；忽略沙盒化软件包（snap、flatpak），因为它们无法读取 $HOME 目录以外的内容。
• 仅支持单一增值税税率。不支持多税率。
• 货币不是 EUR：必须由上游提供以 EUR 计的增值税折算金额（BT-111）（模型的 VATEur 字段）；目前尚未在 JSON 中公开。
• 仅实现了一个 PDP（SuperPDP）。

许可证

GNU AGPL v3 或更高版本——参见 LICENSE。

版权所有 (C) 2026 Benjamin Touchard。

gofact 是自由软件：你可以根据自由软件基金会发布的 GNU Affero 通用公共许可证条款重新分发和／或修改它；许可证版本为第 3 版或（由你选择）任何更高版本。发布 gofact 是希望它有用，但不提供任何担保；也不提供任何关于适销性或特定用途适用性的默示担保。