CData Software Blog

クラウド連携のCData Software の技術ブログです。

クラウド会計ソフト freee の API の使い方:Postman からアクセスする方法

f:id:sugimomoto:20210813143634p:plain

こんにちは。CData Software Japanリードエンジニアの杉本です。

今回は会計 freee の API の使い方、API開発・テスト便利ツール Postman からアクセスする方法を紹介したいと思います。

会計 freee とは

freee株式会社が提供する無料から使えるSaaSクラウド会計ソフトです。

www.freee.co.jp

f:id:sugimomoto:20210813143023p:plain

会計 freee では製品リリースの初期から API が提供されており、取引や請求書・見積書などのトランザクションデータ、勘定科目や部門などのマスタデータの取得・作成・更新といった幅広い機能をAPIを通じて実行できるようになっています。

developer.freee.co.jp

f:id:sugimomoto:20210813143030p:plain

また、freee アプリストアというサービスでfreee 含む各社が開発したAPI連携サービスを利用できるようになっているのも特徴的ですね。

app.secure.freee.co.jp

f:id:sugimomoto:20210813143037p:plain

今回はこの 会計 freee の APIの使い方、具体的には Postman を通じてOAuth 2.0 の認証・認可と実際のAPIリクエストを実行するまでを解説したいと思います。

Postman は予め以下のURLから取得しておいてください。

www.postman.com

なお、会計 freee ではAPI連携開発を行うための、開発用アカウント・テスト環境を提供しているので、こちらも予め取得・構成しておきましょう。

開始情報の入力 | freeeアプリストア

認証方法について

freee API は OAuth 2.0 の Authorization Code Grant でAPIの認証・認可を実施します。

developer.freee.co.jp

f:id:sugimomoto:20210813143045p:plain

認可URLを元に、freee へのログインおよび認可処理を実施し、RedirectURLから Authorization Code を取得、

f:id:sugimomoto:20210813143051p:plain

その後、Token Endpointを通じて、AccessTokenを取得するという流れです。

Authorization Endpoint・Token Endpoint は以下のとおりです。

https://accounts.secure.freee.co.jp/public_api/authorize
https://accounts.secure.freee.co.jp/public_api/token

認証URLはアプリ管理画面から入手できるので、わかりやすくてとてもありがたいですね。

f:id:sugimomoto:20210813143828p:plain

Access Token のリクエストは「application/x-www-form-urlencoded」で「grant_type=authorization_code」を指定し、ClientId・ClientSecret・RedirectUriをリクエスト方式です。

POST /public_api/token HTTP/1.1
Host: accounts.secure.freee.co.jp
Content-Type: application/x-www-form-urlencoded
Content-Length: 239

grant_type=authorization_code&client_id=235950d4807608588719d3b6229076ce32d171407f25f70d50908563391e151a&client_secret=98e21ce29873f1d1a60918d2b84f94c3ea1f864ca723073988310500d725a07e&code=XXXXXX&redirect_uri=http%3A%2F%2Flocalhost%3A33333

アクセス許可は予めアプリ側で定義して、その定義でのみ認可が可能な方式になっています。そのため、Authorization Code Grant で Scopeなどのリクエストは行いません。

f:id:sugimomoto:20210813143058p:plain

ここまでざっと freee の OAuth を説明してきましたが、今回はこの認証・認可のプロセスを Postman の Authorization 機能を通じて実施します。なので実際の手順は特に難しいことはありません。

f:id:sugimomoto:20210813143106p:plain

アプリの登録

それでは早速作業を始めましょう。

まず、freee のアプリ管理ページに移動して、新しくAPI連携用のアプリを登録します。すでに作成している場合はOKです。

以下のURLにアクセスして「+新規追加」をクリックします。

app.secure.freee.co.jp

f:id:sugimomoto:20210813143112p:plain

任意のアプリ名と概要を入力し、各規約の確認・同意を行った上で「作成」をクリックします。

f:id:sugimomoto:20210813143119p:plain

アプリを作成したらまずコールバックURLを変更します。

今回は前述の通り、Postman を使ってリクエストするので、Postman専用のコールバックURL「https://oauth.pstmn.io/v1/callback」を指定し、保存します。

f:id:sugimomoto:20210813143129p:plain

併せて作成したアプリの「Client ID」と「Client Secret」を控えておきましょう。

f:id:sugimomoto:20210813143151p:plain

基本情報の設定が完了したら、権限を追加します。

権限タブに移動し、リクエストしたいAPIの権限を付与しましょう。

f:id:sugimomoto:20210813143200p:plain

これで保存することで、アプリの準備は完了です。

Postman で Collection の登録

続いて Postman 側の準備を行います。

Postman ではGUIを使って手軽にAPIリクエストを作成できますが、予めOpen API(Swagger)などの定義が提供されていれば、APIリクエストの雛形の集まり・Collectionを自動生成できます。

freee APIAPI リファレンスのページからOpen APIスキーマが入手できるので、これを使うことでより簡単にAPI検証を進められます。

生成方法は簡単です。まず、以下のURLからOpen APIスキーマURLをコピーしておきます。

developer.freee.co.jp

f:id:sugimomoto:20210813143207p:plain

Postmanに移動して、「Collections」タブから「Import」をクリック

f:id:sugimomoto:20210813143213p:plain

「Link」タブにある「Enter a URL」の欄に先程コピーしたOpen API SchemaのURLを入力して「Continue」をクリックします。

f:id:sugimomoto:20210813143218p:plain

あとは「Import」をクリックするだけでOKです。

f:id:sugimomoto:20210813143224p:plain

これで、freee API の Collection が自動生成されました。

以下のように各種APIリクエストが予め登録されているのがわかりますね。

f:id:sugimomoto:20210813143229p:plain

Postman で OAuth 2.0 フローの実施・アクセストークンの取得

freee API の Collectionを作成したら、OAuth 2.0 による認証・認可を通じて freee API のアクセストークンを取得してみましょう。

先程登録したfreee API の Collection を選択し「Authorization」タブから「OAuth 2.0」を選択します。

f:id:sugimomoto:20210813143235p:plain

「Configure New Token」タブから freee の OAuth に必要な各種情報を入力します。ここで先程登録していたアプリのClient IdやClient Secretも併せて指定します。

プロパティ名 備考
Token Name 例)freee API
Grant Type Authorization Code
Callback URL https://oauth.pstmn.io/v1/callback Authorize using browser で実行します。
Auth URL https://accounts.secure.freee.co.jp/public_api/authorize
Access Token URL https://accounts.secure.freee.co.jp/public_api/token
Client ID 例)235950d4807608588719d3b6229076ce32d171407f25f70d50908563391e151a アプリ登録時に生成された Client IDを指定します。
Client Secret 例)98e21ce29873f1d1a60918d2b84f94c3ea1f864ca723073988310500d725a07e アプリ登録時に生成された Client Secret を指定します。
Client Authentication Send as Basic Auth header

f:id:sugimomoto:20210813143242p:plain

あとは「Get New Access Token」をクリックすることで、自動的にブラウザが立ち上がり、freee へのログインとアクセス権の確認・認可プロセスが実施できます。

f:id:sugimomoto:20210813143249p:plain

「許可する」をクリックすると、Authorization Code がPostmanのコールバックURLにリダイレクトされます。

f:id:sugimomoto:20210813143255p:plain

以下のように「Authentication Complete」が表示されれば、Access Tokenの取得が完了です。

f:id:sugimomoto:20210813143302p:plain

APIリクエストの実行

それでは取得したAccessTokenを使って、実際にAPIリクエストを実行してみましょう。

freee API ではほとんどのエンドポイントでアクセスする事業所のId(ComapnyId)が必要です。なので、まず事業所のIdを特定するリクエストを実行してみましょう。(ちなみにCompanyIdはTokenリクエストのレスポンスにも含まれます)

事業所は「GET /api/1/companies」のリクエストで取得できます。

https://developer.freee.co.jp/docs/accounting/reference#/Companies/get_companies

Postman では「事業所一覧の取得」を選んで「Send」を実行してみましょう。

以下のように事業所のIdが取得できます。

f:id:sugimomoto:20210813143308p:plain

この事業所のIdを使って、他のAPIも実行してみましょう。

例えば勘定科目一覧を取得する場合は「GET /api/1/account_items」を使います。

https://developer.freee.co.jp/docs/accounting/reference#/Account%20items/get_account_items

この時にURLクエリパラメータで「?company_id=XXXXXX」という形で先程取得した事業所Idを指定します。

あとは「Send」をクリックすると、勘定科目一覧が取得できます。

f:id:sugimomoto:20210813143315p:plain

おわりに

ざっくりとですが、freee APIの使い方を解説してみました。

Postman で API リクエストを試すと、自動的に各種プログラミング言語の Code snippet も生成してくれるのがありがたいですね。

f:id:sugimomoto:20210813144827p:plain

次回は CData Driver から freee API に接続する方法を紹介したいと思います。