会計サービスなどを提供する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や準備手順は予告なる変わるかもしれません。

この記事は個人的に情報を再整理してまとめたものとなります。
開発・操作の際は、各種公式ドキュメントをご確認いただければ幸いです。