freee 一括記帳・突合スキル

freee会計のAPIで、銀行明細からの一括記帳と検算を行う。画面作業では現実的でない件数（数百〜数千件）を扱うときに使う。

前提

freee_token_<key>.json にトークンがある（freee_cashflow_discord.py の token_for(key, env) / load_env() で取得）
勘定科目の判定ルールは librex_journal_rules.py の RULES（キーワード・科目・税区分・金額レンジ・入出金の向き）
事業内容が同じ会社なら、このルールはそのまま流用できる

必ず守ること

1. APIで作った取引は明細を消込まない

freee APIで取引を作っても口座明細は「未処理」のまま残る。帳簿には仕訳が入っているので二重ではないが、画面の「自動で経理」から一括登録すると全部が二重計上になる。

→ 記帳が終わったら、その旨をユーザーに明示的に伝える。申告が終わるまで画面の登録ボタンを押さないよう念を押す。

2. 巻き戻せる形で実行する

登録した取引IDは必ずログに1行ずつ書き出し、--delete-log で一括削除できるようにする。分類方針は途中で変わるものと考えて設計する。

created<TAB>取引ID<TAB>日付<TAB>科目<TAB>金額

3. 登録前に必ず dry-run で分類結果を見せる

科目別の件数・金額を集計して提示し、ユーザーの承認を得てから登録する。未分類が残っていれば先に潰す。

4. ログの同時実行に注意

複数プロセスを並行させるとログの行が欠ける。付け替えや訂正はログではなく /deals をAPIから直接引くこと。

手順

Step 1: 未処理明細の特定

/wallet_txns（明細）と /deals（取引）を全件取得し、(日付, 種別, 金額) で突合して未処理を洗い出す。どちらも limit=100 なので offset でページングする。

Step 2: 分類

RULES を当てて科目を決める。会社固有の判定は RULES より先に置く。よくあるもの:

関係会社との資金移動 → 短期借入金（別法人なら口座振替ではない）
代表者からの入金 → 短期借入金（役員借入）／代表者への出金 → 役員報酬
同一法人の口座間移動 → 振替（取引として作らない）

Step 3: dry-run → 登録

POST /deals に details（科目・金額）と payments（決済口座・日付）を渡す。

Step 4: 突合（これが本体）

月末の預金残高を、帳簿と明細の両方で出して一致を確認する。

明細の残高    wallet_txns の balance（銀行が持っている実残高）
帳簿の残高    /reports/trial_bs の口座科目
同期残高      /walletables の walletable_balance

3つが一致すれば記帳は完了。ズレたら Step 1 に戻る。差額の符号と金額から、入金漏れか出金漏れか日付ズレかが判別できる。

会計期間が開いていない期の試算表

freeeは「当年度＋翌年度」の2期しか開かない。3期目の /reports/trial_pl は 400 を返す。

→ /journals（非同期エクスポート）で仕訳帳をCSVで全件取得し、勘定科目マスタの account_category と突き合わせて自前で集計する。

リクエスト  GET /journals?download_type=csv&start_date=&end_date=  → 202 で id
ポーリング  GET /journals/reports/{id}/status  → status が uploaded になるまで
ダウンロード GET /journals/reports/{id}/download  → CP932

必ず、数字が確定している期で検算してから使う。 レポートAPIの値と自前集計が1円まで一致することを確認できれば、出せない期の数字も信頼できる。

CSVの列（カンマ区切り・ヘッダなし）:

[2]決算整理フラグ [3]日付
[4]借方科目 [7]借方税区分 [8]借方金額
[10]貸方科目 [13]貸方税区分 [14]貸方金額
[16]摘要

月次試算表

/reports/trial_pl の start_month は効かないことがある。end_month を変えて期首からの累計を取り、前月との差分で当月発生額を出す。BSは累計＝月末残高なのでそのまま使える。

決済代行の純額計上を総額に直す

Stripe・Square等からの入金を手数料控除後の純額で売上計上している場合、総額主義に反する。損益は変わらないが、売上規模と消費税の課税売上高が変わる。

明細が取れない場合は入金額を手数料率で割り戻す。検証は、割り戻した金額が決済単価の組み合わせとして成立する丸い数字になるかを見る。複数件で連続して丸くなれば率は正しい。

freeeと連携して経理業務を楽にするskills

インストール方法

ソースファイルを確認