核心功能概述
SmartBill Invoicing 是一款面向罗马尼亚市场的本地化发票自动化工具，基于 SmartBill.ro 官方 API 构建，通过 Python CLI 脚本实现发票生命周期的全流程管理。
核心用法
该技能采用四层安全 workflow：
1. 本地验证 (validate-payload) — 在发送前校验发票数据结构
2. 干运行预览 (create-invoice --dry-run) — 查看标准化 payload 而不调用 API
3. 确认后签发 (--allow-final) — 明确要求用户确认后才生成最终发票
4. PDF 归档 (download-invoice-pdf) — 按系列号检索正式发票文档
关键命令覆盖：
get-series: 查询可用发票系列create-invoice: 创建发票（支持草稿/最终模式）validate-payload: 前置结构校验
显著优点
- 确定性自动化: 用统一 CLI 替代临时 HTTP 片段，消除手动构造请求的错误风险
- 多层安全设计: 强制 dry-run → 确认 → 最终签发的流程，防止误操作
- 灵活输入格式: 自动解包裸对象或
{invoice: {...}}包装格式 - 完善的调试支持:
SMARTBILL_DEBUG环境变量开启完整请求/响应日志 - 本地验证优先: 在调用 API 前捕获格式错误，减少无效请求
潜在缺点与局限性
- 地域限制: 仅适用于罗马尼亚税务系统（SmartBill.ro），无其他国家/地区支持
- 环境依赖: 需预配置
SMARTBILL_USERNAME、SMARTBILL_TOKEN、SMARTBILL_COMPANY_VAT_CODE三个必需环境变量 - Python 依赖: 依赖本地
python3环境，无内置运行时 - 速率限制: 硬编码 30 请求/10秒，高频场景需自行节流
- 无状态设计: 不提供发票状态持久化，需外部管理 series/number 与业务订单的映射
适合人群
- 在罗马尼亚运营的中小企业财务/运营团队
- 需要将发票系统与本地 ERP/CRM 集成的开发者
- 寻求替代手动 SmartBill Web 界面操作的用户
常规风险
- API 令牌泄露:
SMARTBILL_TOKEN具备完整发票操作权限，需按生产密钥保管 - 发票不可逆性: 最终发票 (
isDraft: false) 在罗马尼亚税法下具有法律效力，误发需走冲红流程 - 测试数据污染: 忘记设置
saveToDb: false可能将测试数据持久化到生产数据库 - CIF 配置错误:
SMARTBILL_COMPANY_VAT_CODE不匹配会导致发票归属错误 - 网络超时: 默认 30 秒超时在高峰期可能不足，建议监控并调整
SMARTBILL_TIMEOUT_SECONDS