openfactura-cli：实践指南

面对实际交付，我看openfactura-cli的重点不在星标，而在这项能力：OpenFactura（Haulmer）的API的非官方CLI：为SII签发和查阅电子税务文件，具有克劳德代码的技巧。一旦进入软件开发环节，依赖、接口和异常处理往往比主路径更影响采用会直接影响交付，这也是我最关心的风险。试跑可以从在隔离分支完成一个可回滚的小任务开始，并把安装步骤、接口契约、测试结果和错误信息写进验收记录。对需要可检查开发流程而非单次演示的工程师来说，这个仓库值得继续验证；只求即装即用的人则要先看维护成本。

openfactura-cli

CLI 为 OpenFactura (Haulmer) 的 API：发布并查阅文件 来自终端的电子税 SII。本来是打算让克劳德来帮你操作的，但是 用手操作也是一样的。

• 涵盖完整记录的API：发布、文件咨询、发布、收到、确认、 采购和销售记录、纳税人档案和注销指南。
• 解决API里面的陷阱：收据与发票的方案不同，PDF在 base64、过滤器被默默忽略、每秒调用次数限制、三个错误 不同的格式。
• 默认情况下问题是干的。没有--confirmar，组装文档，计算总数并给你。 显示而不发送任何内容到 SII。
• 始终输出 JSON。运行时零依赖。

安装

您需要 Node 20 或更高版本。

npm install -g https://github.com/Lelemon-studio/openfactura-cli/releases/download/v0.1.0/openfactura-cli-0.1.0.tgz
openfactura --version

这些版本位于 版本 中。还有 从本地副本工作：git clone https://github.com/Lelemon-studio/openfactura-cli，并在 npm install -g . 文件夹

在 Windows 上，避免 npm install -g github:Lelemon-studio/openfactura-cli：npm 使命令指向 然后删除临时文件夹，并且 openfactura 失败并显示 Cannot find module。

如果没有 Node，Windows 二进制文件将使用 bun run build 构建，并保留为 dist/openfactura.exe。对于 其他系统：bun build src/main.ts --compile --target=bun-linux-x64 --outfile dist/openfactura （或 bun-darwin-arm64、bun-darwin-x64）。

API 密钥

API 密钥来自您的 OpenFactura 帐户。将其保留在环境变量中，而不是文件中 版本控制：

export OPENFACTURA_API_KEY="tu-clave"          # macOS / Linux
$env:OPENFACTURA_API_KEY = "tu-clave"          # PowerShell

每个命令中也接受 OPENFACTURA_KEY 或 --api-key。该密钥永远不会出现在输出中 也不在错误消息中。

第一步

openfactura emisor                    # ¿con qué empresa estoy operando?
openfactura ventas 2026-09            # resumen de ventas del mes
openfactura contribuyente 76430498-5  # ficha SII de un RUT

开具发票，先干：

openfactura emitir factura --receptor 76430498-5 --item "Servicio de septiembre|1|100000"

输出带来了带有接收器、净值、IVA 和总计的 resumen，以及完整的 DTE。如果没问题的话，重复一遍 命令为 --confirmar。重复完全相同的命令不会发出两次：关键 幂等性是文档的哈希值，OpenFactura 会记住它 24 小时。

openfactura emitir factura --receptor 76430498-5 --item "Servicio de septiembre|1|100000" --confirmar --esperar 120

命令

openfactura <comando> --help 显示每一项的所有选项。

与克劳德代码

openfactura instalar-skill

将技能保留为~/.claude/skills/openfactura/。从那里你只需要问克劳德诸如此类的问题 “向76,430,498-5开具10万净额发票”或“SII是否接受31号发票？”技巧 表示向您展示干摘要并等待您批准后再发布。

测试环境

--dev（或OPENFACTURA_ENV=dev）指向dev-api.haulmer.com。 OpenFactura 文档 与测试发行者一起发布该环境的演示密钥 928e15a2d14d4a6292345f04960f4bd3。 那里发出的内容没有达到SII。

OPENFACTURA_API_KEY=928e15a2d14d4a6292345f04960f4bd3 openfactura emitir boleta --dev --item "Prueba|1|1190" --confirmar

发展

bun install
bun test               # tests unitarios, sin red
bun run typecheck
bun scripts/probar-dev.ts   # emite todos los tipos contra el ambiente de pruebas
bun run build          # dist/cli.js para Node y dist/openfactura(.exe)

dist/cli.js 已进行版本控制，因此可以直接从 GitHub 安装，无需 Bun。之后 更改 src/，运行 bun run build:node 并提交结果：如果 CI 过时，则失败。

API 的目录，每条信息都标记为根据实际、记录或推断的 API 进行验证， 位于 docs/API.md。

许可证

MIT。由 Lelemon 制造。它不是 Haulmer 或 OpenFactura 的官方产品。