クラウド請求書 API v3 のサポートを追加

CONTRIBUTING.md

@@ -17,6 +17,41 @@
 - All external API calls must be mockable via `httptest`
 - Run `make lint` before submitting
 
+### Command patterns (legacy vs. new)
+
+There are intentionally **two** Cobra command patterns in this repo:
+
+- **Legacy (accounting commands):** package-global flag variables (`format`,
+  `fields`, `debug`), `Run` handlers that call `os.Exit` via `exitError`,
+  and `outputResult` writing directly to `os.Stdout`. Existing `cmd/journals.go`
+  and friends follow this pattern.
+- **New (invoice commands):** dependency injection via `cmdDeps`, pure
+  `runFoo(deps, opts)` runner functions returning `error`, options structs
+  built from a `parseFooOptions(cmd, args)` helper, and writes through
+  injected `io.Writer` values (`outputResultTo`). Cobra `RunE` is a thin
+  wrapper that calls the pure runner and routes errors through
+  `exitInvoiceAPIError` / `exitError`.
+
+New commands should follow the new pattern. Existing commands stay as-is
+unless a separate refactor PR converts them.
+
+### Invoice model imports
+
+When importing the invoice model package, alias it as `invoicemodel` so
+the call site reads consistently across files:
+
+```go
+import invoicemodel "github.com/beatinaniwa/mf-cli/internal/model/invoice"
+```
+
+### Test fixtures
+
+Invoice testdata under `internal/api/testdata/` is pinned to the
+committed `iv_openapi.yaml`. When you regenerate fixtures, update
+`internal/api/testdata/README.md` so the provenance manifest stays in
+sync. Fixture filenames using the `*_minimal.json` suffix indicate
+schema-required minimums rather than full spec examples.
+
 ## Testing Policy
 
 - Run: `make test` (includes `-race` flag)

README.md

@@ -1,18 +1,19 @@
-# mf - MoneyForward会計 CLI
+# mf - MoneyForward 会計 / 請求書 CLI
 
 [![Go](https://img.shields.io/github/go-mod/go-version/beatinaniwa/mf-cli)](https://go.dev/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 [![CI](https://github.com/beatinaniwa/mf-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/beatinaniwa/mf-cli/actions/workflows/ci.yml)
 [![Release](https://img.shields.io/github/v/release/beatinaniwa/mf-cli)](https://github.com/beatinaniwa/mf-cli/releases)
 
-[マネーフォワード クラウド会計](https://biz.moneyforward.com/accounting)のAPIを操作するコマンドラインツールです。
+[マネーフォワード クラウド会計](https://biz.moneyforward.com/accounting) と [マネーフォワード クラウド請求書](https://biz.moneyforward.com/invoice) のAPIを操作するコマンドラインツールです。
 
 > **Note:** リポジトリ名は `mf-cli` ですが、インストールされるバイナリ名は `mf` です。
 
 ## 特徴
 
 - OAuth 2.0 + PKCE による認証
-- 仕訳帳・勘定科目・取引先・部門・税区分などのCRUD操作
+- 仕訳帳・勘定科目・取引先・部門・税区分などのCRUD操作（クラウド会計）
+- 請求書の作成・更新・削除と取引先 / 部署 / 品目の参照（クラウド請求書）
 - 試算表・推移表などの財務レポート取得
 - JSON / テーブル形式での出力切替
 - `--dry-run` による安全な事前確認
@@ -69,7 +70,7 @@ export MF_CLIENT_SECRET=your_client_secret  # 公開クライアントの場合
 # ブラウザで認証（デフォルト）
 mf auth login
 
-# 書き込み権限も含める場合
+# 書き込み権限も含める場合（クラウド請求書APIを使う場合は必須）
 mf auth login --scopes all
 
 # ブラウザを使わずに認証（SSHセッション等）
@@ -97,9 +98,24 @@ mf journals create --json '{"..."}' --dry-run
 # 試算表（P/L）を取得
 mf reports trial-balance-pl --fiscal-year 2024
 
-# APIスキーマを確認
+# APIスキーマを確認（会計）
 mf describe --list          # 利用可能なリソース一覧
 mf describe journals        # journals の詳細
+
+# 請求書APIスキーマを確認
+mf describe --api invoice --list
+mf describe --api invoice invoices
+
+# 請求書ドラフトを作成（dry-run で事前確認）
+mf invoices create --dry-run --json '{"department_id":"...","billing_date":"2026-05-08","title":"請求書","items":[{"name":"作業費","price":10000,"quantity":1,"excise":"ten_percent"}]}'
+
+# 請求書一覧
+mf invoices list --per-page 5
+
+# 取引先・部署・品目の参照
+mf invoice-partners list
+mf invoice-departments list --partner-id <partner_id>
+mf invoice-items list
 ```
 
 ## コマンド一覧
@@ -129,7 +145,15 @@ mf describe journals        # journals の詳細
 | `reports trial-balance-pl` | 試算表（P/L） | o | | |
 | `reports transition-bs` | 推移表（B/S） | | | |
 | `reports transition-pl` | 推移表（P/L） | | | |
-| `describe [resource]` | APIスキーマ表示 | o | | |
+| `describe [resource]` | APIスキーマ表示（`--api accounting\|invoice` で切替） | o | | |
+| `invoices list` | 請求書一覧 | o | | |
+| `invoices get <ID>` | 請求書詳細 | | | |
+| `invoices create` | 請求書ドラフト作成（POST `/invoice_template_billings`） | | o | o |
+| `invoices update <ID>` | 請求書更新 | | o | o |
+| `invoices delete <ID>` | 請求書削除 | | o | |
+| `invoice-partners list` / `get` | 請求書取引先 | o | | |
+| `invoice-departments list` / `get` | 取引先の部署（`--partner-id` 必須） | o | | |
+| `invoice-items list` / `get` | 請求書品目 | o | | |
 | `version` | バージョン表示 | | | |
 
 ## 入出力
@@ -184,6 +208,7 @@ mf journals create --json '{"..."}' --dry-run
 | `MF_AUTH_PORT` | ローカルコールバックポート | `8089` |
 | `MF_CONFIG_DIR` | 設定ディレクトリのパス | OS依存（下記参照） |
 | `MF_SCOPES` | スペース区切りのスコープリスト | `--scopes` フラグより優先 |
+| `MF_INVOICE_BASE_URL` | クラウド請求書 API のオリジン（`/api/v3` を含めない） | `https://invoice.moneyforward.com` |
 
 環境変数は設定ファイルの値を上書きします。
 
@@ -205,10 +230,13 @@ mf journals create --json '{"..."}' --dry-run
   "client_id": "your_client_id",
   "client_secret": "your_client_secret",
   "base_url": "https://api-accounting.moneyforward.com",
+  "invoice_base_url": "https://invoice.moneyforward.com",
   "auth_port": 8089
 }
 ```
 
+> `invoice_base_url` は origin のみを指定してください（末尾の `/api/v3` は不要）。`/api/v3` 付きで設定された場合や末尾スラッシュは自動でトリムされ、それ以外の不正値は invoice 系コマンド実行時にエラーになります。
+
 #### token.json
 
 認証トークンは同ディレクトリ内の `token.json` に自動保存されます。
@@ -222,7 +250,8 @@ mf-cli はAIエージェント（Claude Code、Codex等）からの利用に適
 - `--fields` でJSON出力から必要なフィールドのみ抽出可能
 - `--dry-run` で安全にリクエスト内容を事前確認
 - `--json -` で標準入力からJSONを渡せる
-- エラーは構造化JSONとしてstderrに出力
+- エラーは構造化JSONとしてstderrに出力（cobra/pflagの未定義フラグや型不正のみ平文で stderr に出力されます）
+- 請求書APIを使うには `mf auth login --scopes all` で再認可が必要です（`MF_SCOPES` を設定中の場合は `unset MF_SCOPES` してから実行してください）
 
 ## 開発