什么是 SmartBill 发票助手？

SmartBill 发票技能为与 SmartBill.ro API 交互提供了强大的接口，允许用户和 AI 代理精确管理计费文档。通过利用基于 Python 的本地 CLI，这一 Openclaw Skills 扩展可确保在执行任何外部 API 调用之前对发票数据进行验证和规范化。这可以防止常见错误，并为在专业会计工作流中生成草稿和正式发票提供安全环境。

下载入口:https://github.com/openclaw/skills/tree/main/skills/tokyo-s/smartbill

安装与下载

1. ClawHub CLI

从源直接安装技能的最快方式。

2. 手动安装

将技能文件夹复制到以下位置之一

优先级：工作区 > 本地 > 内置

3. 提示词安装

将此提示词复制到 OpenClaw 即可自动安装。

SmartBill 发票助手 应用场景

• 根据项目管理或电子商务数据自动创建合法发票。
• 在本地验证复杂的发票负载，以确保在提交前符合架构规范。
• 批量下载发票 PDF 以便存档或自动向客户发送电子邮件。
• 以编程方式管理多个单据系列并查询可用的编号序列。

1. 从用户或数据源收集必要的发票详细信息，如客户信息和行项目。
2. 使用 CLI 运行本地验证步骤，以确保负载结构符合 SmartBill 要求。
3. 执行模拟运行以检查规范化后的负载，而不触及实时 API 端点。
4. 执行发票创建命令，并在生成正式（非草稿）单据前获得用户的明确确认。
5. 获取生成的系列号和发票号码，以编程方式下载并保存生成的 PDF 文档。

SmartBill 发票助手 配置指南

要在 Openclaw Skills 中开始使用此技能，请使用您的 SmartBill 凭据配置环境变量：

export SMARTBILL_USERNAME="your_email@example.com"
export SMARTBILL_TOKEN="your_api_token"
export SMARTBILL_COMPANY_VAT_CODE="RO12345678"

确保脚本目录中可以访问 smartbill_cli.py 脚本。

SmartBill 发票助手 数据架构与分类体系

该技能使用灵活的 JSON 结构处理数据。关键组件包括：

CLI 自动处理裸发票对象和封装的发票对象，以实现最大兼容性。

name: smartbill-invoicing description: Issue SmartBill invoices through the SmartBill.ro API with local automation. Use for SmartBill tasks such as validating invoice payloads, creating invoices, listing available document series, and downloading invoice PDFs by series and number.

SmartBill Invoicing

Use scripts/smartbill_cli.py for deterministic SmartBill API calls instead of ad-hoc HTTP snippets.

Workflow

1. Collect invoice input from the user.
2. Validate payload locally before sending:
   • python scripts/smartbill_cli.py validate-payload --input references/invoice-example.json --show-payload
3. Dry-run to inspect the normalized payload without calling the API:
   • python scripts/smartbill_cli.py create-invoice --input --dry-run
4. Issue final invoice after explicit user confirmation:
   • python scripts/smartbill_cli.py create-invoice --input --allow-final
5. Retrieve PDF once series and number are known:
   • python scripts/smartbill_cli.py download-invoice-pdf --series-name --number --output

Required Environment

Set these before calling SmartBill:

• SMARTBILL_USERNAME - SmartBill login email
• SMARTBILL_TOKEN - SmartBill API token
• SMARTBILL_COMPANY_VAT_CODE - default CIF (optional but recommended)

Optional overrides:

• SMARTBILL_API_BASE (default: https://ws.smartbill.ro/SBORO/api)
• SMARTBILL_TIMEOUT_SECONDS (default: 30)
• SMARTBILL_RETRIES (default: 2)

Command Guide

• validate-payload
  • Parse and normalize payload shape (bare invoice object or { "invoice": {...} } wrapper both accepted).
  • Validate minimum required structure before API calls.
• create-invoice
  • Create invoice via POST /invoice.
  • Requires --allow-final to issue a final invoice.
  • Supports --dry-run (prints normalized payload, no API call) and --force-draft.
• get-series
  • Query available SmartBill series via GET /series.
• download-invoice-pdf
  • Fetch PDF via GET /invoice/pdf using CIF + series + number.

Payload Format

The invoice payload is a flat JSON object sent directly to the SmartBill API. See references/invoice-example.json for the canonical minimal example and references/smartbill-api.md for field documentation.

Both formats are accepted as input to the CLI:

• Bare invoice object: { "companyVatCode": "...", "client": {...}, ... }
• Wrapped: { "invoice": { "companyVatCode": "...", "client": {...}, ... } }

The CLI unwraps automatically and sends the invoice object directly to the API.

Operational Rules

• Always use --dry-run first to confirm the normalized payload before hitting the API.
• Treat final invoice issuance (isDraft: false) as a high-impact action requiring explicit user confirmation.
• Set client.saveToDb: false and products[].saveToDb: false to avoid persisting test data.
• Preserve SmartBill response data (series, number, message) in run logs.
• Respect SmartBill rate limits: max 30 calls per 10 seconds.

References

• Read references/smartbill-api.md for payload field reference, endpoint mapping, and auth/rate-limit notes.
• Use references/invoice-example.json as the canonical starting payload template.