Salesforce からクラウド会計ソフト freee の API にアクセスする

皆さん、こんにちは！今回は、クラウド会計ソフトである [freee さんの API](https://developer.freee.co.jp/startguide) を Salesforce の外部サービス経由でフローから呼び出す方法をご紹介してみます。外部サービスを利用することで、Salesforceから他のサービスのAPIをノーコードで呼び出すことができるようになります。また、外部サービス自体もノーコードで設定でき、30分程度で完了するのでぜひ挑戦してみてください。

# 前提事項
- 今回は、freee さんが提供してくれている無料の開発者向けアカウントを利用します。[freee API スタートガイド](https://developer.freee.co.jp/startguide) の手順の中で、API連携に必要なアカウント、事業所、アプリケーションで取得できるので事前に完了しておいてください。
- また、Salesforce の検証環境についても、無料の Developer Edition に[サインアップ](https://developer.salesforce.com/signup)することで取得できます。

# 連携の大まかな流れ
Salesforce から freee のアプリケーションを介して事業所のデータにアクセスするには、Salesforce 上で(1)認証情報を登録し、(2)利用するAPIリソースを登録するという流れになります。そのためにそれぞれ以下の設定を追加します。

**(1) 認証情報を登録には...**
- 認証プロバイダ
- 指定ログイン情報(+ 外部ログイン情報 + プリンシパル + 権限セット)

**(2) 利用するAPIリソースを登録には...**
- 外部サービス

これらの設定は最初に一度作成しておけば、Salesforce の複数のノーコードツールやコードから繰り返し利用する事ができます。
この記事では、これらを作成する手順と設定の利用方法について順を追って紹介していきます。


# freee 連携の設定手順
### 1. 認証プロバイダを作成する

##### 1-1. 認証プロバイダの作成に必要な情報を取得
- 認証プロバイダを作成するためには、事前にfreee のアプリケーションから `コンシューマ鍵(Client ID)` と`コンシューマの秘密(Client Secret)`を取得します。
- これらの情報は、[開発アプリ一覧](https://app.secure.freee.co.jp/developers/applications)から `開発用テストアプリ > 基本情報`から取得できます。
<img width="480" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/26378/3520cced-735f-831e-a460-295a237931ff.png">

##### 1-2. 認証プロバイダーを作成
- 次に Salesforce にログインし、`設定 > ID > 認証プロバイダ > 新規` から以下の要領で作成、保存します。

| 項目|値|
|-----------:|:------------|
|プロバイダタイプ | Open ID Connect |
| 名前 | freee Auth Provider | 
| URL 接尾辞	| freee_Auth_Provider | 
| コンシューマ鍵 | <1-1 でコピーしたコンシューマ鍵(Client ID)> | 
| コンシューマの秘密 |	<1-1 でコピーしたコンシューマの秘密(Client Secret)> | 
| 承認エンドポイント URL | https://accounts.secure.freee.co.jp/public_api/authorize?prompt=select_company | 
| トークンエンドポイント URL | https://accounts.secure.freee.co.jp/public_api/token | 


##### 1-3. freee アプリケーションの設定を変更
- 認証プロバイダを作成すると、`コールバック URL` が生成されるのでコピーします。
<img width="480" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/26378/254d8c7c-2b38-bcef-2fb2-95271ae3a3e0.png">

再び freee の `開発用テストアプリ` を開き、`コールバックURL` に貼り付け下書き保存します。

<img width="480" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/26378/81de4332-ade5-b5aa-ccfb-fed60456da89.png">


さらに権限設定タブを開き、`[会計] 事業所` の `参照` にチェックを入れておきます。
<img width="480" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/26378/5c425bbe-a1bb-287a-a971-7e6e45355f1e.png">

:::note info
認証プロバイダの動作確認
それでは、ここまでの設定が正しく動作するか確認します。
認証プロバイダを開き、テスト専用初期化 URLをコピーします
<img width="320" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/26378/91cc9a1b-dd4b-80f6-de7a-6dde941ce02c.png">

そのアドレスをブラウザ開くとアプリの連携を確認するページが表示されるので、許可します。
<img width="320" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/26378/7d10f914-3645-fa20-6682-dbbe2b6ab1a9.png">

連携が成功するすると、このような XML ファイルが表示されれば成功です。
<img width="320" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/26378/7fb77b49-f55c-fe18-3799-c1631f5bf07b.png">
:::


### 2. 指定ログイン情報を作成
指定ログイン情報は、freee のAPIにアクセスする際の認証情報の管理を行います。指定ログイン情報を作成するには、外部ログイン情報とそれに紐づくプリンシパルを作成する必要があります。また作成した認証情報の利用にはプリシパルへのアクセス権限必要になりますので、ここでは順に対応していきます。

##### 2-1. 外部ログイン情報を作成
- `設定 > セキュリティ > 指定ログイン情報 > 外部ログイン情報 > 新規` から以下の要領で外部ログイン情報を作成します。

| 項目|値|
|-----------:|:------------|
| 表示ラベル | freee External Credential | 
| 名前 | freee_External_Credential | 
| 認証プロトコル | OAuth 2.0 | 
| 認証フロー種別 | ブラウザフロー | 
| 認証プロバイダ | freee Auth Provider | 



##### 2-2. プリンシパルを作成
- 作成した外部ログイン情報を開き、プリンシパルを以下の要領で作成します、

| 項目|値|
|-----------:|:------------|
| パラメータ名 | freee External Credential Principal | 
| ID 種別 | 指定ユーザ | 

- 作成したプリンシパルで認証を済ませておきます。
<img width="480" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/26378/236d418c-9381-0ea6-670f-a573801cae5a.png">

##### 2-3. 指定ログイン情報を作成
- `設定 > セキュリティ > 指定ログイン情報 > 指定ログイン情報 > 新規` から以下の要領で指定ログイン情報を作成します。

| 項目|値|
|-----------:|:------------|
|表示ラベル|freee Named Credential|
|名前|freee_Named_Credential|
|URL|https://api.freee.co.jp/|
|コールアウトに対応|ON|
|外部ログイン情報|freee External Credential|

<img width="480" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/26378/d45bdecf-c151-dd1c-e22e-f66b827bd35d.png">

##### 2-4. プリンシパルへのアクセス権を追加
- `設定 > ユーザ > 権限セット > 新規` から、先程作成したプリンシパルへのアクセス権を追加した新しい権限セットを作成します。
<img width="480" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/26378/e4c956f1-99d6-3dc2-3b62-315b0af44e4a.png">

- `設定 > ユーザ > ユーザ > [自分のユーザ] > 権限セットの割り当て > 割り当ての編集`から現在のユーザに割り当てておきましょう。

<img width="480" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/26378/504a8413-6f79-88bc-be69-c26d335003b6.png">


:::note info
指定ログイン情報の動作確認
ここまでの設定が正しく動作するか確認します。
開発者コンソールを開き、`Debug > Open Execute Anonymous Window` を起動します。
以下のコードを実行し、ログを確認しましょう。
```java
HttpRequest req = new HttpRequest();
req.setMethod('GET');
req.setEndpoint('callout:freee_Named_Credential/api/1/companies');

Http http = new Http();
HTTPResponse res = http.send(req);
System.debug(res.getBody());
```

ログの USER_DEBUG が以下の様に出力されていれば成功です。
<img width="320" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/26378/e74f2183-282f-1e3f-616b-2be624ce3558.png">

:::

### 3. 外部サービスを作成
- `設定 > インテグレーション > 外部サービス > 外部サービスを追加` からウィザードに従って外部サービスを作成します。
- freee では OAS3 のAPI仕様が公開されているで「API仕様から」を選択します。
<img width="480" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/26378/98e8752b-dee1-190d-e59a-5493703a5a19.png">

- 次に「登録の詳細を入力」画面では、以下の要領で設定を追加します。

| 項目|値|
|-----------:|:------------|
|外部サービス名|freeeExtenalService|
|サービススキーマ|完全な JSON|
|指定ログイン情報を選択|freee_Named_Credential|
|JSON|[こちら](https://raw.githubusercontent.com/freee/freee-api-schema/master/v2020_06_15/open-api-3/api-schema.json)のテキストをコピーして貼り付け|

<img width="480" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/26378/9de54a91-2538-2486-f609-341ab50acdb2.png">

- APIの仕様上送信されるメディアタイプの全てをSalesforceがサポートしていないので、対応付けを要求されます。今回の検証では以下の設定にしておきます。

<img width="480" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/26378/dd7a6d15-2c7f-473d-b153-3aff38e26212.png">

- 最後に、取り込むAPIを選択後、確認画面を経て設定は完了です。今回は、get_companies と get_company を選択しておきます。

<img width="480" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/26378/6b1ea024-3dbe-5ac5-3be0-a9c535b257fb.png">

# freee 連携の利用手順

- それでは、実際にフローから外部サービスを呼び出して動作を確認しましょう。今回は「アクション」要素を一つだけ持った、動作確認用のフローを作成しました。
<img width="480" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/26378/e6f06f36-7789-28ed-0f78-06eb84863ef5.png">

- アクションの設定内容は以下のとおりです。
<img width="480" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/26378/255e2516-18c4-e4ca-c92f-51d302b13356.png">

- 　`デバッグ` ボタンから起動して結果を確認します。以下の様に、コード200で事業所名が取得できていれば成功です！お疲れ様でした。

<img width="480" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/26378/d3876153-1f34-1401-ef43-ad3909a73414.png">