（著者：ビットリバー株式会社 安藤 光昭）
こんにちは、 kintone エバンジェリストの安藤です。
このTipsは、クラウド会計ソフトの会計 freee と kintone のデータを連携させるカスタマイズについて紹介します。
業務システムとして構築した kintone のデータを会計に連携することで色々な可能性が広がります。
はじめに
会計 freee は kintone と同様に様々な機能が API として公開されています。
取引先や仕訳、請求データなどを外部から連携したり、B/S や P/L などの会計情報を取得して利用することが可能です。
参考: freee Developers Community 会計 API 概要
この記事では、様々な取引の基本となる顧客情報を kintone から会計 freee に連携させるカスタマイズをご紹介します。
会計 freee では「取引先」を登録することで売上や仕入の管理に利用できます
取引に取引先を登録すると、レポートにて取引先毎の推移を見たり、取引一覧で検索できるようになります。
このカスタマイズを応用すると、 kintone で管理する顧客の中で受注済顧客のみを会計 freee の取引先に連携させるなどの活用が可能となり、システム間の二重入力が解消されます。
この記事では、ステータスによらず顧客情報の保存時に取引先を作成するところまでを解説します。
ソースコードや画面は 2020 年 4 月時点の kintone、会計 freee に対応しています。
必要なもの
- kintone アカウント
- freee アカウント
準備
kintone アプリの作成
まず、連携元となる kintone の顧客情報アプリを作成します。
今回は「顧客名（正式名称）」「顧客名（略称）」「電話番号」の3つのフィールドで作成します。
フィールド名とフィールドコードの設定
| フィールド名 | フィールドタイプ | フィールドコード |
|---|---|---|
| 顧客名（正式名称） | 文字列（1行） | customerName |
| 顧客名（略称） | 文字列（1行） | customerNameShort |
| 電話番号 | リンク（電話番号） | phone |
アプリを作成したら、 URL をメモします。後述する freee の設定で利用します。
アプリの URL は「https://{subdomain}.cybozu.com/k/xxx/」の形式です。
会計 freee の開発用テスト事業所の作成
freee API スタートガイドを参考に開発用テスト事業所を作成してください。
freee の API 認証情報を取得する
次に、API 連携させるために freee 側の準備をしていきます。
1. 会計 freee にログインした後、「設定」→「データ設定」→「連携アプリ設定」を開きます。
2. freee アプリストアの開発者ページから「今すぐアプリを作成」をクリックします。
3. 「アプリ名」と「概要」を入力し、利用規約に同意したら「作成」をクリックします。
アプリ名や概要はご自由に決めていただくことができます。
4. 作成されたアプリの「コールバック URL」に連携したい kintone のアプリの URL を設定し、「Client ID」と「Client Secret」をメモしておきます。
kintone アプリの URL は末尾のスラッシュを忘れるとエラーになります。注意してください。
「https://{subdomain}.cybozu.com/k/xxx/」
※ Client ID と Client Secret は重要な情報です。絶対に外部に公開しないようにしてください。
5. 「下書き保存」をクリックし、情報を保存します。
「権限設定」は未設定のままでも動作しますが、適切な権限を割り振ってセキュリティの設計にご注意ください。
「公開設定」は作成した freee アプリをストアで公開する場合に利用するため、今回は設定しません。
JavaScriptカスタマイズの開発
freee 側の準備が終わったら、いよいよ kintone 側のカスタマイズをスタートします。
この記事では、次の2つのストーリーでカスタマイズを作成します。
- アプリの一覧画面を表示したタイミングで freee の認証情報と事業所情報を取得する
- レコードの保存時に freee の取引先を新規作成する
まずはカスタマイズの内容について説明します。
freee から認証トークンを取得する
OAuth2.0 を使って、会計 freee API から認証トークンを取得します。
この処理では「 freee の API 認証情報を取得する」の 5.で取得したClient IDと Client Secretを利用する必要があります。
これらの情報は漏洩すると API を自由に実行できてしまうため、 kintone のJavaScriptの開発においても慎重に扱う必要があります。
cybozu develper networkでは、認証情報の秘匿にプラグインを利用する方法を推奨しています。詳しくは以下の記事をご確認ください。
OAuth2.0 はサービス間で認証情報を連携する仕組みです。
kintone も外部からの連携のために OAuth2.0 の入口を用意しています（今回の記事とは逆パターン）。
OAuth2.0 の理解には、Webサービスに関する基礎的な知識が必要なため、詳細な説明は省略します。
当記事では、会計 freee API から認証トークンを取得するエンドポイントの呼び出し例を抜粋します。
上記のコードで取得したアクセストークンは、次のステップ以降で何度も利用します。
処理の流れは下記の通りです。2つのサービスを行き来する事で正しい認証手続きであることを担保しています。
- kintone から freee OAuth に認証情報を取得依頼を送る
- freee 側は認証のためのログイン画面を表示する
- ログインに成功した場合、コールバック URL に指定されたページにリダイレクトする
- リダイレクトされた kintone 側でアクセストークンを取得する
アクセストークンについて
上記のコードでは、取得したアクセストークンは画面が切り替わると無効化されてしまいます。
kintone のログイン中のみトークンが利用可能となるような仕組みを実装する必要があります。
この場合、アプリにトークン情報を保存して kintone の権限を設定することで管理者とログイン中のユーザ以外は参照不可にするなどの方法が考えられます。
今回の記事ではこの部分は省略いたします。
アクセストークンを使って事業所情報を取得する
アクセストークンの取得ができたら、次に事業所IDを取得します。
freee との API 連携ではリクエストに必ず「事業所ID」を指定する必要があります。
freee は1つのユーザIDで複数の事業所に所属が可能なため、どの事業所に API 連携するかを特定するために事業所IDを使います。
事業所IDは freee の管理画面では参照できないため API を使って取得する必要があります。
認証には、先ほど取得したアクセストークンを利用します。
freee の API は、取得する情報の種類毎にリクエスト先のエンドポイント（URL）が異なります。 事業所の取得では「/companies」に接続しています。
取得した事業所の情報はセッションストレージに格納しています。
事業所IDの取得ができたら、もう少しです！
顧客情報を使って freee の取引先を新規作成する
これまでのステップで取得したアクセストークンと事業所IDを使って、いよいよ freee に新規の取引先を作成していきます！
取引先の新規作成では「/partners」に接続します。
すでに freee に存在する取引先と同じ名称を使うとエラーになるのでこの点も注意が必要です。
カスタマイズの内容がおおよそわかったら kintone アプリに設定しましょう。
プラグイン化
kintone プラグイン開発手順にしたがって、kintone プラグインを作成します。
- https://js.cybozu.com/jquery/3.4.1/jquery.min.js
- これまでのステップで作成したカスタマイズ JavaScript のファイル
連携を試す
開発した連携機能がうまく動いているかを試してみましょう。
作成したアプリを公開して、アプリを開きます。
設定に問題がなければ、 freee のログイン画面にリダイレクトされます。
freee にログインすると、API 認証の画面が表示されます。
「許可する」をクリックすると kintone の画面に戻ります。
レコードを新規作成し、保存します。
連携に成功すると freee の取引先設定に新しい顧客情報が登録されている事がご確認できます。
まとめ
会計 freee の API を使うことで、比較的簡単に会計 freee に情報を登録することができました。
実際に作成された方はお判りかと思いますが freee のAPI では OAuth2.0 の仕組みを利用するため、セキュリティを確保した開発を行うことが最も難易度が高いポイントになります。
認証の問題をクリアできれば、あとは freee API には連携可能な情報が非常に多く用意されており、うまく使いこなす事で会計の手間を大幅に削減することが可能になります。
注意事項
この記事では、最も難しいポイントである OAuth2.0 の認証やトークンの管理についての記載を省略しています。
そのため、記事中に記載したコードをコピーしただけでは正しく動作しません。
文責
安藤 光昭（ kintone エバンジェリスト, kintone 開発のキントバ代表）
このTipsは、2020年4月時点の会計 freee 、 kintone で確認したものになります。
アクセストークンの保存について
「kintone のログイン中のみトークンが利用可能となるような仕組みを実装」とありますが、どうすれば実現できるかがわかりません。
別の記事などがあれば教えていただきたいです。
1つ目の案として、取得したトークンを利用者ごとにアプリに保存するという方法が考えられると思います。
ログイン中のユーザIDをキーにしてトークン保存用のアプリにデータを登録し、必要なタイミングで都度レコードを取得するという方法です。トークン保存用のアプリには、ユーザID以外の人は参照不可の権限を設定しておくことで管理者以外が対象レコードを閲覧することはできなくなります。
また、2つ目の案はセキュリティ上のリスクがあるためおすすめでありませんが、セッションストレージを使うという方法です。これはkintoneの機能ではなくブラウザ側にあるJavaScriptの機能ですので、「JavaScript セッションストレージ」で検索していただくとサンプルコードなどが見つかると思います。
参考になりました。
早急な対応で助かります。ありがとうございました。