会計ソフト仕訳APIフルサイクルテストと勘定科目エクスポート/インポート機能

仕訳登録APIでAmazonビジネス明細45件を一括登録し、削除→対象外解除→未入力復帰までのライフサイクルを通した。更新APIと複合仕訳の作成方法も解明。後半では、Chrome拡張に勘定科目のエクスポート/インポート機能を載せて全381テストを通した。

仕訳登録API（journalize）のフルサイクルテスト

明細データから仕訳を起こすAPIエンドポイント。DevToolsでUIの「登録」ボタンが叩いているリクエストをキャプチャして形式を特定した。

Amazonビジネス明細45件を200ms間隔で連続POST。レート制限に引っかからず全件成功した。bulk_register系のAPIも探したが見つからず、1件ずつ journalizing_suggestions を叩く方式に落ち着いた。

登録した仕訳を削除すると、元の明細が「仕訳済み」から「対象外」ステータスに変わる。「未入力」には戻らない。

「対象外」ステータスの明細を「未入力」に戻すAPI。削除→ignore_cancelの2ステップで、明細を登録前の状態に完全復帰できることを確認した。

これで登録→削除→対象外解除→未入力復帰のフルサイクルが回る。一括登録のテストを何度でもやり直せる状態になった。

登録APIは見つかったが、更新APIはドキュメントに載っていなかった。UIから勘定科目を変更する操作をDevToolsで追いかけて、PATCH update_new エンドポイントを捕捉した。

借方を「仮払金」→「消耗品費」に変更するリクエストを再現。PATCHのボディにはbranches配列（借方・貸方の行）を含め、変更対象の行だけでなく全行を送る必要がある。一部の行だけ送ると残りが消えるので注意。

PATCH update_new のbranches配列を2行以上にすると、複合仕訳になる。

仮払金で一旦計上した経費を、消耗品費に振り替える複合仕訳を作成した。

branches配列に借方行と貸方行を並べてPATCHすると、複合仕訳として登録される。

貸方を1行目に合計額として集約した形式でもAPIは受け入れた。つまり借方を複数行に分けて貸方を1行にまとめる、またはその逆も可能。バリデーションは借方合計 = 貸方合計のみで、行数の制約はなかった。

DevToolsで管理画面のCSVエクスポート/インポート操作を追跡し、GET /items_csv と POST /items_csv の2つのエンドポイントを特定した。GETでCSVダウンロード、POSTでCSVアップロード。

エクスポートしたCSVをGoogle Sheetsで開いて再保存すると、空フィールドの表現が変わる。会計ソフトのCSVは "" (ダブルクォート2つ)、Google Sheetsは空文字。そのままdiffを取ると全行が差分になる。

trim + 空文字正規化を挟むことで、実質的な変更がない行を差分から除外した。

勘定科目のインポートでは追加・更新はCSV経由で対応できるが、削除はCSVではできない。DevToolsで補助科目の削除操作を追跡して DELETE /sub_items/{id} を見つけた。IDは sub_item-{数値ID} 形式。

事業者設定タブと勘定科目タブで、エクスポート/インポートのUIが重複していた。HTML生成ロジックを renderEntityExportImportList 関数に統合した。

タブごとにエンティティ定義の配列を渡すだけでUIが生成される形になった。

全381テスト合格。勘定科目エクスポート/インポートのテストを追加しても既存テストは壊れなかった。純粋関数にロジックを閉じ込めてあるので、API呼び出し部分をモックするだけでテストが書ける。

仕訳APIの調査は、公式ドキュメントに載っていないエンドポイントをDevToolsで一つずつ追いかける作業だった。bulk_registerを探して見つからず、journalizeの1件ずつ方式に切り替えたとき、45件を200ms間隔で流してレート制限に引っかからなかったのは助かった。

複合仕訳のbranches配列を組み立てるとき、最初は借方・貸方の行数制約があると思い込んでいた。実際にバランスさえ合えばAPIは受け入れるとわかり、振替仕訳のパターンが一気に広がった。

勘定科目のエクスポート/インポートは、diff正規化で半日持っていかれた。"" と空文字の差異に気づくまで「なぜ全行が差分になるのか」とログを睨み続けた。原因がわかった瞬間、trim一行で解決したのが拍子抜けだった。