5.0 KiB
意大利云开票命令行工具
CLI 发票 电子发票 API PHP 意大利税务
Fatture in Cloud CLI
一个用于 Fatture in Cloud API 的命令行工具，具备完整的 API 覆盖、面向智能体的文档，以及针对电子发票（fattura elettronica）XML 文件的实用导入工作流。
版本 1.0.1 起的发布说明请参见 CHANGELOG.md。
安装
Composer
composer global require 16bitsrl/fattureincloud-cli
静态二进制文件
每个版本同时提供适用于 Linux、macOS 和 Windows 的静态构建包。
- 从 GitHub Release 资产中下载
- 或查看
builds/static/中的本地示例
下载后，在类 Unix 系统上赋予可执行权限：
chmod +x ./fic-linux-x86_64
./fic-linux-x86_64 --version
快速开始
# 身份验证
fic auth:login
# 设置默认公司
fic company:set
# 浏览生成的 API 命令
fic api:list
# 搜索助手
fic clients:search acme --company-id=12345
fic suppliers:search studio --company-id=12345
fic products:search consulting --company-id=12345
在 secure.fattureincloud.it/api 获取您的手动令牌。
XML 电子发票导入
官方 API 不直接接收原始 XML，因此 CLI 通过 JSON API 重建文档。
对于已开具发票的 XML 导入，重建的文档默认被视为电子发票。
# 预览单个 XML 文件
fic einvoice:import /absolute/path/to/fattura.xml --company-id=12345 --dry-run
# 预览签名的 XML.p7m 文件
fic einvoice:import /absolute/path/to/fattura.xml.p7m --company-id=12345 --dry-run
# 导入一个文件夹中的所有 XML 文件（方向从 XML 内容自动判断）
fic einvoice:import /absolute/path/to/xml-dir --company-id=12345 --yes
导入功能支持：创建前预览确认、模拟运行（dry run）、.xml 和 .xml.p7m 格式输入、客户/供应商匹配、嵌入附件携带、自动判断方向（已开具/已收到/自开发票），以及在回退到 ei_raw 之前对支持的电子发票字段进行结构化映射。如果 XML 中的双方均与所选公司不匹配，导入将被拒绝。
智能体技能
本仓库包含一个 agent skill，用于教导编码智能体如何使用本 CLI，涵盖筛选、排序、分页、常见问题边界情况、配额限制及 XML 导入。
安装技能
fic install-skill
技能源文件位于 skills/fattureincloud/。
实用示例
fic api:list-issued-documents --company-id=12345 --type=invoice --sort=-date --json
fic api:list-clients --company-id=12345 --q="vat_number = 'IT01234567890'" --json
fic api:send-e-invoice --company-id=12345 --document-id=99
API 覆盖范围
| 资源 | 命令 |
|---|---|
| 客户 | list、get、create、modify、delete、info |
| 供应商 | list、get、create、modify、delete |
| 产品 | list、get、create、modify、delete |
| 已开具文档 | list、get、create、modify、delete、totals、email、transform、join |
| 电子发票 | send、verify XML、get XML、rejection reason |
| 已收到文档 | list、get、create、modify、delete、totals、pending |
| 收据 | list、get、create、modify、delete、monthly totals |
| 税款 (F24) | list、get、create、modify、delete、attachments |
| 现金账簿 | list、get、create、modify、delete |
| 存档 | list、get、create、modify、delete、attachments |
| 设置 | 付款账户/方式、增值税类型、税务档案、模板 |
| 信息 | 城市、国家、货币、语言、类别等 |
| Webhook | list、create、get、modify、delete、verify |
| 用户 | info、companies |
| 公司 | info、plan usage |
智能体技能
请参见上方的专属章节。
测试
composer test
发布新版本
使用发布脚本：
./bin/release.sh X.Y.Z
该脚本将：
- 使用请求的版本构建
builds/fic - 验证
builds/fic与源码版本一致 - 提交
builds/fic - 创建标签
vX.Y.Z - 推送分支和标签
之后 GitHub Release 工作流将为 Linux、macOS 和 Windows 构建 PHAR 及静态二进制文件。
如果只想验证已提交的 PHAR 是否与源码版本仍保持一致：
./bin/check-phar-sync.sh
CI 也会在每次推送和 Pull Request 时执行相同的同步检查。
用户可通过 composer global require 16bitsrl/fattureincloud-cli 进行安装或更新。
更新 OpenAPI 规范
./bin/update-spec.sh # 从 master 获取最新版
./bin/update-spec.sh v2.1.8 # 指定标签版本
fic clear-cache # 清除已缓存的规范文件
致谢
- 基于 Laravel Zero 和 Spatie Laravel OpenAPI CLI 构建
- API 由 Fatture in Cloud 提供
- 由 16bit S.r.l. 的 Mattia Trapani 开发
许可证
MIT 许可证（MIT）。详情请参见 LICENSE.md。