freee APIへアプリケーションを登録する
freee APIを利用するアプリケーションを登録します。登録によりアプリケーションのIDとSecretが発行され、freeeユーザーが当該アプリを利用できる状態となります。
【注意】エンドユーザーは認証用URLを用いてアプリケーションの認証を行います。
開発者のアカウントでfreee会計にログイン後、アプリ一覧画面 にアクセスし、「+新しいアプリケーションを登録」をクリックします。
アプリケーション名、コールバックURIを入力し保存します。（入力内容は登録後にも編集できます）
※ ローカル環境でのテスト時には、コールバックURIに「urn:ietf:wg:oauth:2.0:oob」をご利用ください。
アプリケーションが登録され、IDとSecret、認証用URL（エンドユーザーが認証時にアクセスするURL）が表示されます。
※ 以後、アプリケーションの一覧から、登録したアプリケーション名をクリックすると、この画面を確認できます。
OAuth 2について
OAuth 2.0認証は、サードパーティアプリに対してhttpサービスへのアクセスを付与するフレームワークです。アクセストークンを用いて、保護されたリソースにアクセスできます。
連携アプリのアクセストークンを取得する
アクセストークンの取得方法
アクセストークンを取得するためには、「Webアプリ認証用URL」にて認可コード（Authorization code）を取得し、それを用いたhttpリクエストを送る必要があります。また、認可コードの有効期間は10分です。
※Webアプリ認証用URL
https://secure.freee.co.jp/oauth/authorize?client_id=アプリケーションID&redirect_uri=コールバックURL&response_type=code
※ 「Webアプリ認証用URL」へのアクセス時には、Googleアカウント等のソーシャルログインではなく、freeeアカウントのメールアドレス・パスワードでログインする必要があります。
redirect_uriに「urn:ietf:wg:oauth:2.0:oob」を指定している場合、「Webアプリ認証用URL」へそのままブラウザでアクセスしても認可コード（Authorization code）を確認できます。
「許可する」をクリックすると、認可コードが表示されます。（有効期間：10分）
※ テスト用に画面に表示しています。本来はリダイレクトしてリダイレクト先に認可コードを渡すため、本番環境ではこのような表示は不要です
コンソール上からcurlコマンドを使ってアクセストークンを取得する例は下記のようになります。
curl -i -X POST \ -H "Content-Type:application/x-www-form-urlencoded" \ -d "grant_type=authorization_code" \ -d "client_id=お客様のApp ID" \ -d "client_secret=お客様のSecret" \ -d "code=先ほどのauthorization code" \ -d "redirect_uri=連携アプリのコールバックURI" \ 'https://accounts.secure.freee.co.jp/public_api/token'
成功すると、レスポンスとして 下記のようにアクセストークン、リフレッシュトークンが得られます。有効期限は、アクセストークンについては24時間、リフレッシュトークンでは無期限となっています。使用する際は必要に応じてrefresh、revokeしてください。
{
"access_token": "アクセストークンの文字列",
"token_type": "bearer",
"expires_in": 86400,
"refresh_token": "リフレッシュトークンの文字列",
"scope": "read write"
}
refreshする例は下記のようになります。
curl -i -X POST \ -H "Content-Type:application/x-www-form-urlencoded" \ -d "grant_type=refresh_token" \ -d "client_id=お客様のApp ID" \ -d "client_secret=お客様のSecret" \ -d "refresh_token=前回取得したrefresh_token" \ 'https://accounts.secure.freee.co.jp/public_api/token'
それぞれのAPIは、取得したaccess tokenを添えて利用したいAPIへアクセスすることで利用できます。
例えば、Bearer Headerに添付してcurlコマンドを実行する例は下記のようになります。
curl -H "Authorization: Bearer 取得したアクセストークンの文字列" "https://api.freee.co.jp/api/1/xxx"
※ アクセストークンを用いたGET・POST等のリクエスト送信の詳細については、こちらのページで取り扱います。
エンドユーザーのアプリ利用手順
一般的には次のような流れとなり、ユーザーがfreeeへログインし「許可する」をクリックするだけで完了します。
- エンドユーザーが認証用URLに誘導される（その際、freeeへのログインが要求される）
- エンドユーザーが認証用URLにて許可の操作を行う
- 設定していたリダイレクトURIによって元のアプリに戻る（%9