会計APIは、便利さと事故の影響が同時に大きい連携です。最初から取引登録を自動化せず、事業所、勘定科目、税区分、取引一覧を読むところから始めました。
先に決めた安全境界
設計時に、次のルールを固定しました。
- 初期値は
FREEE_ENABLE_WRITES=false - トークンは専用ファイルへ保存し、権限を絞る
- AIの回答へアクセストークンやrefresh tokenを出さない
- 一件あたりの登録金額に上限を設ける
- API呼び出し結果と失敗を監査ログへ残す
- 削除APIは最初の版に入れない
「使わなければ安全」ではなく、「使おうとしても拒否される」状態をコード側で作ることが重要です。
OAuth 2.0で接続する
freee会計APIはOAuth 2.0を使用します。アプリを登録し、クライアントID、クライアントシークレット、redirect URIを取得します。記事では必ずダミー値を使います。
FREEE_CLIENT_ID=YOUR_CLIENT_ID
FREEE_CLIENT_SECRET=YOUR_CLIENT_SECRET
FREEE_COMPANY_ID=123456
FREEE_ENABLE_WRITES=false認可後のトークンは失効や更新を前提に扱います。ブラウザに表示された認可コードを会話履歴へ貼るのではなく、必要なツールへ一度だけ渡し、ログへ残さない設計にします。
読み取りで確認する順番
- 接続状態と書き込み無効を確認する
- 自分がアクセスできる事業所を一覧する
- 対象事業所IDが想定どおりか確認する
- 勘定科目と税区分を取得する
- 期間と件数を絞って取引を取得する
AIに「最近の取引を全部見せて」と頼むのではなく、対象期間、件数、必要項目を限定します。データ最小化は、応答速度だけでなくプライバシー面でも有効です。
API仕様は変化する
freee公式の2026年4月27日告知では、取引作成・更新時の明細行上限が40行から100行へ拡大されました。これは非破壊的変更ですが、APIレスポンスへ任意項目が追加されることもあります。未知のプロパティが増えても壊れない実装と、公式変更情報の定期確認が必要です。
再現チェック
- [ ] OAuthアプリのredirect URIを確認した
- [ ] 書き込みフラグは初期値false
- [ ] トークンをソースコードへ書いていない
- [ ] 対象事業所IDを人が確認した
- [ ] 取得期間と件数を制限した
- [ ] 削除機能を公開していない
次回は、取引登録を将来可能にする場合でも誤登録を防ぐ、確認コード方式を紹介します。