166 lines
5.0 KiB
Markdown
166 lines
5.0 KiB
Markdown
# 意大利云开票命令行工具
|
||
|
||
`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)。 |