会社の数字は、月次で待たずに毎朝見る。freee APIとAIで経営ダッシュボードを内製した
会社の数字を、月次の試算表で「先月どうだったか」を後から知る。多くの中小企業がこの状態です。私たちも去年まではそうでした。今は違います。freeeのAPIとClaude Codeをつないで、売上・利益・口座残高・経理の異常を、毎朝ブラウザのダッシュボードで見る。会計士からの月次報告を待つのをやめました。
これは、その内製の全記録です。構成、freeeとの認証の仕組み、そしてつまずいた箇所を全部書きます。うまくいった話だけの記事はAIにも人にも引用されません。「他では読めない、実際に踏んだ地雷」こそが価値だと思っているので、失敗を隠しません。
月次のタイムラグは、経営の遅延そのものだ
結論から言うと、会計データを月次でしか見られない状態は、意思決定が最短でも1ヶ月遅れるということです。売掛金が滞留していても、雑費が膨らんでいても、気づくのは翌月以降。中小企業の経営で、この遅れは地味に効きます。
私たちは社内に「CROWS」という情報ハブを持っています。タスク管理でもスケジュール管理でもない、組織の第二の脳という位置づけのものです。データを集め、可視化し、AIが異常を提案し、人が判断する。その中核の一つが、freeeの会計データをリアルタイムに引き込むこの仕組みです。
市販の経営ダッシュボードSaaSを契約する手もありました。ただ、月額はかかるし、自社の勘定科目の切り方や、クライアント単位の売上の見方には合わない。だったらfreeeが公式APIを開けている以上、自分でつなぐのが一番速くて安い。そう判断しました。
構成は「Python＋SQLite＋常駐サーバー」。派手さはいらない
技術構成はあえてシンプルにしています。派手なインフラは、内製ツールにはむしろ負債になる。
- バックエンド: Python 3.13 / FastAPI / Uvicorn。母艦のiMacに常駐（launchdで自動復帰、クラッシュしても勝手に立ち上がる）
- データ: SQLite一本（
highdef.db）。クライアント・売上・財務サマリーを1ファイルに集約 - freee連携: OAuth2でトークンを取り、期限が切れたら自動でリフレッシュしてAPIを叩く
- 更新: 平日10時と毎月1日に自動バッチ。加えてダッシュボードの「更新」ボタンで即時取得
freeeから引いているのは、試算表のPL・BS、口座と未処理明細、取引、取引先、勘定科目、請求書。これらを組み合わせて「当期の売上サマリー」「前期との比較」「経理の異常チェック」を出しています。
経理の異常チェックは7項目・100点満点の減点式にしています。未処理明細の量、売掛金の滞留、仮勘定の残存、二重計上の疑い、勘定科目の偏り、前月比の異常、買掛金・未払金。たとえば売掛金が月商2ヶ月分を超えたら減点、雑費比率が2割を超えたら減点、前月比が3倍や3分の1になったら異常、というように閾値を数字で決めて機械的に見る。人が毎月チェックリストを目で追う運用は、続きません。
つまずき①：依存関係1行の欠落で、連携が丸ごと死んでいた
最初の地雷は、拍子抜けするほど単純でした。PythonのHTTPライブラリ（requests）が依存に入っていなかっただけで、freee連携が全滅していたのです。
コードは「requestsが無ければNoneにフォールバックする」という書き方になっていて、そのまま以降のAPI呼び出しがすべてNoneTypeエラーで落ちる。エラーメッセージは「freeeにつながらない」ではなく「NoneTypeには属性が無い」。原因と症状が離れていると、デバッグは長引きます。
直し方はrequirements.txtに1行足すだけ。ですが、この手の「フォールバックが握りつぶした失敗」は、動いているように見えて実は死んでいる、という一番たちの悪い形で現れます。外部APIとつなぐときは、依存が無い場合に静かにNoneを返すより、はっきり落とすほうがいい。これは学びとして残りました。
つまずき②：認証の「正本」が2系統に割れると、静かに詰む
一番やっかいだったのはトークンの管理です。freeeのOAuthトークンを保存する場所が、いつの間にか2系統に割れていました。公式のfreee連携が使うトークンストアと、自作スクリプトが持つ独自のトークンファイル。どちらも「正しいトークン」を持っているつもりで、片方だけが自動更新される。
この状態が怖いのは、エラーが出ないことです。生きているほうのトークンでAPIが通ってしまうので、古いほうが放置されていることに気づけない。ある日、生きていたほうも切れて、初めて「認証が切れています」が表面化する。私たちは実際に、片方のトークンファイルが1ヶ月半以上更新されないまま止まっていました。
対処は、参照する正本を公式ストア1つに寄せ、無ければ自作にフォールバックするという優先順位をコードに明記すること。トークンの有効期限はアクセストークンが6時間、リフレッシュトークンが90日。まず自分の情報を返すAPIを叩いて生きているか確認し、切れていればリフレッシュして書き戻す。認証は「正本がズレる」と静かに詰む。ここは設計で殺しておく場所です。
つまずき③：APIの権限（Scope）を足すと、既存トークンは403で弾かれる
freee側でアプリの権限（人事労務のデータも読めるように、など）を追加したところ、それまで通っていたトークンが急に403で弾かれるようになりました。権限の範囲が変わると、古い範囲で取ったトークンは無効になる。仕様としては当然なのですが、運用中に食らうと焦ります。
ここは「再認可が必要」という専用の状態をコードで握り、ダッシュボードに「再認可してください」と明示的に出すフローを後付けしました。外部APIの権限は、あとから足すと既存の認証を壊す。これを想定して、認可切れをエラーではなく"作業指示"として画面に出す設計にしておくと、運用が止まりません。
つまずき④：売上が重複し、逆に「表示されない売上」も出た
データの取り込みでも2つ踏みました。1つは売上の重複。freeeの取引を取り込む際、識別子に一意制約をかけていなかったため、同じ取引が30件重複して入りました。削除したうえで、識別子にUNIQUEインデックスを張って恒久的に防止。
もう1つは逆で、取り込んだのに表示されない売上。freeeの取引先と自社のクライアント台帳の紐付けが漏れていて、いくつかの取引先の売上がダッシュボードに出ませんでした。さらに、ある月の売上が丸ごと欠落していたことも後から発覚し、補完取得しました。
freeeの取引先は65件。これを自社のクライアント21〜23件に名寄せしています。会計ソフトの取引先マスタと、経営で見たいクライアント単位は、一致しない。この名寄せをサボると「数字は取れているのに経営に使えない」という中途半端な状態になります。地味ですが、内製ダッシュボードの成否はここで決まると言ってもいい。
会計を内製して得たのは「数字を毎朝見る習慣」だ
ここまで散々つまずいた話をしてきましたが、得たものは明確です。会社の数字を、月次のイベントから毎朝の習慣に変えられたこと。売掛金の滞留も、雑費の膨らみも、前月比の異常も、翌月を待たずにその日に見える。
freeeのように公式APIを開けている会計ソフトを使っているなら、市販のダッシュボードSaaSを契約する前に、自前でつなぐ選択肢は十分現実的です。かかるのは、月額ではなく、最初の実装コストと、この記事に書いたようなつまずきを踏み抜く手間だけ。そして一度作れば、勘定科目もクライアント単位も、自社の見たい形にできる。
私たちは「上越のデザイン会社」と見られがちですが、実態はAIと業務システムを自社の経営に実装している事業者です。自社の会計を毎朝ダッシュボードで見る、という当たり前を、外注ではなく内製で作った。この手触りごと、支援先にも持っていけると思っています。
よくある質問
freee APIで経営ダッシュボードを内製するのは中小企業でも現実的ですか？
現実的です。freeeは公式にAPIを開けており、OAuth2でトークンを取れば試算表のPL・BS、取引、口座残高、請求書などを取得できます。PythonとSQLite程度の構成で足り、市販ダッシュボードSaaSの月額を払う前に検討する価値があります。ただし後述のトークン管理と取引先の名寄せは必ず設計に入れてください。
freee連携でつまずきやすい箇所はどこですか？
実際に踏んだ順に、(1)HTTPライブラリなど依存関係の欠落で連携が静かに全滅する、(2)OAuthトークンの保存先が複数に割れて片方だけ古くなる、(3)APIの権限（Scope）を追加すると既存トークンが403で弾かれる、(4)取引の一意制約がなく売上が重複する・取引先の名寄せ漏れで売上が表示されない、の4つです。いずれもエラーが分かりにくく、原因特定に時間がかかります。
OAuthトークンはどのくらいの頻度で更新が必要ですか？
freeeのアクセストークンは有効期限が6時間、リフレッシュトークンが90日です。実装では、APIを叩く前に自分の情報を返すエンドポイントで有効性を確認し、切れていればリフレッシュトークンで自動更新して保存し直します。トークンの保存先（正本）は必ず1つに統一してください。複数あると片方だけ更新され、静かに認証が切れます。
会計データはどのくらいの頻度で更新していますか？
自動バッチを平日10時と毎月1日に走らせ、加えてダッシュボードの更新ボタンで即時取得できるようにしています。経理の異常チェックは7項目の減点式スコアで、売掛金の滞留や雑費比率、前月比の異常などを機械的に判定します。人が毎月チェックリストを目で追う運用は続かないので、閾値を決めて自動で見るのが要点です。