APIドキュメント

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

APIエンドポイント

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

(httpsのみ)


認証

OAuth 2.0を使用します。

  • 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
    • 認可コードの発行を行います。リソースオーナーがリソースへのアクセス権に同意すると同意の証として認可コードがリダイレクトエンドポイント(リダイレクトURI)に送ります
  • Token endpoint, トークンエンドポイント :
  • redirect uri/callback url:
    • APIクライアントが提供し、認可サーバーから認可コードを受け取るために利用します。設定はfreeeアプリストアのアプリ管理からコールバックURLに値を入れて行います。認可サーバーはリソースオーナーの権限移譲の同意が行われると、ステータスコード302のレスポンスを返してリダイレクトURIにブラウザをリダイレクトします。この際にクエリパラメータとして認可コードの値が渡されれます。

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

認証時に得たrefresh_token を使ってtoken の期限をリフレッシュして新規に発行することが出来ます。 grant_type=refresh_token で/oauth/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を参照下さい。

 


アクセストークンの破棄

認証時に得たaccess_tokenまたはrefresh_tokenを使って、tokenを破棄することができます。 token=access_tokenまたはtoken=refresh_tokenで/oauth/revokeにアクセスすると破棄されます。token_type_hintでaccess_tokenまたはrefresh_tokenのいずれかを指定できます。

e.g.)

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

詳細はrefresh_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の長さの変更(長くする)

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

  • freee APIスタートガイド
    • 最初のAPIコールに必要な環境準備とセットアップ、ブラウザでのAPIコールの方法などについて触れています。
  • 会計freee API概要
    • 会計freee APIでできることを確認できます。事業所や取引、勘定科目、取引先の情報から経費精算申請の下書きの作成や更新について触れています。
  • 会計freee APIリファレンス
    • 会計freee APIの仕様を確認できます。アクセストークンを取得するとブラウザからのAPIコールもできるようになっています。
  • 人事労務freee API概要
    • 人事労務freee APIでできることを確認できます。従業員一覧、日時勤怠、月次勤怠からタイムレコーダーの登録や取得について触れています。
  • 人事労務freee APIリファレンス
    • 人事労務freee APIの仕様を確認できます。アクセストークンを取得するとブラウザからのAPIコールもできるようになっています。