ここでは、freee Public APIで共通の仕様、項目をまとめています。一番下にプロダクト別のAPI概要や仕様に関するリンクがあります。
- プロダクト共通
- APIエンドポイント
- 認証と認可、アクセストークン
- データフォーマット
- 後方性互換有の変更
- エラーハンドリング
- プロダクト別のAPI概要と仕様
APIエンドポイント
https://api.freee.co.jp/
- httpsのみ有効
会計や人事労務など、プロダクトによってpathが異なります。詳細は各プロダクトのAPIリファレンスを参照してください。
認証
OAuth 2.0を使用します。この仕組みにより、アプリケーション利用者はfreeeのIDとパスワードをアプリケーションに教えることなくログイン、アプリケーションを利用することができます。
- Authorization Code Flow (Webアプリ向け)
- Implicit Flow (Mobileアプリ向け)

freee APIの認可エンドポイントとトークンエンドポイント
https://accounts.secure.freee.co.jp/
- Authorize page, 認可リクエスト画面、認可ページ :
- https://accounts.secure.freee.co.jp/public_api/authorize
- freeeの認可サーバがfreeeユーザの確認の後に認可コードの発行を行います。リソースオーナー(freee user)がリソース(freeeのデータ)へのアクセス権に同意すると、同意の証(”freee userのデータを利用したいアプリ”がfreee userのデータにアクセスすることへの同意)として認可コードが”freee userのデータを利用したいアプリ”の開発者が指定したリダイレクトURLに送られます
- ”freeeユーザのデータを利用したいアプリ”は、次のステップで認可コードを利用してアクセストークンを取得します
- Token endpoint, トークンエンドポイント :
- https://accounts.secure.freee.co.jp/public_api/token
- 認可コードを受け取ったAPIクライアントである”freee userのデータを利用したいアプリ”が必要なパラメータを指定してfreeeのトークンエンドポイントにリクエストを投げるとアクセストークンを取得できます。
- アクセストークンにより、freee利用者のid, passwordがなくても利用者の変わりに必要なデータに許可された権限でアクセス可能となります。
- redirect uri/callback url:
- APIクライアントが提供し、認可サーバーから認可コードを受け取るために利用します。設定はfreeeアプリストアのアプリ管理からコールバックURLに値を入れて行います。認可サーバーはリソースオーナーの権限移譲の同意が行われると、ステータスコード302のレスポンスを返してリダイレクトURIにブラウザをリダイレクトします。この際にクエリパラメータとして認可コードの値が渡されれます。
アクセストークンのリフレッシュ
認証時に得たリフレッシュトークンを使ってアクセストークンの期限をリフレッシュして新規に発行することが出来ます。1つのリフレッシュトークンを利用して2度アクセストークンを取得することはできません。アクセストークン取得毎にリフレッシュトークンを保管し、アクセストークンを取得してください。
- grant_type=refresh_token でトークンエンドポイントの/public_api/token にアクセスすればリフレッシュされます。
- リクエスト時にはContent-Type:application/x-www-form-urlencodedを指定し、リクエストヘッダーにAuthorization:Bearer ${ACCESS_TOKEN}を入れる必要があります。
e.g.)
POST: https://accounts.secure.freee.co.jp/public_api/token params: grant_type=refresh_token&client_id=UID&client_secret=SECRET&refresh_token=REFRESH_TOKEN
詳細はrefresh_tokenを参照下さい。
- リフレッシュトークンを利用してアクセストークンを再発行しようとしても、401エラーとなる場合、以下を確認してください
- 同じリフレッシュトークンを利用して2回リフレッシュしていないか(retryなどで)
- リフレッシュ前のアクセストークンをrevoke,破棄していないか
- 前のアクセストークンが有効な間にリフレッシュトークンを利用して新しいアクセストークンを取得する必要があります
アクセストークン、リフレッシュトークンの有効期限はトークンの有効期限についてを参照してください。
アクセストークンの破棄
認証時に得たtokenおよびrefresh_tokenを利用してアクセストークンを破棄することができます。
- token=access_tokenまたはrefresh_tokenで/oauth/revokeにアクセスすると破棄できます。
- リクエストヘッダーにContent-Type:application/x-www-form-urlencodedを指定する必要があります。
e.g.)
POST: https://accounts.secure.freee.co.jp/public_api/revoke params: token=ACCESS_TOKEN または params: token=REFRESH_TOKEN
curlでリクエストを送る場合は以下のようにします。
curl -i -X POST -H "Content-Type:application/x-www-form-urlencoded" "https://accounts.secure.freee.co.jp/public_api/revoke?token=${ACCESS_TOKEN}"
認証認可におけるAPIからのエラーレスポンスについて
freeeではRFCに準拠してOAuth2.0の実装をしています。以下の資料のケースに応じた”エラーレスポンス”の項を参照してください。
データフォーマット
リクエスト、レスポンスともにJSON形式をサポートしていますが、詳細はAPIリファレンス内のContent-type(application/jsonなど)を確認してください。一部multipart/form-dataのみに対応しているエンドポイントがあります。
リクエスト時はリクエストヘッダーに以下のようにContent-Typeを正しく入れてください
Content-Type: application/json
後方互換性ありの変更
freeeでは、APIを改善していくために以下のような変更は後方互換性ありとして通知なく変更を入れることがあります。アプリケーション実装者は以下を踏まえて開発を行ってください。
- 新しいAPIリソース・エンドポイントの追加
- 既存のAPIに対して必須ではない新しいリクエストパラメータの追加
- 既存のAPIレスポンスに対する新しいプロパティの追加
- 既存のAPIレスポンスに対するプロパティの順番の入れ変え
- keyとなっているidやcodeの長さの変更(長くする)
エラーハンドリング
各プロダクトのAPIリファレンスを参照してください。
会計APIの場合、以下も併せて参照してください。
プロダクト別のAPI概要と詳細仕様情報
- freeeの基本的な使い方
- freee会計を中心に、基本的な使い方や活用方法を学べるコンテンツのリンク集です。freeeについて知りたい方は、こちらをご覧ください。
- freee APIスタートガイド
- 最初のAPIコールに必要な環境準備とセットアップ、ブラウザでのAPIコールの方法などについて触れています。
- freee会計 API概要
- freee会計 APIでできることを確認できます。事業所や取引、勘定科目、取引先の情報から経費精算申請の下書きの作成や更新について触れています。
- freee会計 APIリファレンス
- freee会計 APIの仕様を確認できます。アクセストークンを取得するとブラウザからのAPIコールもできるようになっています。
- freee人事労務 API概要
- freee人事労務 APIでできることを確認できます。従業員一覧、日時勤怠、月次勤怠からタイムレコーダーの登録や取得について触れています。
- freee人事労務 APIリファレンス
- freee人事労務 APIの仕様を確認できます。アクセストークンを取得するとブラウザからのAPIコールもできるようになっています。
- freeeスマート受発注API概要
- freeeスマート受発注 APIでできることを確認できます。
- freee スマート受発注 APIリファレンス
- freee スマート受発注 APIの仕様を確認できます。
- freeeプロジェクト管理API概要
- APIでできることを確認できます。
- freeeプロジェクト管理 APIリファレンス
- freeeプロジェクト管理 APIの仕様を確認できます。
- freeeアプリストアAPIリファレンス
- アプリストアの決済機能を利用して有料アプリ販売を行う際に利用するAPIの仕様を確認できます