【Googleスプレッドシート】MoneyForwardの家計データを連携!OAuth認証フロー

MoneyForwardで管理している家計データをGoogleスプレッドシートに自動で取り込めると、毎月の収支分析が格段に楽になります。しかし、そのためにはOAuth認証という仕組みを正しく理解し、アクセストークンを取得するフローを実装する必要があります。この記事では、MoneyForwardが提供するAPIを使ったOAuth 2.0の認可コードフローを、スプレッドシート上で動かす手順を詳しく解説します。このフローをマスターすれば、毎日の取引データをスプレッドシートに自動反映できるようになります。

MoneyForward APIとOAuth認証の仕組み

MoneyForwardは家計簿サービスで、APIを通じて取引データや資産情報を取得できます。OAuth 2.0はユーザーのパスワードを共有せずに、限定的なアクセス権を委任する認証方式です。MoneyForwardでは認可コードフロー(Authorization Code Grant)が推奨されており、以下の3つのフェーズで構成されます。まず認可コードを取得し、次にそのコードをアクセストークンとリフレッシュトークンに交換します。最後にアクセストークンを使ってAPIを呼び出します。アクセストークンには有効期限があるため、リフレッシュトークンを使って定期的に更新する必要があります。

スプレッドシートでこのフローを実装するには、Google Apps Scriptを使用します。Apps ScriptはUrlFetchAppクラスでHTTPリクエストを送信でき、スクリプトプロパティにトークンを保存できます。また、OAuth2ライブラリ(OAuth2 for Apps Script)を利用すると、トークンの管理が容易になりますが、本記事ではフローの理解のために生のHTTPリクエストを使った手順を解説します。

MoneyForwardのOAuth認証フローをスプレッドシートで実装する手順

1. MoneyForward Developerでアプリケーションを登録する

1. MoneyForward Developerサイトにアクセスする
   ブラウザでhttps://developer.moneyforward.com/ を開き、MoneyForwardのアカウントでログインします。
2. 新しいアプリケーションを作成する
   「My Applications」メニューから「New Application」をクリックし、アプリ名(例:Sheets連携)を入力します。リダイレクトURIには、後で使用するコールバックURLを登録します。テスト段階では https://script.google.com/macros/d/{スクリプトID}/usercallback のような形式になります。実際のスクリプトIDは後で確認します。
3. クライアントIDとクライアントシークレットを控える
   登録が完了すると、クライアントIDとクライアントシークレットが発行されます。これらは後でトークン交換に必要なので、安全な場所に保存します。

2. 認可コードを取得する

1. 認可エンドポイントのURLを組み立てる
   以下のパラメータを含むURLを生成します。
   https://moneyforward.com/oauth/authorize?response_type=code&client_id={クライアントID}&redirect_uri={リダイレクトURI}&scope=account+transactions
   scopeには必要な権限を指定します。最低限 account と transactions を含めます。
2. ユーザーに認可画面を表示する
   Apps Scriptで HtmlService を使って認可URLへのリンクを表示するか、ブラウザで直接開くように促します。ユーザーが認可すると、リダイレクトURIに認可コードが付与されて戻ってきます。
3. 認可コードを取得する
   リダイレクト先のURLパラメータ code の値を取得します。Apps Scriptでは e.parameter.code で受け取れます。

3. 認可コードをアクセストークンと交換する

1. トークンエンドポイントにPOSTリクエストを送信する
   エンドポイントは https://moneyforward.com/oauth/token です。以下のパラメータをx-www-form-urlencoded形式で送信します。
   grant_type=authorization_code&code={認可コード}&redirect_uri={リダイレクトURI}&client_id={クライアントID}&client_secret={クライアントシークレット}
2. レスポンスからトークンを抽出する
   成功するとJSONが返ります。中に access_token、refresh_token、expires_in が含まれます。これらをスクリプトプロパティに保存します。

4. アクセストークンを使ってデータを取得するApps Scriptコードを書く

1. スクリプトプロパティからトークンを読み出す
   ScriptProperties.getProperty('access_token') で取得します。
2. APIリクエストを送信する
   例えば取引データを取得するには、https://moneyforward.com/api/v1/transactions にAuthorizationヘッダー Bearer {access_token} を付けてGETリクエストを送信します。
3. レスポンスをパースしてシートに書き込む
   JSONを配列に変換し、sheet.getRange().setValues() でシートに展開します。

5. リフレッシュトークンを使ってアクセストークンを更新する

1. トークンエンドポイントにリフレッシュリクエストを送信する
   パラメータ grant_type=refresh_token&refresh_token={リフレッシュトークン}&client_id={クライアントID}&client_secret={クライアントシークレット} をPOSTします。
2. 新しいアクセストークンでスクリプトプロパティを更新する
   レスポンスに含まれる新しい access_token を保存します。必要に応じて refresh_token も更新します。

OAuth認証でよく起きるトラブルと対策

リダイレクトURIの不一致エラー

認可リクエスト時に指定したリダイレクトURIが、MoneyForward Developerで登録したURIと完全に一致しないとエラーになります。特に末尾のスラッシュや大文字小文字に注意します。また、Apps ScriptのコールバックURLはスクリプトのデプロイごとに変わるため、開発中は毎回URIを更新する必要があります。対策として、ローカルテスト用に複数のURIを登録しても構いません。

認可コードの有効期限切れ

認可コードは発行から数分で期限切れになります。コードを取得したらすぐにトークン交換のリクエストを送信してください。また、ユーザーが認可画面で承認した後、一定時間内にコードを受け取れなかった場合は再度認可を求めます。

スコープの不足によるAPIエラー

認可リクエストで指定したスコープが、実際に呼び出すAPIの権限をカバーしていないと、403エラーが返ります。MoneyForwardのAPIドキュメントで必要なスコープを確認し、scopeパラメータにスペース区切りで列挙します。一般的には account(口座情報)と transactions(取引データ)を含めます。

リフレッシュトークンの保存漏れ

初回のトークン交換時にリフレッシュトークンが返ってこない場合があります。MoneyForwardの設定によっては発行されないケースもあるため、その場合はリフレッシュ機構を別途実装する必要があります。また、リフレッシュトークンを紛失すると、ユーザーに再度認可を求めるしかありません。必ずスクリプトプロパティに確実に保存しましょう。

OAuth認証に必要なエンドポイントとパラメータ一覧

まとめ

この記事では、MoneyForwardのOAuth認証フローをスプレッドシートと連携する手順を解説しました。クライアントIDとシークレットを発行し、認可コードを取得してアクセストークンに交換する流れを実装すれば、定期的に家計データを自動取得できます。次は取得したデータをシートに整形する関数や、毎日実行するトリガーを設定することで、完全自動化を目指してみましょう。また、OAuth2ライブラリを利用するとトークン管理がさらに簡単になりますので、公式ドキュメントも参照してください。