SmartBill 开票系统

请使用 scripts/smartbill_cli.py 执行确定性的 SmartBill API 调用，而非临时编写的 HTTP 片段代码。

工作流程

1. 从用户处收集发票输入数据。
2. 发送前在本地验证载荷（payload）：
   • python scripts/smartbill_cli.py validate-payload --input references/invoice-example.json --show-payload
3. 执行试运行（dry-run），仅检查标准化后的载荷，不实际调用 API：
   • python scripts/smartbill_cli.py create-invoice --input --dry-run
4. 在获得用户明确确认后，签发正式发票：
   • python scripts/smartbill_cli.py create-invoice --input --allow-final
5. 当已知发票系列（series）和编号（number）后，获取 PDF 文件：
   • python scripts/smartbill_cli.py download-invoice-pdf --series-name --number --output
   • 必须使用 SmartBill 返回的原始 number 字符串（含前导零，例如 "0123"）。不得去除前导零，也不得将其转换为整数。
   • --output 参数支持绝对路径或相对路径，且路径结尾必须为 .pdf。

必需的运行环境

调用 SmartBill 前，请设置以下环境变量：

• SMARTBILL_USERNAME — SmartBill 登录邮箱
• SMARTBILL_TOKEN — SmartBill API Token
• SMARTBILL_COMPANY_VAT_CODE — 默认 CIF（可选，但建议设置）

可选覆盖项：

• SMARTBILL_API_BASE（默认值：https://ws.smartbill.ro/SBORO/api）
• SMARTBILL_TIMEOUT_SECONDS（默认值：30）
• SMARTBILL_RETRIES（默认值：2）
• SMARTBILL_DEBUG（默认未设置）— 设为 1、true 或 yes 可启用请求/响应调试日志，并输出至 stderr

命令说明

• validate-payload
  • 解析并标准化载荷结构（支持裸发票对象，也支持带 { "invoice": {...} } 包裹层的格式）。
  • 在调用 API 前校验最小必需字段结构。
• create-invoice
  • 通过 POST /invoice 创建发票。
  • 需指定 --allow-final 参数方可签发正式发票（非草稿）。
  • 支持 --dry-run（仅打印标准化后的载荷，不发起 API 调用）及 --force-draft 参数。
  • 传入 --debug 参数（或设置 SMARTBILL_DEBUG=1）可在 stderr 中打印完整的请求与响应载荷。
• get-series
  • 通过 GET /series 查询当前可用的 SmartBill 发票系列。
• download-invoice-pdf
  • 通过 GET /invoice/pdf 使用 CIF + 系列名 + 编号组合获取 PDF 文件。
  • --output 接受绝对路径或相对路径的 .pdf 文件路径；相对路径基于当前工作目录解析；最终解析出的路径必须位于 OpenClaw 允许的媒体根目录内，或处于当前工作目录下。

载荷格式

发票载荷是一个扁平化的 JSON 对象，直接提交至 SmartBill API。参见 references/invoice-example.json 获取标准最小示例，以及 references/smartbill-api.md 查阅各字段详细说明。

CLI 支持以下两种输入格式：

• 裸发票对象：{ "companyVatCode": "...", "client": {...}, ... }
• 包裹格式：{ "invoice": { "companyVatCode": "...", "client": {...}, ... } }

CLI 会自动解包，并将内部的发票对象直接发送至 API。

操作规范

• 始终优先使用 --dry-run 检查标准化后的载荷，确认无误后再调用 API。
• 将正式发票签发（即 isDraft: false）视为高影响操作，必须经用户显式确认。
• 设置 client.saveToDb: false 和 products[].saveToDb: false，避免测试数据被持久化。
• 在运行日志中完整保留 SmartBill 的响应数据（包括 series、number、message）；其中 number 必须按返回值原样存储（如 "0123"），严禁去除前导零或转为整数类型。
• 遵守 SmartBill 的速率限制：每 10 秒最多 30 次调用。

参考资料

• 阅读 references/smartbill-api.md 以了解载荷字段定义、端点映射，以及认证与速率限制相关说明。
• 以 references/invoice-example.json 作为标准初始载荷模板使用。