# 意大利云开票命令行工具

`CLI` `发票` `电子发票` `API` `PHP` `意大利税务`

# Fatture in Cloud CLI

一个用于 [Fatture in Cloud](https://www.fattureincloud.it) API 的命令行工具，具备完整的 API 覆盖、面向智能体的文档，以及针对电子发票（fattura elettronica）XML 文件的实用导入工作流。

版本 `1.0.1` 起的发布说明请参见 `CHANGELOG.md`。

## 安装

### Composer

```bash
composer global require 16bitsrl/fattureincloud-cli
```

### 静态二进制文件

每个版本同时提供适用于 Linux、macOS 和 Windows 的静态构建包。

- 从 GitHub Release 资产中下载
- 或查看 `builds/static/` 中的本地示例

下载后，在类 Unix 系统上赋予可执行权限：

```bash
chmod +x ./fic-linux-x86_64
./fic-linux-x86_64 --version
```

## 快速开始

```bash
# 身份验证
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](https://secure.fattureincloud.it/api) 获取您的手动令牌。

## XML 电子发票导入

官方 API 不直接接收原始 XML，因此 CLI 通过 JSON API 重建文档。

对于已开具发票的 XML 导入，重建的文档默认被视为电子发票。

```bash
# 预览单个 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](https://skills.sh)，用于教导编码智能体如何使用本 CLI，涵盖筛选、排序、分页、常见问题边界情况、配额限制及 XML 导入。

### 安装技能

```bash
fic install-skill
```

技能源文件位于 `skills/fattureincloud/`。

## 实用示例

```bash
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 |

## 智能体技能

请参见上方的专属章节。

## 测试

```bash
composer test
```

## 发布新版本

使用发布脚本：

```bash
./bin/release.sh X.Y.Z
```

该脚本将：

- 使用请求的版本构建 `builds/fic`
- 验证 `builds/fic` 与源码版本一致
- 提交 `builds/fic`
- 创建标签 `vX.Y.Z`
- 推送分支和标签

之后 GitHub Release 工作流将为 Linux、macOS 和 Windows 构建 PHAR 及静态二进制文件。

如果只想验证已提交的 PHAR 是否与源码版本仍保持一致：

```bash
./bin/check-phar-sync.sh
```

CI 也会在每次推送和 Pull Request 时执行相同的同步检查。

用户可通过 `composer global require 16bitsrl/fattureincloud-cli` 进行安装或更新。

## 更新 OpenAPI 规范

```bash
./bin/update-spec.sh              # 从 master 获取最新版
./bin/update-spec.sh v2.1.8       # 指定标签版本
fic clear-cache                   # 清除已缓存的规范文件
```

## 致谢

- 基于 [Laravel Zero](https://laravel-zero.com) 和 [Spatie Laravel OpenAPI CLI](https://spatie.be/docs/laravel-openapi-cli) 构建
- API 由 [Fatture in Cloud](https://developers.fattureincloud.it) 提供
- 由 [16bit S.r.l.](https://16bit.it) 的 [Mattia Trapani](https://github.com/zupolgec) 开发

## 许可证

MIT 许可证（MIT）。详情请参见 [LICENSE.md](LICENSE.md)。