リファレンス

リファレンス

ここでは、freee Public APIで共通の仕様、項目をまとめています。一番下にプロダクト別のAPI概要や仕様に関するリンクがあります。

  • プロダクト共通
    • APIエンドポイント
    • 認証と認可、アクセストークン
    • データフォーマット
    • 後方性互換有の変更
    • エラーハンドリング
  • プロダクト別のAPI概要と仕様

APIエンドポイント

https://api.freee.co.jp/
  • httpsのみ有効

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

認証

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

アクセストークンやリフレッシュトークンの取得手順はアクセストークンを取得するを参照してください。

oauth2.0の遷移図

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=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の仕様を確認できます。アクセストークンを取得するとブラウザからのAPIコールもできるようになっています。
  • freee工数管理API概要
    • freee工数管理APIでできることを確認できます。
  • freee工数管理 APIリファレンス
    • freee工数管理APIの仕様を確認できます。