対象プラン
|
法人プラン | ミニマム | ベーシック | プロフェッショナル | エンタープライズ |
個人プラン | スターター | スタンダード | プレミアム |
【注意】本ページはソフトウェア開発者向けのページです
freee APIへのアプリケーションの登録、その後のアクセストークン取得までの流れをご紹介します(OAuth2に対応)。簡単な検証方法・サンプルコードも記載しています。
APIを利用したアプリケーションの作成チュートリアルはこちらを、どのようなデータが送受信できるかが確認できるAPIドキュメントはこちらで公開しています。
freee API
目次
OAuth 2について
OAuth 2.0認証は、サードパーティアプリに対してhttpサービスへのアクセスを付与するフレームワークです。アクセストークンを用いて、保護されたリソースにアクセスできます。
freee APIへアプリケーションを登録する(未登録の場合)
未登録である場合は、freee APIを利用するアプリケーションをfreeeに登録します(無料)。登録によりアプリケーションのIDとSecretが発行され、必要な情報があればすべてのfreeeユーザーが当該アプリを利用できる状態となります。
【注意】このアプリケーションの登録はシステム開発者が行う作業であり、エンドユーザーが行う作業ではありません。開発者が発行したApp IDとSecret、認証用URLをエンドユーザーが用いることとなります。
freeeアプリストアの開発者ページへアクセスし、右上のログインをクリックします。
freeeアカウントをお持ちの方はメールアドレス、パスワードを入力してログインします。お持ちでない方はオレンジ枠「まだアカウントをお持ちでない方はこちら」からアカウント作成を行います。
所属している事業所が表示されるので、アプリを作成する事業所を選択します。
外部ユーザー(会計士など) として招待されている事業所ではアプリケーションを作成できませんので、内部メンバーとして所属する事業所を選択します。
freeeアプリストアの開発者ページ右上の表記が変わるので、「アプリ管理」をクリック、または「事業所アカウントを選択」をクリックします。
既に作成済みのアプリケーションがオレンジ枠部分に表示されます。新規作成する場合は赤枠「新規追加」をクリックします。
アプリ名、概要を入力して「作成」をクリックします。
(アプリを公開する場合のみ)アプリ名はアプリ認可画面、概要は検索結果画面に反映され、ユーザーから見ることができるようになります。
Client ID/Client Secretが発行、表示されます。ID/Secretは他のユーザーに知られることが無いよう管理して下さい。
コールバックURLは認可完了後の遷移先URLを指定します。初期値としてローカル用のものが自動入力されていますので、必要に応じて変更、保存します。
連携アプリのアクセストークンを取得する
アクセストークンの取得方法
アクセストークンを取得するためには、「Webアプリ認証用URL」(https://accounts.secure.freee.co.jp/public_api/authorize?client_id=${お客様のClient ID}&redirect_uri=${お客様のコールバックURI}&response_type=code)にて認証コード(Authorization code)を取得し、それを用いたhttpリクエストを送る必要があります。認証コードの有効期間は10分です。
※ 「Webアプリ認証用URL」へのアクセス時にログインする場合は、Googleアカウント等のsocial ログインではなく、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=${お客様のClient 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": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"token_type": "bearer",
"expires_in": 86400,
"refresh_token": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"scope": "read write"
}
refreshする例は下記のようになります。
curl -i -X POST \
-H "Content-Type:application/x-www-form-urlencoded" \
-d "grant_type=refresh_token" \
-d "client_id=${お客様のClient 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 ${取得したaccess token}" "https://api.freee.co.jp/api/1/xxx.json"
エンドユーザーの体験について
一般的には次のような流れとなり、ユーザーがfreeeへログインし「許可する」をクリックするだけで完了します。
- エンドユーザーが認証用URLに誘導される(その際、freeeへのログインが要求される)
- エンドユーザーが認証用URLにて許可の操作を行う
- 設定していたリダイレクトURIによって元のアプリに戻る(同時に認証コードを連携アプリへ渡す)
サンプルコード
※動作保証対象外
PHP
「Webアプリ認証用URL」からアクセストークンのエンドポイントへリダイレクトし、curlでリクエスト送信、レスポンスボディのアクセストークンを取得するまでのテストコードです。index.php及びcallback.phpから成ります。 APP_ID、CALLBACK_URL、SECRETについては、開発するアプリケーションの環境に合わせ、適宜置き換えて用いてください。
index.php
<?php
//連携アプリ情報
define('APP_ID', 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX');
define('CALLBACK_URL', 'http://localhost:XXXX/callback.php');
// 認証ページにリダイレクト
$params = array(
'client_id' => APP_ID,
'redirect_uri' => CALLBACK_URL,
'response_type' => 'code', );
header("Location: " . 'https://accounts.secure.freee.co.jp/public_api/authorize/'. '?' . http_build_query($params));
callback.php
<?php
//連携アプリ情報
define('APP_ID', 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX');
define('SECRET', 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX');
define('CALLBACK_URL', 'http://localhost:XXXX/callback.php');
//POSTデータ
$params = http_build_query(
array(
'grant_type' => 'authorization_code',
'client_id' => APP_ID,
'client_secret' => SECRET,
'code' => $_GET['code'], //認証用URLで取得したコード
'redirect_uri' => CALLBACK_URL, ));
$headers = array( "Content-type: application/json" );
//POSTリクエスト送信
$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, 'https://accounts.secure.freee.co.jp/public_api/token');
curl_setopt($curl, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($curl, CURLOPT_POSTFIELDS, $params);
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($curl, CURLOPT_HEADER, true);
//アクセストークンの取得
$response = curl_exec($curl);
$header_size = curl_getinfo($curl, CURLINFO_HEADER_SIZE);
$header = substr($response, 0, $header_size);
$body = substr($response, $header_size);
$result = json_decode($body, true);
$access_token = $result['access_token'];
print_r($access_token); //テスト用に表示
VBA
取得した認証コードを用いてVBAでリクエスト送信、レスポンスボディのアクセストークンを取得するまでのテストコードです。 APP_ID、CALLBACK_URL、SECRET、AUTH_CODEについては、開発するアプリケーションの環境に合わせ、適宜置き換えて用いてください。
'URLエンコード用ファンクション
Public Function UrlEncode(mySource As Variant) As String
Dim objSC As Object
Set objSC = CreateObject("ScriptControl")
objSC.Language = "JScript"
UrlEncode = objSC.CodeObject.encodeURIComponent(mySource)
Set objSC = Nothing
End Function
----------------------------------------------------------
'連携アプリ情報
Dim APP_ID: APP_ID = "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
Dim SECRET: SECRET = "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
Dim CALLBACK_URL: CALLBACK_URL = "XXXXXXXXXXXXXXXXXXXXXXXX"
Dim AUTH_CODE: AUTH_CODE = "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
'リクエスト先URLとリクエストボディ
Dim url_api: url_api = "https://accounts.secure.freee.co.jp/public_api/token"
Dim request_body: request_body = "grant_type=authorization_code" & "&client_id=" & APP_ID & "&client_secret=" & SECRET & "&code=" & AUTH_CODE & "&redirect_uri=" & UrlEncode(CALLBACK_URL)
'レスポンスとトークンを格納する変数を宣言
Dim js As String
Dim AccessToken As String
Dim RefreshToken As String
'tokenのPOSTリクエストを送信
With CreateObject("MSXML2.XMLHTTP")
.Open "POST", url_api, False
.setRequestHeader "Content-Type", "application/json"
.send request_body
js = .responseText
End With
'レスポンスからアクセストークン、リフレッシュトークンを取得
js = "(" & js & ")"
With CreateObject("ScriptControl")
.Language = "JScript"
AccessToken = .CodeObject.eval(js).access_token
RefreshToken = .CodeObject.eval(js).refresh_token
End With
Google Apps Script(GAS)
GASでAPI認証からアクセストークンの取得するまでのテストコードです。 APP_ID、SECRET、CALLBACK_URLについては、開発するアプリケーションの環境に合わせ、適宜置き換えて用いてください。 ※freeeにアプリ登録をする際のCALLBACK_URLには「https://script.google.com/macros/d/{スクリプト ID}/usercallback」を用いてください ※OAuth2認証用に外部のライブラリを参照しています
/*
***********************************************************************************
参照ライブラリ
title |OAuth2
project_key |1B7FSrk5Zi6L1rSxxTDgDEUsPzlukDsi4KGuTMorsTQHhGBzBkMun4iDF
***********************************************************************************
*/
//連携アプリ情報(Googleスプレッドシートサンプルファイル)
var APP_ID = "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";
var SECRET = "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";
// 認証のエンドポイントとなるダイアログ
function alertAuth() {
var service = getService();
var authorizationUrl = service.getAuthorizationUrl();
var template = HtmlService.createTemplate('認証. ');
template.authorizationUrl = authorizationUrl;
var page = template.evaluate();
SpreadsheetApp.getUi().showModalDialog(page, "認証が必要です");
}
//freeeAPIのサービスを取得
function getService() {
return OAuth2.createService('freee')
.setAuthorizationBaseUrl('https://accounts.secure.freee.co.jp/public_api/authorize')
.setTokenUrl('https://accounts.secure.freee.co.jp/public_api/token')
.setClientId(APP_ID)
.setClientSecret(SECRET)
.setCallbackFunction('authCallback')
.setPropertyStore(PropertiesService.getUserProperties())
}
//認証コールバック(アクセストークンの取得)
function authCallback(request) {
var service = getService();
var isAuthorized = service.handleCallback(request);
var access_token = service.getAccessToken();
if (isAuthorized) {
return HtmlService.createHtmlOutput('認証に成功しました。タブを閉じてください。');
} else {
return HtmlService.createHtmlOutput('認証に失敗しました。タブを閉じてください。');
}
}