# 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. 登録: ```json { "company_id": <テスト事業所ID>, "issue_date": "YYYY-MM-DD", "type": "expense", "ref_number": "-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 で確かめる。 - 外部へ書き込む検証スクリプトは「失敗しても再実行しない」。自動リトライする委譲ツールには再試行無効フラグを付ける。 ---