M
masaki.work

freee APIは明細を「処理済み」にできない — 二重計上から学んだ「一時ルール+画面1クリック」設計

freee accounting api ai workflow

★この記事の全文をコピーして、AIに「この通りに設定をガイドして」と渡すと便利です

📊この記事の図解版があります。内容を視覚的にまとめたページで、全体像をサッと把握できます

図解を見る

freee APIは明細を「処理済み」にできない — 二重計上から学んだ「一時ルール+画面1クリック」設計

想定読者: freeeで経理を回している小規模事業者・一人法人の方、AIやAPIで経理作業を楽にしたい方 最終更新: 2026年9月13日 読了時間: 約12分

はじめに

帳簿の数字は合っているのに、freeeの画面を開くと「未処理」の明細がずらりと並んでいる — 私たちは9月2日、この状態を自分の手で作ってしまいました。機械（AIプログラム）に仕訳を106件まとめて作らせたところ、帳簿上の記録はきれいにできたのに、元になった銀行・カードの明細103件が「処理済み」に変わらないまま残り、それを手作業で片付けようとした結果、売上5件を二重に計上してしまったのです。

原因を一次情報まで遡って調べると、「freeeのAPI（外部のプログラムからfreeeを操作する仕組み）には、明細を処理済みにする専用の経路が存在しない」という、当社固有ではないfreee API全体の設計上の欠落に行き着きました。

この記事では、(1) freeeの「明細」と「仕訳」がなぜ別物として扱われているか、(2) 実際に何が起きたか、(3) 唯一残された正規の経路を使って「一時的なルール+人による画面の1クリック」という方式にたどり着いた設計、の3点を解説します。

技術寄りの内容も含みますが、freeeで経理を回している方なら誰でも「明細と仕訳の違い」を知っておくと事故を避けやすくなるはずです。

freeeの「明細」と「仕訳」は別物

freeeを使っていると「明細」と「仕訳」という2つの言葉が出てきますが、この2つはまったく別のデータです。たとえるなら、明細は銀行やカード会社から届く郵便物（利用のお知らせ）そのもの、仕訳はその郵便物を見ながら帳簿に書き写した記録です。

郵便物を書き写しても、郵便物自体に「もう処理しました」という印が付くわけではありません。freeeの中でもこれと同じ関係があり、明細をもとに仕訳（正式には「取引」）を作っても、明細側が自動的に「処理済み」になるとは限らないのです。

この2つの間にどんな橋が架かっているかを、外部プログラムからできること・できないことで整理すると次のようになります。

対象外部プログラムからできることできないこと
明細読み取る書き換える・削除する・「処理済み」を直接押す
仕訳（取引）作る・直す・消す明細と直接紐づける（そのための欄が無い）
自動登録ルール作る・消す既にある明細に後から当てる（当たるのは新しく届いた明細だけ）
画面の「一括適用」ボタン（外部プログラムからは押せない）押す。人が画面で押すしかない

「明細は外部プログラムから書き換えも削除もできない」という点は、freee公式の仕様定義ファイル（freeeが自社のAPIの仕様を機械可読な形で公開しているもの）で裏取りが取れている事実です。仕訳を作る側の項目を見ても、明細の番号を渡す欄自体が用意されていません。この制約を知らずに「仕訳さえ作れば明細は自動でついてくる」と考えると、私たちが踏んだのと同じ壁にぶつかります。

9月2日、何が起きたか

9月2日、私たちは月次の経理作業を自動化する仕組みの中で、機械に仕訳106件を直接作らせました。帳簿の見た目は整い、金額も合っているように見えました。ところが、元になった明細のうち103件は仕訳と紐づく欄が存在しないため、いつまでも「未処理」のまま残ったのです。仕訳という帳簿側の記録だけを見ていれば「作業は完了した」ように見えてしまう、という点がこの失敗の怖さでした。

未処理の明細が大量に残っている状態は見た目が悪いため、その場では手作業で「無視」（この明細はもう扱わない、という印）を付けて片付けようとしました。しかし「無視」は画面上の操作でしか元に戻せない一方通行の操作でした。そして後から確認すると、売上5件が帳簿に二重に計上されていました。同じ入金が帳簿に二度載ってしまえば、当然ながら月次の数字は実態より大きくずれます。

金額や取引先などの詳細はここでは伏せますが、要点は「仕訳を直接作る経路そのものは正常に動いた」にもかかわらず、「明細を処理済みにする」という一手間が抜け落ちていたために、未処理明細の山と二重計上という帳簿の誤りにつながった、という点です。仕訳を作る処理と、明細を処理済みにする処理が、freeeの中では別々の仕組みだと知らなかったことが根本の原因でした。

この失敗は「無視を安易に使ってはいけない」ことも同時に教えてくれました。

唯一の正規経路: 自動登録ルール+画面の一括適用

この事故のあと、freeeで明細を処理済みにできる経路を調べ直しました。行き着いたのが「自動登録ルール」という仕組みです。これは「摘要（取引の説明文）や金額がこの条件に合う明細が来たら、自動でこの科目・税区分で仕訳を作る」というルールをあらかじめ登録しておく機能です。

ここで、公式の仕様定義と社内での実測の両方から、重要な制約が分かりました。自動登録ルールが自動的に働くのは「新しい明細が届いた瞬間」だけで、すでにfreeeに届いている明細には後から遡って適用されません。すでに届いている明細を処理済みにするには、人が画面を開いて「自動で経理」から「最新の自動登録ルールを適用」というボタンを押す必要があります。

しかもこのボタンは範囲を選ぶことができず、「有効なルール全部×未処理の明細全部（全期間）」に一括で効きます。狙った明細だけを狙って処理する、という細かい制御はできません。

この制約は当社固有の問題ではありません。freee公式のGitHubリポジトリに、口座明細を外部プログラム経由で処理済みにする専用の窓口が無いことについて、2件の報告・要望が上がっています。

  • freee/freee-mcp Issue #313: 仕訳を登録しても対応する明細が処理済みにならない、という当社とまったく同じ症状の報告。2026年3月に「対応しない（not planned）」として公式にクローズされています
  • freee/freee-api-schema Issue #541: 「取引作成時の自動消込」「明細を処理済みにする専用API」「取引作成時に明細の番号を指定できるようにする」の3案を求める機能要望。担当が付かないまま開いています

つまりこの制約はAPI全体の設計上の欠落であり、当社の使い方が悪いわけではありません。

なお2026年には、この自動登録ルール自体を作成・変更・削除できるAPIが新たに公開され、ルールを外部プログラムから直接扱える点は着実に前進しています。私たちの方式もこのAPIの上に成り立っています。ルールに関する更新はその後も続いているので、「既存の明細にルールを適用する」経路がいつか用意される可能性を含めて、定点観測する価値があります。

設計: 「一時ルール+1クリック」の4段

唯一の正規経路が「ルールを作る→画面のボタンを押す」である以上、私たちが取れる選択肢は、この経路をできる限り安全に、かつ機械で組み立てられる形に落とし込むことでした。たどり着いたのが次の4段の設計です。

段1                段2                     段3                  段4
機械がその場限り  → 機械が「押すと何件・  → 人が画面のボタンを → 機械が読み取りで
のルールを作る      いくら」を自前計算      1回押す(本番に       照合し、一時ルール
(あとで消せる)      して提示               反映するのはここ     を消す(明細は
                                            だけ)                消さない)

段1では、機械がその明細1件専用の、あとで消せる「一時的な自動登録ルール」を作ります。ボタンを押すと有効なルール全部が全期間の未処理明細に一括で効いてしまうため、狙った明細以外を巻き込まないよう、条件を絞り込んだ使い捨てのルールをその場で作る、という発想です。

段2では、一括適用ボタンを押したときに何件・いくらの仕訳が生まれるかを、freeeの画面表示に頼らず機械が自分で計算して人に提示します。段3が唯一の本番反映ポイントで、人が画面のボタンを実際に1回押します。freeeはこの1回のクリックで、仕訳の作成と明細の処理済み化を同時に行います。

段4では、機械が件数・金額・科目・明細の状態を読み取って提示した内容と一致しているかを照合し、役目を終えた一時ルールだけを削除します（明細そのものは消しません）。

一時ルールの条件は「摘要の完全一致・金額の上限と下限を両方とも同じ値に固定・口座名」の3つに絞り、同じ条件に当てはまる未処理の明細が全期間を通じて1件だけであることを確認してから作成を許可します（一意性の検査）。摘要を部分一致にすると、似た文言の別の明細まで巻き込んでしまうため、あえて完全一致に固定しています。

またfreeeが持っている「たぶんこの科目だろう」という推測機能には頼らず、科目・税区分は自分たちで指定した値をルールに直接書き込みます。優先度の高いルールほど推測より先に当たる仕組みを使い、狙った通りの仕訳が生まれるようにしています。

ルールに書き込める項目は、freeeの仕様上は取引先や品目、部門といった項目まで広く用意されています。ただし、存在しない取引先名や品目名を指定すると、freeeが自動で新しいマスタとして登録してしまう仕様があるため、私たちの仕組みでは「送ってよい項目」をあらかじめ絞った一覧として決め、それ以外の項目が1つでも混ざっていたら、そもそも送信しない作りにしています。

マスタが意図せず増えてしまう事故を、経路の入り口で防ぐという考え方です。

安全装置: 何を守るか

段3の「人が画面のボタンを押す」瞬間は、後戻りが難しくなる本番反映の一点です。ここに至るまでと、至った後のそれぞれに安全装置を置いています。この章は設計の詳細なので、急ぐ方は「いま・次・その先の3段階」まで読み飛ばしてもかまいません。

装置何を守るか
押す前の関所承認した件数・金額・使うルールを、実際に送る内容と突き合わせ、少しでも違えば止める。判定できなかった0件は「当たりが無い」と「そもそも判定できなかった」を分けて扱う
押した後の照合ルールを作る前に固定しておいた基準値と、実際の結果の差分を、成功でも失敗でも必ず取る。仕訳と明細の両方について確認する
指紋承認した内容そのものから作る短い符号（ハッシュ）。人がその先頭8桁を打ち込むことで、「たしかにこの内容を見て承認した」という記録を残す
見張り役作業をしていた端末が途中で落ちても、残った一時ルールを片付ける別の仕組み
回収コマンド上記でも片付かなかったときの最後の手段

見張り役と回収コマンドは、どちらも「一時ルールを作りっぱなしにしない」ための備えです。一時ルールが残ったまま翌月の明細が届くと、意図しない仕訳が自動で作られてしまうため、主の仕組みが途中で止まっても必ず片付く経路を二重に用意しています。

「判定できなかった0件」をわざわざ分けて扱う理由を補足します。安全確認のために「同じ明細が二重に処理されようとしていないか」をあらかじめ調べる仕組みを組み込んでいますが、調べる元データがそもそも十分に取得できていない場合、それを「一致するものが無かった」と同じ扱いにしてしまうと、本当は確認できていないだけなのに「問題なし」と判定されてしまいます。

だからこそ「当たりが無い」と「判定できなかった」は最初から別の結果として扱い、後者は必ず人の確認へ回すようにしています。

指紋がとくに重視しているのは、勘定科目と税区分です。この2つは明細側に対応する情報が存在しないため、実際に送られた値が承認した値と合っているかを、あとから機械的に検算する手段がありません。だからこそ、承認した時点の内容から作る指紋だけが、この2項目を守る唯一の砦になっています。

正直に書くと、「画面のボタンをクリックする」という操作だけが、構造的にAIには手が届かない唯一の歯止めです。それ以外の承認のやり取り（確認のやり取りや端末への打ち込みなど）は、突き詰めればAIが代わりに行える経路が存在します。

完全にAIが触れない鍵は存在しない、という限界も、承認を求める文書にそのまま明記しています。だからこそ、押す前の関所と押した後の照合という二重の確認を、クリックの前後に置いています。

いま・次・その先の3段階

この仕組みは一度にすべてを自動化するのではなく、段階を踏んで進めています。9月2日の失敗を踏まえて、いきなり本番へ書き込むのではなく、まず小さく試してから範囲を広げる、という進め方に切り替えました。

段階freeeへの反映人がすること
いますべて下書きのみ。freeeにはまだ1円も書き込んでいない全部手作業
次段1〜段4が実際に動く。数百円の1件で試してから、残り30件余りへ進める確認内容を見る・指紋の先頭8桁を打つ・画面のボタンを1回押す
その先型が決まっている取引は恒久的なルールにして、翌月からの同期時に自動で処理する。ボタン操作は不要になる例外だけを見る。月次レビューに使う数字が自動で出る

「次」の段階で件数をいきなり増やさないのは、想定外の当たり方をした場合の被害を最小限にとどめるためです。金額の小さい1件で4段の設計が想定どおりに動くことを確かめてから、残りの明細へ範囲を広げます。

「その先」で言う恒久的なルールとは、毎月同じ条件で繰り返し発生する取引について、一時ルールのように毎回作って消すのではなく、常設のルールとして残しておく方式です。恒久的なルールは、いまの一括適用の作業がすべて済んだ後に投入します。

過去の月に残っている未処理の明細を先に片付けておくことが前提で、そうしないと恒久ルールを入れても過去分の処理が進まないためです。段階を踏むことで、型が決まった取引ほど人の手を離れ、判断が要る例外だけが人の目に残る状態を目指しています。

間違えたときの戻し方

どれだけ関所や照合を積み重ねても、想定外は起こり得ます。だからこそ自動化の設計では「間違えたときにどう戻すか」を、実装する前の段階で決めておく必要があります。

間違えた内容戻し方
仕訳を作ってしまったその仕訳を削除すれば、元の明細は自動的に未処理へ戻る（社内で実測済み）
一時ルールが残ってしまった見張り役による自動片付け、または回収コマンドで削除する
明細を「無視」にしてしまった画面上でしか戻せない。だからこそ機械の処理経路には「無視」を最初から通さない設計にしている

3つのうち上の2つは、いずれも「作ったものを削除すれば元に戻る」という単純な戻し方で済みます。仕訳は削除すれば明細が未処理に戻ることが社内の検証で確認できており、一時ルールも作りっぱなしにせず必ず片付ける仕組みを備えています。

一方で「無視」だけは性質が違い、画面上でしか元に戻せません。「無視」だけが一方通行だと分かっていたからこそ、9月2日の失敗を踏まえて、自動化する処理から「無視」という選択肢そのものを外しました。戻せない操作を戻せる仕組みで補おうとせず、経路そのものを塞ぐという判断です。

学び: AIに業務を任せるときの設計原則

今回の一連の経緯から得られた教訓は、freeeに限らずAIに業務を任せるときの一般的な設計原則として整理できます。

1点目は、取り消せない瞬間をできるだけ1点に絞り込み、そこだけを人が担当することです。今回で言えば「画面のボタンを押す」の1回だけが本番反映の瞬間で、それ以外の準備・確認・後片付けはすべて機械が担っています。取り消せない箇所が複数に散らばっていると、どこか1か所を見落としただけで事故につながります。

2点目は、機械の推測に帳簿を委ねないことです。これはfreee自身のAI機能にも、私たちが作ったAIの仕組みにも同じように当てはまります。指定したはずの科目・税区分が実際に入ったかどうかは、必ず読み取って照合します。便利な自動推測ほど、狙い通りに動いているかを別の手段で確かめる仕組みとセットにする必要があります。

3点目は、戻せる操作だけを自動化し、戻せない操作は経路ごと塞ぐことです。仕訳の作成・ルールの作成と削除はすべて戻せる操作である一方、「無視」の解除は画面でしか戻せないため、自動化の対象から外しています。すべてを自動化しようとするのではなく、安全に戻せる範囲を見極めて、その内側だけを機械に任せるという発想です。

freeeを使っている方への持ち帰りを1つだけ挙げると、「AIやツールに仕訳を自動で登録させているなら、帳簿の数字だけでなく、元の明細が本当に処理済みになっているかを月に一度は画面で確かめる」ことです。私たちの失敗は、帳簿側だけを見て「完了」と思い込んだところから始まりました。

また自分で自動登録ルールを設定している方は、一括適用が全期間の未処理明細に効くことを踏まえ、条件の広すぎるルールを作らないよう注意してください。

外部の視点から今回の方式を検証したところ、「一時的なルールを作って画面で発火させ、後片付けする」というやり方そのものの先行事例は見当たりませんでした。独自色が強い方式ではありますが、それはむしろ、freeeに他の正規の経路が用意されていないことの裏返しでもあります。

請求書や経費精算のアプリを経由する代替も調べましたが、いずれも最終的には人による1回の確定操作が残るため、当社の方式より簡単・確実とまでは言えないという結論でした。現時点での推奨は、いまの方式を維持しながら、freeeへ機能要望を出しつつ、API側の更新を定点観測し続けることです。

参考リンク