Home » リファレンス

リファレンス

ここでは、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概要と詳細仕様情報