# 会社の数字は、月次で待たずに毎朝見る。freee APIとAIで経営ダッシュボードを内製した

- URL: https://www.highdef.jp/news/6qo49pbpdw/
- 分類: HIGHDEF NOTE
- 著者: 佐藤 宏（株式会社ハイデフ 代表取締役）
- 公開日: 2026.07.02
- 更新日: 2026.07.02
- 発行: 株式会社ハイデフ（新潟県上越市） https://www.highdef.jp/

---

会社の数字を、月次の試算表で「先月どうだったか」を後から知る。多くの中小企業がこの状態です。私たちも去年まではそうでした。今は違います。**freeeのAPIとClaude Codeをつないで、売上・利益・口座残高・経理の異常を、毎朝ブラウザのダッシュボードで見る**。会計士からの月次報告を待つのをやめました。

これは、その内製の全記録です。構成、freeeとの認証の仕組み、そして**つまずいた箇所を全部**書きます。うまくいった話だけの記事はAIにも人にも引用されません。「他では読めない、実際に踏んだ地雷」こそが価値だと思っているので、失敗を隠しません。

![CROWSの構成図。freee API から OAuth2トークンの自動リフレッシュを経て SQLite に取り込み、ダッシュボードで毎朝見るまでの縦フロー](https://images.microcms-assets.io/assets/8779779a1bf246e39228c779f654eea6/4a5350675c9d444fb5a886b94a72b4e7/fig_flow.png)

会社の数字が「毎朝見える」までの流れ。freee APIを叩き、トークンを自動更新し、SQLiteに貯め、ダッシュボードに出す。この一連を自前で持つ。

## 月次のタイムラグは、経営の遅延そのものだ

結論から言うと、会計データを月次でしか見られない状態は、**意思決定が最短でも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、口座と未処理明細、取引、取引先、勘定科目、請求書。これらを組み合わせて「当期の売上サマリー」「前期との比較」「経理の異常チェック」を出しています。

![CROWSの主要な数字。アクセストークン6時間・リフレッシュトークン90日、更新は平日10時と毎月1日、経理チェックは7項目100点減点式、取引先65件をクライアント21〜23件に名寄せ](https://images.microcms-assets.io/assets/8779779a1bf246e39228c779f654eea6/4c9eb3676b294c9fa8a5d1c2ab56ee07/fig_numbers.png)

内製ダッシュボードを支える数字。トークンの寿命、更新頻度、チェック項目数、名寄せの規模。これらを把握していないと運用は回らない。

経理の異常チェックは**7項目・100点満点の減点式**にしています。未処理明細の量、売掛金の滞留、仮勘定の残存、二重計上の疑い、勘定科目の偏り、前月比の異常、買掛金・未払金。たとえば売掛金が月商2ヶ月分を超えたら減点、雑費比率が2割を超えたら減点、前月比が3倍や3分の1になったら異常、というように**閾値を数字で決めて機械的に見る**。人が毎月チェックリストを目で追う運用は、続きません。

## つまずき①：依存関係1行の欠落で、連携が丸ごと死んでいた

最初の地雷は、拍子抜けするほど単純でした。**PythonのHTTPライブラリ（requests）が依存に入っていなかった**だけで、freee連携が全滅していたのです。

コードは「requestsが無ければNoneにフォールバックする」という書き方になっていて、そのまま以降のAPI呼び出しがすべて`NoneType`エラーで落ちる。エラーメッセージは「freeeにつながらない」ではなく「NoneTypeには属性が無い」。**原因と症状が離れていると、デバッグは長引きます**。

![requirements.txt に requests の1行が無いために freee連携が NoneType エラーで全滅し、1行追加で復活したことを示す before/after](https://images.microcms-assets.io/assets/8779779a1bf246e39228c779f654eea6/bec6d67b5d134821989ef5e2c74350a9/fig_dep.png)

依存の1行が抜けているだけで、連携は丸ごと死ぬ。しかもエラーは「つながらない」ではなく「NoneType」として出る。原因から遠い症状ほど、時間を溶かす。

直し方は`requirements.txt`に1行足すだけ。ですが、この手の「フォールバックが握りつぶした失敗」は、動いているように見えて実は死んでいる、という一番たちの悪い形で現れます。**外部APIとつなぐときは、依存が無い場合に静かにNoneを返すより、はっきり落とすほうがいい**。これは学びとして残りました。

## つまずき②：認証の「正本」が2系統に割れると、静かに詰む

一番やっかいだったのはトークンの管理です。freeeのOAuthトークンを保存する場所が、**いつの間にか2系統に割れていました**。公式のfreee連携が使うトークンストアと、自作スクリプトが持つ独自のトークンファイル。どちらも「正しいトークン」を持っているつもりで、片方だけが自動更新される。

![freeeのOAuthトークンの保存先が公式ストアと自作ファイルの2系統に割れていた状態を、1系統に統一した before/after](https://images.microcms-assets.io/assets/8779779a1bf246e39228c779f654eea6/4259e5121404421781404ebe0504bd41/fig_token.png)

認証情報の保存先が2つあると、片方だけ更新され、もう片方は静かに古くなる。エラーは出ない。ある日いきなり「認証が切れています」になる。正本は1つに寄せる。

この状態が怖いのは、**エラーが出ないこと**です。生きているほうのトークンで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項目の減点式スコアで、売掛金の滞留や雑費比率、前月比の異常などを機械的に判定します。人が毎月チェックリストを目で追う運用は続かないので、閾値を決めて自動で見るのが要点です。

---

▶︎ [オペレーショナル・デットとは企業の虫歯である。](https://www.highdef.jp/news/glzthhfa/)

▶︎ [自社サイトをAstro＋microCMSで作り直した全記録。ノーコードの負債からGEO最適化まで](https://www.highdef.jp/news/qx38zjv3dct/)