--- title: "freee APIとは：会計APIの認可・事業所IDと取引登録をPythonで実装する手順と上限" url: "https://www.issoh.co.jp/tech/details/19184/" published: 2026-11-02 updated: 2026-11-02 categories: ["業務システム"] publisher: "株式会社一創" --- # freee APIとは：会計APIの認可・事業所IDと取引登録をPythonで実装する手順と上限 freee APIは、freee会計やfreee人事労務などのデータを、自社のシステムからHTTPで読み書きするためのAPIです。この記事では、中心となるfreee会計APIを対象に、OAuth 2.0による事業所単位の認可、6時間で切れるアクセストークンと1回しか使えないリフレッシュトークンの扱い、Pythonでの取引の登録と一覧の取得、プランごとに決まる1日の呼び出し上限までを、コード例付きで説明します。公式リファレンスでは別々のページに分かれている「実装で詰まる箇所」を、1本にまとめました。仕様と数値は2026年11月時点の公式ドキュメントと公式OpenAPI定義に基づきます。 ## まとめ：freee APIで会計連携を作る前に決める認可の単位と呼び出し上限 freee会計APIの認証はOAuth 2.0だけです。認可URLに`prompt=select_company`を付けると、利用者が選んだ1つの事業所にだけアクセスできるトークンが発行され、応答に事業所ID`company_id`が入ります。ほぼすべてのAPIでこのIDが必須なので、トークンと一緒に保存します。 詰まりやすいのは次の4点です。アクセストークンは6時間、リフレッシュトークンは90日で、リフレッシュトークンは1回しか使えないこと。公式FAQが、前のアクセストークンが切れる前に更新するよう求めていること。取引と振替伝票は別のAPIで、売掛・買掛のレポートに載るのは取引だけであること。403が「呼び出しすぎ」と「権限不足」の2つの意味で返ること。 上限は事業所とアプリの組み合わせごとに1日3,000回から10,000回で、契約プランで決まります。冪等キーの仕組みは無いため、再実行で同じ取引が2件できない設計は呼び出し側で作ります。 ## freee会計APIの全体像と操作できる範囲・エンドポイント・プラン差 ### 取引・振替伝票・口座明細・試算表など107本のエンドポイントの範囲 freeeが公開している[公式のOpenAPI定義（freee-api-schema）](https://github.com/freee/freee-api-schema)には、会計APIのパスが107本定義されています。業務でよく使うものを区分ごとに並べると次のとおりです。 | 区分 | パス | 主な操作 | | ---- | ----------------- | ------------------ | | 取引 | deals | 収入・支出の作成、支払行の追加 | | 振替伝票 | manual\_journals | 貸借を指定した伝票の作成 | | 口座明細 | wallet\_txns | 明細の登録と取引への変換 | | 帳票 | reports | 試算表（BS・PL）と総勘定元帳 | | 仕訳帳 | journals | ファイル出力の依頼と取得 | | マスタ | account\_items ほか | 勘定科目・税区分・取引先・部門・品目 | パスはすべて`https://api.freee.co.jp/api/1/`の後ろに続きます。このOpenAPI定義はGitHubからそのまま取得できるので、型の生成やPostmanのコレクション作成に使えます。画面で見るなら[会計APIリファレンス](https://developer.freee.co.jp/reference/accounting)が同じ内容です。 ### 総勘定元帳と固定資産台帳のAPIが上位プランに限られるプラン差 freee会計APIは、Web版で使える機能がAPIでも使えるという原則です。経費精算を使える契約なら、経費精算のAPIも呼べます。例外として、公式OpenAPI定義の説明欄には次の2つが明記されています。 - 総勘定元帳API：法人アドバンスプラン、法人エンタープライズプラン（旧プロフェッショナル・旧エンタープライズを含む）のみ - 固定資産台帳API：法人エンタープライズプラン（旧エンタープライズを含む）のみ - セグメントタグのパラメータ：法人アドバンスプラン以上（セグメント2・3はアドバンスとエンタープライズ） 対象外のプランで呼ぶと401が返り、エラーコードは`freee_plan_limit`です。顧客ごとに契約プランが違う連携を作るときは、プラン差で落ちる機能を要件定義の段階で洗い出しておきます。 ### 使える機能と上限は接続先の事業所の契約で決まり、開発環境は無料 API経由で使える機能と上限は、接続先の事業所が契約しているfreee会計のプランで決まります。開発中の動作確認には、[開発用テスト環境の案内](https://developer.freee.co.jp/reference/%E9%96%8B%E7%99%BA%E7%94%A8%E3%83%86%E3%82%B9%E3%83%88%E7%92%B0%E5%A2%83%E3%81%AB%E3%81%A4%E3%81%84%E3%81%A6)にある「開発用テスト事業所」が無料で作れる仕組みです。事業形態とプランを選んで作れるので、法人アドバンス相当の機能も本番の契約なしで試せます。 注意点が1つあります。作成から90日以上たち、過去90日間にアプリ経由のAPI実行が無いテスト事業所は、アプリごと削除対象になり、復旧できません。開発が止まる期間がある案件では、テストデータの作成手順をスクリプトに残しておくと作り直しが楽です。 ## OAuth 2.0の認可を事業所単位で通すアプリ登録とトークン管理の実装 ### プライベートは5事業所、パブリックは既定20事業所というアプリ種別の差 アプリはfreeeアプリストアの開発者画面で作ります。[アプリについての公式説明](https://developer.freee.co.jp/reference/application-types)によると、種別は2つです。 | 項目 | プライベートアプリ | パブリックアプリ | | --------- | ----------- | ------------- | | 想定する使い方 | 特定の事業所だけで使う | 複数の事業所へ配布する | | 接続できる事業所数 | 5事業所まで | 既定20事業所まで | | 上限の解除 | 不可 | ストア公開か上限変更の申請 | | アプリストア掲載 | 不可 | 審査を経て可能 | | 銀行明細の取得 | 申請不要 | 申請が必要 | 自社の会計と社内システムをつなぐだけならプライベートで足ります。会計事務所が顧問先を6社以上つなぐ、あるいは自社サービスとして配る場合はパブリックを選びます。上限変更の申請は、接続事業所が15に達するまで出せない点も計画に入れてください。 ### select\_company指定で1事業所だけを認可させる認可URLとトークン取得 認可はOAuth 2.0の認可コードフローで行います。[公式の認可の説明](https://developer.freee.co.jp/reference/%E8%AA%8D%E5%8F%AF%E3%82%B3%E3%83%BC%E3%83%89)にあるとおり、認可エンドポイントは`https://accounts.secure.freee.co.jp/public_api/authorize`、トークンエンドポイントは同じホストの`/public_api/token`です。APIを呼ぶホスト`api.freee.co.jp`とは別なので、設定値を取り違えないようにします。 ``` # 1. ブラウザで開く（prompt=select_company で事業所選択画面を出す） https://accounts.secure.freee.co.jp/public_api/authorize?response_type=code&client_id=${CLIENT_ID}&redirect_uri=${REDIRECT_URI}&state=${STATE}&prompt=select_company # 2. リダイレクト先に付いた code をトークンに交換する curl -s -X POST "https://accounts.secure.freee.co.jp/public_api/token" \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "grant_type=authorization_code" \ -d "client_id=${CLIENT_ID}" \ -d "client_secret=${CLIENT_SECRET}" \ -d "code=${AUTH_CODE}" \ -d "redirect_uri=${REDIRECT_URI}" # 応答例: {"access_token":"...","expires_in":21600,"refresh_token":"...","company_id":123, ...} ``` [事業所の選択についての説明](https://developer.freee.co.jp/reference/select-company)では、`prompt=select_company`を付ける方式が推奨で、付けない方式（アカウントの全事業所を認可する）は将来廃止予定とされています。付けない方式でストアに出すと、事業所選択を自前で実装していない限り審査で承認されません。新規の実装は最初から付ける形で作ってください。認可フローの考え方は[OAuth 2.0の仕組みと認可フローの解説](https://www.issoh.co.jp/tech/details/8369/)で扱っています。 ### 6時間のアクセストークンと90日で1回限りのリフレッシュトークンの更新 [トークンの有効期限についてのFAQ](https://developer.freee.co.jp/reference/faq/token%5Flifetime)によると、アクセストークンは6時間、リフレッシュトークンは90日有効です。1つのリフレッシュトークンで2回アクセストークンを取ることはできず、更新のたびに返る新しいリフレッシュトークンを保存し直します。 実装上の落とし穴は2つあります。1つは、同じFAQが401のチェック項目として「前のアクセストークンが有効な間に更新する」ことを挙げている点です。401を受けてから更新する作りだと、この条件を外れることがあるため、期限の少し前に更新する作りにします。もう1つは、再試行による二重の更新。[エラーレスポンスの説明](https://developer.freee.co.jp/reference/40x-checkpoint)では、更新後に古いトークンを使うと`invalid_grant`になるとされています。 ``` # pip install requests import os import time import requests TOKEN_URL = "https://accounts.secure.freee.co.jp/public_api/token" BASE = "https://api.freee.co.jp/api/1" def refresh(store) -> dict: """store は DB のトークン行（排他ロックを取った状態で渡す想定）""" # 期限の30分前を過ぎたら更新する（アクセストークンが有効なうちに更新する） if time.time() < store["expires_at"] - 1800: return store r = requests.post(TOKEN_URL, data={ "grant_type": "refresh_token", "client_id": os.environ["FREEE_CLIENT_ID"], "client_secret": os.environ["FREEE_CLIENT_SECRET"], "refresh_token": store["refresh_token"], }, timeout=10) r.raise_for_status() # 401 invalid_grant は使用済みトークンの再利用を疑う body = r.json() # 新しいリフレッシュトークンは1回限り。取得と保存を同じトランザクションで確定させる store.update( access_token=body["access_token"], refresh_token=body["refresh_token"], expires_at=time.time() + body["expires_in"], # 21600秒＝6時間 ) return store ``` 複数のワーカーが同じ事業所のトークンを同時に更新すると、遅れたほうが使用済みのリフレッシュトークンを送って失敗します。トークン行に排他ロックを取ってから更新し、保存が終わるまで他の処理を待たせます。90日のあいだ1回も更新しなかった事業所は再認可が必要になるので、取引の少ない事業所にも定期的な更新ジョブを回しておくのが安全策です。 ## 取引の登録と一覧取得の実装：事業所IDから勘定科目・税区分まで ### 認可した事業所のcompany\_idをトークンと保存しクエリと本文に付ける freee会計APIは、事業所一覧の取得などを除き、どの事業所のデータかを`company_id`で指定します。GETではクエリに、POSTやPUTではJSON本文に入れます。`prompt=select_company`で認可した場合、トークン取得の応答に入っている`company_id`がそのまま使う値で、選ばれなかった事業所の詳細には触れません。 存在しない、または削除済みの事業所IDを指定すると、401のエラーコード`company_not_found`が返ります。複数の事業所を扱うシステムでは、事業所IDとトークンを同じ行に保存し、処理の入り口で取り出す形にしておくと、別の事業所へ書き込む事故を防げます。兄弟製品の[マネーフォワード APIの実装手順](https://www.issoh.co.jp/tech/details/19181/)は、APIキー認証で事業所番号を呼び出しごとに指定する方式なので、両方に対応する連携基盤では事業所の持ち方を分けた設計が必要です。 ### 取引作成の必須項目は4つで明細は最大100行、金額は税込の円で送る 取引（収入・支出）は`POST /api/1/deals`で作ります。公式OpenAPI定義の必須項目は、事業所ID`company_id`、発生日`issue_date`、収支区分`type`（`income`か`expense`）、明細行`details`の4つです。明細行は最大100行で、各行に税区分コード`tax_code`と、税込・円単位の金額`amount`が必須になります。 ``` def call(method: str, path: str, token: str, **kw): r = requests.request(method, BASE + path, headers={"Authorization": f"Bearer {token}"}, timeout=30, **kw) r.raise_for_status() return r.json() token, company_id = store["access_token"], store["company_id"] # 勘定科目と税区分は名前ではなくIDとコードで送る。先に対応表を作る items = call("GET", "/account_items", token, params={"company_id": company_id})["account_items"] acc = {a["name"]: a["id"] for a in items} TAX_CODE_SALES = int(os.environ["FREEE_TAX_CODE_SALES"]) # 事業所ごとに値を確認して設定する deal = { "company_id": company_id, "issue_date": "2026-11-02", "type": "income", "due_date": "2026-11-30", "ref_number": "SO-2026-0042", # 管理番号。元データのキーを入れて照合に使う "details": [{ "account_item_id": acc["売上高"], "tax_code": TAX_CODE_SALES, # 税区分APIで事前に確認した課税売上のコード "amount": 110000, # 税込・円 "description": "11月分 保守料", }], } created = call("POST", "/deals", token, json=deal) print(created["deal"]["id"]) # 更新・削除で使うID。自社DBに保存しておく ``` 税区分コードは、`GET /api/1/taxes/companies/{company_id}`でその事業所が使える一覧を取ってから決めます。コード例では確認済みの値を環境変数で渡していますが、税率の変更に合わせて見直せるよう、設定値として外に出しておくのが無難です。取引先コードや勘定科目コードを使いたい場合は、事業所の設定でコード利用を有効にする必要があり、IDとコードを同時には指定できません。 ### 取引と振替伝票の使い分けは売掛買掛レポートに載せるかどうかで判断 貸借を自分で組む仕訳は`POST /api/1/manual_journals`（振替伝票）で作ります。公式OpenAPI定義の注意点には、振替伝票は売掛・買掛レポートに反映されず、債権・債務の登録には取引APIを使うよう書かれています。貸借行は合計100行までで、貸方と借方の合計が一致していることが条件です。 判断の基準は単純です。請求や支払の消し込みを追う売上・仕入は取引で登録する。減価償却や科目の振り替えのように債権・債務を伴わないものは振替伝票で登録する。販売管理から売上を流す連携で振替伝票を使うと、入金の消し込みがfreeeの画面でできなくなり、経理担当者の手作業が残ります。仕訳の起点をどこに置くかは[経理システムと会計システムの違いの解説](https://www.issoh.co.jp/column/details/16461/)でも整理しています。 ### 一覧取得はlimit最大100件で、仕訳帳は非同期のファイル出力で取る `GET /api/1/deals`の1回の取得件数`limit`は既定20件、最大100件で、`offset`をずらして次を取ります。発生日`start_issue_date`と`end_issue_date`で範囲を絞れます。 ``` offset, rows = 0, [] while True: res = call("GET", "/deals", token, params={ "company_id": company_id, "start_issue_date": "2026-04-01", "end_issue_date": "2026-11-30", "limit": 100, "offset": offset, }) rows += res["deals"] if len(res["deals"]) < 100: break offset += 100 print(len(rows), "件") ``` 1万件の取引を取ると100回の呼び出しになり、後述する1日の上限を食います。会計期間の仕訳をまとめて取りたいときは、仕訳帳の`GET /api/1/journals`を使います。こちらはファイル作成を依頼するだけのAPIで、返った受付IDで`/journals/reports/{id}/status`を確認し、`uploaded`になってから`/download`で取得する2段階です。文字コードは指定しないとShift\_JISになるので、`encoding=utf-8`を付けておきます。 ## 本番運用で詰まる上限：1日のAPIコール数と403・429・二重登録 ### 事業所とアプリごとに1日3,000〜10,000回というプラン別の呼び出し上限 公式OpenAPI定義の説明欄には、事業所とアプリケーションの組み合わせごとの1日の上限が載っています。 | freee会計のプラン | 1日の上限 | | ---------------------- | ------- | | 法人エンタープライズプラン | 10,000回 | | 法人アドバンスプラン（旧プロフェッショナル） | 5,000回 | | 上記以外（個人のプランを含む） | 3,000回 | 3,000回は、取引を1件ずつ登録すれば1日3,000件で尽きる数です。月末に数千件をまとめて送る処理では、明細を1件の取引に複数行まとめる、マスタの取得を起動時の1回に絞る、といった呼び出し回数の節約を最初から設計に入れます。同じ事業所に複数のアプリをつないでいる場合、上限はアプリごとに数えられます。 ### 過度のアクセスで返る403と権限不足の403を見分けて10分待つ判断 freee会計APIの呼び出しすぎは、一般的な429ではなく403で返ります。公式OpenAPI定義の説明では、一定期間に過度のアクセスを検知すると403でアクセスを制限し、10分程度で解除されるとしています。一方、アプリの権限設定に無いエンドポイントを呼んだときも403で、メッセージは「このアプリケーションにはアクセス権限がないエンドポイント」である旨の文言です。 両者を同じ扱いにすると、権限不足を10分待って再試行し続ける、あるいは制限中に権限設定を疑って時間を失う、という失敗が起きます。本文のメッセージで分岐し、権限不足ならすぐに失敗として通知、それ以外の403は10分以上空けてから再開する作りが安全です。429が返るのは試算表などの`/reports`（毎秒10回まで）と証憑のダウンロード`/receipts/{id}/download`（毎秒3回まで）で、応答ヘッダ`x-ratelimit-reset`にリセット時刻が入ります。待ち方の設計は[APIレート制限の解説](https://www.issoh.co.jp/tech/details/16179/)と[リトライパターンと指数バックオフの解説](https://www.issoh.co.jp/tech/details/16185/)が参考になります。 ### 再送で同じ取引が2件できる問題を管理番号と自社DBの対応表で防ぐ 取引作成のAPIには、重複を防ぐ冪等キーがありません。タイムアウトで応答を受け取れなかった処理をそのまま再送すると、同じ取引が2件できます。取引一覧の絞り込み条件も、取引先・勘定科目・発生日などで、管理番号`ref_number`では検索できません。 1. 自社DBに「元データのキーと取引ID」の対応表を作り、送信前に状態を「送信中」で登録する 2. 201が返ったら取引IDを書き込み、状態を「完了」にする 3. 「送信中」のまま残った行は、発生日で取引一覧を取り、`ref_number`に入れた元データのキーで照合してから再送するか決める 照合のために、管理番号には元データのキーを必ず入れます。考え方は[冪等性と担保方法の解説](https://www.issoh.co.jp/tech/details/13382/)にまとめています。 ## freee API連携を自社開発すべき条件と既製の連携で済ませる場面 ### 販売管理からの売上自動登録と複数事業者の横断集計なら自社開発 APIを使う開発に進む価値があるのは、次のどちらかが要件にある場合です。1つは、販売管理や受発注システムの確定データから、勘定科目・税区分・取引先まで決めた取引を毎日自動で登録し、入金の消し込みまでfreee上で回したい場合。もう1つは、会計事務所やグループ会社のように、複数の事業所の試算表や取引を1か所に集めたい場合です。後者はプライベートアプリの5事業所の上限にすぐ当たるため、パブリックアプリの申請と事業所ごとのトークン管理まで含めた設計が要ります。会計事務所側の使い方は[税理士が使う会計ソフトと連携方式の解説](https://www.issoh.co.jp/column/details/17057/)でも扱っています。 ### CSVインポートや自動登録ルールで足りる場面と開発会社へ相談する目安 月に数十件の取引を取り込むだけなら、APIを使う開発は過剰です。freee会計の取り込み機能と明細の自動登録ルールで足り、トークンの更新や上限の管理も要りません。勘定科目の決め方とルール設計は[会計ソフトの勘定科目と自動仕訳ルールの設計](https://www.issoh.co.jp/column/details/17987/)、freee以外のバックオフィスSaaSと比べている段階なら[バックオフィスSaaSの比較と連携の判断軸](https://www.issoh.co.jp/column/details/10661/)を先に読むと手戻りがありません。 一方、基幹システムとの双方向の連携、数万件規模の過去データの移行、複数事業所をまたぐ集計のように、認可の単位や1日の上限、失敗時の再実行まで設計する必要がある場合は、要件定義の段階から開発会社に入ってもらうと安全です。一創の[API開発・システム連携サービス](https://www.issoh.co.jp/service/system/api/)では、会計SaaSと社内システムの連携を、要件整理から運用まで受託しています。REST APIの連携全般の手順は[API連携の実装方法の記事](https://www.issoh.co.jp/tech/details/15351/)も参考になります。 ## freee APIの料金・個人利用・MCP連携でよくある質問 freee APIを使い始める実装者や担当者から出やすい質問に、公式ドキュメントの記載をもとに答えます。 ### freee APIは無料で使えますか？ 開発を始めるまでは費用がかかりません。freeeアカウントを持っていなければ無料の開発者向けアカウントを作れ、開発用テスト事業所も無料で作成できます。本番で使える機能と1日の呼び出し上限は、接続先の事業所が契約しているfreee会計のプランで決まるので、費用として見るべきはAPIではなくそのプランの料金です。総勘定元帳APIのようにプランが足りないと呼べないものもあり、その場合は`freee_plan_limit`のエラーが返ります。 ### 個人事業主でもfreee APIを使えますか？ 使えます。個人向けのfreee会計を契約していれば、法人と同じ手順でアプリを作り、自分の事業所を認可できます。1日の上限は法人エンタープライズとアドバンス以外のプランと同じ3,000回で、個人の記帳を自動化する用途には十分な回数です。自分の事業所だけで使うなら、アプリはプライベートで作れば審査も要りません。 ### freee APIとマネーフォワード APIの違いは何ですか？ 大きな違いは認証と事業所の指定方法です。freeeはOAuth 2.0だけで、認可時に選んだ事業所のIDをトークンと一緒に持つ方式。マネーフォワード クラウド会計APIはOAuth 2.0に加えてAPIキー認証があり、APIキーでは事業所番号を呼び出しごとに指定します。上限もfreeeは1日の回数、マネーフォワードは毎秒の回数で決まります。詳しくは[マネーフォワード APIの認証方式と仕訳登録の解説](https://www.issoh.co.jp/tech/details/19181/)を参照してください。 ### AIエージェントからfreeeを操作するfreee-mcpとAPIの関係は？ freeeは、AIエージェントから会計・人事労務・請求書などのAPIを操作するための公式MCPサーバー[freee-mcp](https://github.com/freee/freee-mcp)をGitHubで公開しています。中で呼んでいるのはこの記事で扱ったfreee APIなので、事業所の選択やプラン別の上限はそのまま当てはまると考えてください。利用者向けのChatGPTアプリとの違いは[freeeのChatGPTアプリとfreee-mcp連携の違い](https://www.issoh.co.jp/tech/details/11044/)で解説しています。 ### 取引が登録されたことを自社システムで即時に受け取れますか？ 2026年11月時点ではできません。[会計Webhookの概要](https://developer.freee.co.jp/reference/accounting/webhook)で通知の対象になっているのは、各種申請・経費精算・支払依頼の作成と更新だけで、取引や振替伝票は含まれていません。Webhook自体もβ版と明記されています。取引の変更を拾うには一覧APIを定期的に呼ぶことになるため、発生日の範囲を前回の取得以降に絞り、1日の上限を食わない間隔で回します。 ## 関連記事 - [マネーフォワード APIとは：クラウド会計API v3の認証2方式と仕訳登録・取得をPythonで実装する手順](https://www.issoh.co.jp/tech/details/19181/)：同じクラウド会計の連携をマネーフォワードで作る場合の実装 - [API連携の実装方法：REST・認証・エラー処理の手順をcurlとPythonのコード例で解説](https://www.issoh.co.jp/tech/details/15351/)：製品に依らないREST連携の基本手順 - [OAuthとは？OAuth 2.0の仕組み・認可フローと認証との違い、OAuth 2.1の変更点をわかりやすく解説](https://www.issoh.co.jp/tech/details/8369/)：認可コードフローとトークンの考え方 - [冪等性とは？読み方・意味からAPI・IaCでの担保方法まで実装者向けに解説](https://www.issoh.co.jp/tech/details/13382/)：取引の二重登録を防ぐ設計の土台 - [経理システムと会計システムの違い：業務範囲と仕訳の起点で分ける選定基準](https://www.issoh.co.jp/column/details/16461/)：どのシステムで仕訳を起こすかの整理 --- 出典: [freee APIとは：会計APIの認可・事業所IDと取引登録をPythonで実装する手順と上限]()（株式会社一創）