freee APIドキュメント

ここでは、freee Public APIで共通の仕様、項目をまとめています。

APIエンドポイント

https://api.freee.co.jp/

(httpsのみ)

会計や人事労務など、プロダクトによってpathが異なります。詳細は各プロダクトのAPIリファレンスを参照してください。


認証

OAuth 2.0を使用します。この仕組みにより、アプリケーション利用者はfreeeのIDとパスワードをアプリケーションに教えることなくログイン、アプリケーションを利用することができます。

  • Authorization Code Flow (Webアプリ向け)
  • Implicit Flow (Mobileアプリ向け)
Authorization Code Flowでのアクセストークン取得

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にブラウザをリダイレクトします。この際にクエリパラメータとして認可コードの値が渡されれます。

アクセストークンのリフレッシュ

認証時に得たリフレッシュトークンを使ってアクセストークンの期限をリフレッシュして新規に発行することが出来ます。 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,破棄していないか
      • 前のアクセストークンが有効な間にリフレッシュトークンを利用して新しいアクセストークンを取得する必要があります

アクセストークン、リフレッシュトークンの有効期限はトークンの有効期限についてを参照してください。


アクセストークンの破棄

access_tokenを使って、tokenおよびrefresh_tokenを破棄することができます。 token=access_tokenで/oauth/revokeにアクセスすると破棄されます。また、token_type_hintでaccess_tokenのいずれかを指定できます。Content-Type:application/x-www-form-urlencodedを指定し、リクエストヘッダーにAuthorization:Bearer ${ACCESS_TOKEN}を入れる必要があります。

e.g.)

POST: https://accounts.secure.freee.co.jp/public_api/revoke
params: token=ACCESS_TOKEN
または
params: token=ACCESS_TOKEN&token_type_hint=access_token

curlでリクエストを送る場合は以下のようにします。

curl -i -X POST -H "Content-Type:application/x-www-form-urlencoded" -H "Authorization:Bearer ${ACCESS_TOKEN}" "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の場合、以下も併せて参照してください。


以下も併せて参照してください

  • 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コールもできるようになっています。