freee会計API: 仕訳CSVを API で取引登録できるか検証する（CSV取込APIは無い／account_items の offset 無限ループ／仕訳帳の代わりに試算表で貸方確認）

結論

• freee会計の公開API（v2020_06_15 OpenAPI、約100パス）には CSV ファイルを取り込むエンドポイントは無い。import csv batch を含むパスは0件。
• 代わりに CSV の各行を POST /api/1/deals で1件ずつ送れば、画面の「取引のインポート」と同じ登録になる。
• 未決済の支出（貸方=未払金）は type: "expense" で payments を付けないだけでよい。

手順

1. スキーマを取得して確認: https://raw.githubusercontent.com/freee/freee-api-schema/master/v2020_06_15/open-api-3/api-schema.json の paths を grep。
2. 本番事業所で名前→ID を解決（GET のみ）: /api/1/account_items /api/1/partners /api/1/items /api/1/tags /api/1/sections。CSV の全行が解決できるか先に数える。
3. 税区分コードは /api/1/taxes/companies/{id} が権限で 403 になることがある → 固定表で持つ（例: 136=課対仕入10% / 189=課対仕入（控80）10% / 190=課対仕入（控50）10% / 163=課対仕入8%（軽） / 2=対象外。自分の事業所で実測して確かめる）。
4. テスト事業所だけに書き込む。書き込み関数の先頭で company_id != <テスト事業所ID> なら例外にする。
5. 登録:

{ "company_id": <テスト事業所ID>, "issue_date": "YYYY-MM-DD", "type": "expense",
  "ref_number": "<CSV名>-TEST-<行番号>",
  "details": [{ "account_item_id": 0, "tax_code": 136, "amount": 税込金額,
                "description": "店名", "item_id": 0, "tag_ids": [0], "section_id": 0 }] }

テスト事業所に無い品目・タグ・取引先は付けずに登録する（新規作成しない）。 6. GET /api/1/deals/{id} で issue_date・amount・details[0] の account_item_id / tax_code / amount / vat / description を CSV と照合。 7. 貸方が未払金かは 試算表 GET /api/1/reports/trial_bs?company_id=..&start_date=<期首>&end_date=.. の「未払金」closing_balance を登録前後で比べ、増加額＝登録合計なら確定。 8. DELETE /api/1/deals/{id}?company_id=..（204）→ GET が 404 を確認。ref_number で残骸を一覧検索して0件を確かめる。

落とし穴

• 🔴 /api/1/account_items は offset を無視して毎回同じ先頭100件を返す。len(batch) < 100 で止めるページングだと無限ループし、最後は offset が数十万になって 504。→ offset を付けずに1回で取る／取得IDが既出なら止める。
• 🔴 仕訳帳 /api/1/journals は非同期で作成に10分以上かかることがある。検証スクリプトや委譲先のタイムアウト（例: 30分）を食い潰す。貸方確認は手順7の試算表で足りる。
• 控80/控50 の行は freee の vat が 控除できる分だけ（例: 6,000円・控80 → 436円）になる。請求書の消費税額（545円）と一致しないのは正常。
• 登録中にプロセスが打ち切られると finally の削除が走らない。片付けは ref_number 検索で別途確認する。
• freee API は定期メンテナンスで 503 を返す（status ページに予定が出る）。503 本文がメンテナンス HTML なら再試行は明けてから。

二重登録防止

• ref_number に「CSV名-行番号」を入れ、登録前に同じ ref_number の取引が無いか GET で確かめる。
• 外部へ書き込む検証スクリプトは「失敗しても再実行しない」。自動リトライする委譲ツールには再試行無効フラグを付ける。