会計サービスなどを提供するSaaSサービス 「freee」 。
REST APIが提供されていますが、アカウントがない・利用したことがない技術者が開発を始めようとすると、どこから手を付ければよいか、ちょっと戸惑うところがあります。
また、会計システムという特徴から、ユーザーのデータを気軽に触ることは難しく、開発用のテストデータを準備する必要があります。
ここでは、freeeのAPIを利用した開発を行おうとしている技術者が、一直線に
- freeeの開発用アカウントを無料で開設
- テスト用のデータ投入
- oAuth2.0 を利用したアクセストークンの取得
するまでの手順をかいつまんでまとめてみました。
freee API とは
- 会計や労務管理を提供するSaaSサービス「freee」の各機能を利用できるREST API
- 「会計freee」と「労務管理freee」の2つのサービス用APIを提供
- 認証はoAuth2.0を利用
- 「freee Develoepers Community」 に、各種リファレンス情報がある
アカウント作成と最初のAPIコール
まず最初にfreeeのアカウントを作成する。
メアド＋パスワードで新規登録するか、GoogleやFacebookなどでアカウントを作成する。
開発用のアカウント作成だけなら料金はかからない。
連携するアカウントを選択
事業形態を選ぶ。何でも良いようなので、「個人事業主」を選んで見る
事業形態を選択する
freeeのプラン選択画面に移動する。「お試しアカウント作成」という選択肢が下部にあるため、これを選択。「お試しプランを開始しました」という表示が出て、お試しができる。
スタータープランのお試し、という形で会計freeeの操作画面が表示される。
画面上部の「freeeアプリストア」をクリック
アプリストアから開発者ページをクリック
「開発者用テスト環境の作成」をクリック
ここで任意のシナリオを選ぶ。
ここでは事業所形態は「個人事業主」、プランの選択は「スターター」を選びました。
「開発用テスト環境の作成」をクリック。
「テスト環境の作成を開始しました」というメッセージが表示されるため、暫く待つ。
しばらくすると、開発用テスト環境が作成されたというメールが届く
アクセスして、作成したテスト用環境を開く
「利用サービス」から「会計freee」を選ぶ
会計freeeの管理画面に、テスト用に入力された出入金のデータが登録されていることがわかる。残高が全部リアルな金額で、口座に入っていたら良いのになあ。
ここまでで、freee の開発用アカウント、およびテスト用データの投入が完了しました。
開発者用アプリを作る
次に、開発者用アプリを設定し、REST API経由でデータをやり取りするための準備を行います。
開発者ページ (https://app.secure.freee.co.jp/developers) に移動して、「いますぐアプリを作成」をクリックする
「新しいアプリ」の作成画面に移動する。
名前と説明を適当に決めて、利用規約チェック後、「作成」ボタンをクリック
事業所アカウント選択画面から、アプリと紐付けたい事業所を選択。今回は「開発用テスト環境」を選択。
指定した名称でアプリが作成される。
ページ内にある「Webアプリ認証用URL」をコピーして、ブラウザでアクセスする。
oAuth2.0の認可コードを払い出すための認証ページが表示される。
「許可する」をクリックして、認可コードが表示されればOK。アプリは正常に動作しています。これで、freee APIを利用したアプリ開発の準備が整いました。
oAuth を利用したトークン取得
トークンを取得するために必要な情報
freeeの認証用エンドポイントを叩く際、
- client_id
- client_secret
- コールバックURL
- grant_type
の4つの情報が必須となる。
アプリ側で準備しているコールバックURLと、freeeのアプリ管理画面のコールバックURLは、必ず一致している必要がある。
例として、コールバックURLが
だった場合、freeeのアプリ管理画面上でも
と入力・保存しなければならない。
freeeのアプリ管理画面から、コールバックURLを設定する
freee の 開発者向けドキュメントを参考に、oAuthを利用したトークンを取得する
スタートガイド
https://app.secure.freee.co.jp/developers/tutorials
実装はphp。
仕様は以下の通り。
- index.phpにclient_id を記述。freeeのoAuth認証を叩き、認可コードを取得後、コールバックURL(callback.php)に定義されたページに移動。
- 取得した認可コード、client_id、client_secretをfreee の認証エンドポイントにPOSTし、トークンが含まれたJSONを取得する
- 取得したJSONを表示する
サンプルコードは、oAuth2.0の認可コード認証フローを想定して記述しました。
index.php
<?php
define('APP_ID', '取得したclient_idを記述');
define('CALLBACK_URL', '設定したコールバックURLを記述');
$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));
index.php にアクセスすると、freeeの認証を通じて、oAuthの認可コードを取得し、GETパラメータに付与する形でコールバックURLに戻る。GETパラメータを取得し、コールバック用のコードに渡し、トークン類を取得する。
callback.php
<?php
//アプリの各種情報を定義
define('APP_ID', '取得したclient_idを記述');
define('SECRET', '取得したsecret keyを記述');
define('CALLBACK_URL', '設定したコールバックURLを記述');
//パラメータをJSON形式でPOST
$params = array(
'grant_type' => 'authorization_code',
'client_id' => APP_ID,
'client_secret' => SECRET,
'code' => $_GET['code'],
'redirect_uri' => CALLBACK_URL, );
$headers = array( "Content-Type: application/json" );
$json = json_encode($params);
//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, $json);
curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
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);
//取得したトークン類を表示
var_dump($result);
index.phpにアクセス=>認可コード取得=>oAuth認証を経て、freee APIを利用するためのトークンデータが取得できました。
参照情報
freee のAPIに関するリファレンス
https://developer.freee.co.jp/
https://app.secure.freee.co.jp/developers/tutorials
oAuth認証に関するリファレンス
https://qiita.com/TakahikoKawasaki/items/63ed4a9d8d6e5109e401
https://qiita.com/TakahikoKawasaki/items/8567c80528da43c7e844
https://qiita.com/naoya_matsuda/items/6033b33d8582e0e9a096
免責事項など
この手順は2019年8月時点の情報を元にまとめました。SaaSサービスの性質上、UXや準備手順は予告なる変わるかもしれません。
この記事は個人的に情報を再整理してまとめたものとなります。
開発・操作の際は、各種公式ドキュメントをご確認いただければ幸いです。