by 运行时依赖
安装命令
点击复制技能文档
SmartBill Invoicing 使用 scripts/smartbill_cli.py 脚本进行确定性的 SmartBill API 调用，而不是使用 ad-hoc HTTP 代码段。
工作流程 从用户收集发票输入。 在发送之前在本地验证有效载荷：python scripts/smartbill_cli.py validate-payload --input references/invoice-example.json --show-payload 执行 dry-run 以检查规范化的有效载荷而不调用 API：python scripts/smartbill_cli.py create-invoice --input --dry-run 在获得用户明确确认后发出最终发票：python scripts/smartbill_cli.py create-invoice --input --allow-final 一旦知道系列和编号，就可以检索 PDF：python scripts/smartbill_cli.py download-invoice-pdf --series-name --number --output 使用 SmartBill 返回的确切编号字符串（例如“0123”，零填充）。不要删除前导零或将其转换为整数。--output 接受绝对或相对路径，并且必须以 .pdf 结尾。
所需环境 在调用 SmartBill 之前设置以下环境变量： MAVERICK_SMARTBILL_USERNAME - SmartBill 登录电子邮件 MAVERICK_SMARTBILL_TOKEN - SmartBill API 令牌 MAVERICK_SMARTBILL_COMPANY_VAT_CODE - 默认 CIF（可选，但推荐） 可选覆盖： MAVERICK_SMARTBILL_API_BASE（默认：https://ws.smartbill.ro/SBORO/api） MAVERICK_SMARTBILL_TIMEOUT_SECONDS（默认：30） MAVERICK_SMARTBILL_RETRIES（默认：2） MAVERICK_SMARTBILL_DEBUG（默认：未设置）- 设置为 1、true 或 yes 以启用请求/响应调试日志记录到 stderr
命令指南 validate-payload 解析和规范化有效载荷形状（接受裸发票对象或 { "invoice": {...} } 包装器）。在 API 调用之前验证最小所需结构。 create-invoice 通过 POST /invoice 创建发票。需要 --allow-final 来发出最终发票。支持 --dry-run（打印规范化的有效载荷，无 API 调用）和 --force-draft。传递 --debug（或设置 MAVERICK_SMARTBILL_DEBUG=1）以将完整的请求/响应有效载荷打印到 stderr。 get-series 通过 GET /series 查询可用的 SmartBill 系列。 download-invoice-pdf 通过 GET /invoice/pdf 使用 CIF + 系列 + 编号获取 PDF。--output 接受绝对或相对 .pdf 路径。相对路径是相对于当前工作目录解析的。解析后的路径必须位于 OpenClaw 允许的媒体根目录或当前工作目录内。
有效载荷格式 发票有效载荷是直接发送到 SmartBill API 的平面 JSON 对象。请参阅 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 响应数据（系列、编号、消息）。 以零填充的形式存储编号（例如“0123”），并且永远不要删除前导零或将其转换为整数。 尊重 SmartBill 的速率限制：每 10 秒最多 30 个调用。
参考 阅读 references/smartbill-api.md 以获取有效载荷字段参考、端点映射和身份验证/速率限制说明。 使用 references/invoice-example.json 作为规范的起始有效载荷模板。