こんにちは。CData Software Japanリードエンジニアの杉本です。
今回は会計 freee の API の使い方、API開発・テスト便利ツール Postman からアクセスする方法を紹介したいと思います。
会計 freee とは
freee株式会社が提供する無料から使えるSaaS型クラウド会計ソフトです。
会計 freee では製品リリースの初期から API が提供されており、取引や請求書・見積書などのトランザクションデータ、勘定科目や部門などのマスタデータの取得・作成・更新といった幅広い機能をAPIを通じて実行できるようになっています。
また、freee アプリストアというサービスでfreee 含む各社が開発したAPI連携サービスを利用できるようになっているのも特徴的ですね。
今回はこの 会計 freee の APIの使い方、具体的には Postman を通じてOAuth 2.0 の認証・認可と実際のAPIリクエストを実行するまでを解説したいと思います。
Postman は予め以下のURLから取得しておいてください。
なお、会計 freee ではAPI連携開発を行うための、開発用アカウント・テスト環境を提供しているので、こちらも予め取得・構成しておきましょう。
認証方法について
freee API は OAuth 2.0 の Authorization Code Grant でAPIの認証・認可を実施します。
認可URLを元に、freee へのログインおよび認可処理を実施し、RedirectURLから Authorization Code を取得、
その後、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はアプリ管理画面から入手できるので、わかりやすくてとてもありがたいですね。
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などのリクエストは行いません。
ここまでざっと freee の OAuth を説明してきましたが、今回はこの認証・認可のプロセスを Postman の Authorization 機能を通じて実施します。なので実際の手順は特に難しいことはありません。
アプリの登録
それでは早速作業を始めましょう。
まず、freee のアプリ管理ページに移動して、新しくAPI連携用のアプリを登録します。すでに作成している場合はOKです。
以下のURLにアクセスして「＋新規追加」をクリックします。
任意のアプリ名と概要を入力し、各規約の確認・同意を行った上で「作成」をクリックします。
アプリを作成したらまずコールバックURLを変更します。
今回は前述の通り、Postman を使ってリクエストするので、Postman専用のコールバックURL「https://oauth.pstmn.io/v1/callback」を指定し、保存します。
併せて作成したアプリの「Client ID」と「Client Secret」を控えておきましょう。
基本情報の設定が完了したら、権限を追加します。
権限タブに移動し、リクエストしたいAPIの権限を付与しましょう。
これで保存することで、アプリの準備は完了です。
Postman で Collection の登録
続いて Postman 側の準備を行います。
Postman ではGUIを使って手軽にAPIリクエストを作成できますが、予めOpen API（Swagger）などの定義が提供されていれば、APIリクエストの雛形の集まり・Collectionを自動生成できます。
freee API は API リファレンスのページからOpen API のスキーマが入手できるので、これを使うことでより簡単にAPI検証を進められます。
生成方法は簡単です。まず、以下のURLからOpen API のスキーマURLをコピーしておきます。
Postmanに移動して、「Collections」タブから「Import」をクリック
「Link」タブにある「Enter a URL」の欄に先程コピーしたOpen API SchemaのURLを入力して「Continue」をクリックします。
あとは「Import」をクリックするだけでOKです。
これで、freee API の Collection が自動生成されました。
以下のように各種APIリクエストが予め登録されているのがわかりますね。
Postman で OAuth 2.0 フローの実施・アクセストークンの取得
freee API の Collectionを作成したら、OAuth 2.0 による認証・認可を通じて freee API のアクセストークンを取得してみましょう。
先程登録したfreee API の Collection を選択し「Authorization」タブから「OAuth 2.0」を選択します。
「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 |
あとは「Get New Access Token」をクリックすることで、自動的にブラウザが立ち上がり、freee へのログインとアクセス権の確認・認可プロセスが実施できます。
「許可する」をクリックすると、Authorization Code がPostmanのコールバックURLにリダイレクトされます。
以下のように「Authentication Complete」が表示されれば、Access Tokenの取得が完了です。
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が取得できます。
この事業所の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」をクリックすると、勘定科目一覧が取得できます。
おわりに
ざっくりとですが、freee APIの使い方を解説してみました。
Postman で API リクエストを試すと、自動的に各種プログラミング言語の Code snippet も生成してくれるのがありがたいですね。
次回は CData Driver から freee API に接続する方法を紹介したいと思います。
