【追記】
この記事のプログラムは2022年時点でのMFクラウド請求書API（v2）を使用しています。
2023年9月30日でv2の提供終了が発表されました。
連載記事を全てお読みいただいた後に、
以下の記事を参考にv3への移行をお願いいたします。

こんにちは！！

今回も、GASとマネーフォワードクラウドの連携をやっていきます！

これまでの記事『Google Apps Scriptでマネーフォワードクラウドの請求書を毎月自動発行』はこちら↓

1. API準備篇
2. 認証篇

今回は第3回ということで、実際にAPIを使って、
マネーフォワードクラウドの請求書データを取得する手順をまとめていきます！

楽しんでやっていきましょう＼(^^)／

APIドキュメントの確認

まずは、マネーフォワードクラウド請求書のAPIにはどのようなものがあるのか、
どのような操作がプログラムから可能なのか、
どのような記述をすればいいのかを確認する必要があります。

APIを使うとなれば、まずは公式から提供されているドキュメントやリファレンスの確認からです！

というわけで、マネーフォワードクラウド請求書APIのドキュメントはこちらからご覧ください。

これの凄いところが、「Authorize」ボタンをクリックして認証設定をすることで、
なんとドキュメントページから自分の環境へのAPI操作をお試しできるのです！！

試してみたい方は、ドキュメント記載の「OAuth認証手順」と「API実行手順」を読んでみてください。

但し、左側に「GET」と書いてあるもの（青系）は問題ないですが、
それ以外のものを試すと自分のマネーフォワードクラウド請求書に実際に反映されてしまうので、
実行しても問題ないかを事前によく確認してから実行してくださいね。

ちなみに今回は、請求書一覧を取得するAPI、「/api/v2/billings」の「GET」を使います！

GASでのコーディング

ここからは、GASに請求書データ取得用コードを書いていきます！

Googleドライブを開き、前回作成したGASを開いてください。

今回からはクラシックエディタでも新エディタでもどちらでも大丈夫です！

第1回（API準備篇）と第2回（認証篇）では必ずクラシックエディタを使うので、
こちらがまだの方は混乱しないよう注意してください！

私は今回は、実行ログを簡単に確認できる新エディタを使っていきます。

まず、実行用関数を下記の通り書いてください。

function start() {
  // 認証
  auth();

  // 請求書一覧取得処理を呼び出し結果文字列を取得してログに出力
  console.log(getInvoices_().getContentText());
}

こちらの関数を実行時に指定し実行します。

「auth()」は前回作成した認証用の関数です。

次に、上記で呼び出している請求書一覧取得関数「getInvoices_()」を下記の通り書いてください。

function getInvoices_() {
  return UrlFetchApp.fetch('https://invoice.moneyforward.com/api/v2/billings', {
    method: 'GET',
    muteHttpExceptions: true,
    headers: {
      accept: 'application/json',
      Authorization: 'Bearer ' + getService_().getAccessToken()
    }
  });
}

余談ですが、GASでない普通のJavaScriptに慣れ親しんでいる私のような方は、
「あれ？非同期通信なのにasync/awaitは要らないの？」と思われるかもしれませんが、
なんとこの「UrlFetchApp.fetch()」は同期通信をしてくれるためasync/awaitは不要なのです！
※今回必要のない知識ですが気になった方は「JavaScript 非同期通信」で検索！

GASで他サービスのAPIを呼び出すには「UrlFetchApp.fetch()」を使います。

私も後から調べて知ったのですが便利すぎて感動しましたｗ

第1引数は、先程調べたAPI「/api/v2/billings」の前に、
マネーフォワードのURL「https://invoice.moneyforward.com」を足したものです。

消費税の区分を軽減税率等より詳細に取得したい場合は、
この第1引数のURLの末尾に「?excise_type=enum」と追記しましょう（任意）。

これは「/api/v2/billings」のドキュメントに記載されており、
消費税区分の表示をbooleanにするかenumにするかを選択します（デフォルトはboolean）。
※詳細は公式サイトを参照

第2引数はオブジェクトの中にパラメーターを設定しています。詳細は下記の通り。

• method（必須）
  • 先程APIを調べた際に左側の四角いエリアに書いてあったもの
  • 今回は請求書一覧「取得」なので「GET」
• muteHttpExceptions（任意）
  • エラーとなった場合にエラーメッセージをログ出力して確認するため「true」
  • 「UrlFetchApp.fetch()」は結果がエラーとなるとプログラムごとエラー終了する
• headers（必須）※オブジェクトの中に設定
  • accept…結果をJSON形式で取得するため「application/json」
  • Authorization…認証情報（前回作成したサービスからアクセストークンを取得）
    • 必ず’Bearer ‘と文字列結合させること（半角スペースを忘れずに！）

書けたら「実行」ボタンをクリックしてログを確認してみましょう！

ログが大きすぎて表示しきれないかもしれませんが、
マネーフォワードクラウド請求書に登録されている請求書データが表示されているはずです！

ちなみに、請求書は新しい順に、一度に最大100件まで取得可能です。

補足：100件以上取得したい場合

ここからは補足です。

先程お伝えした通り、請求書一覧取得APIでは一度に最大100件まで取得可能です。

では、101件以上取得したい場合はどうすればいいのでしょうか？

実は、請求書一覧取得データのレスポンスの構造をAPIドキュメントでよく見ると、
「meta」というオブジェクトがあります。

このなかに「total_pages」と「current_page」があり、
この2つの値が同じであれば、現在のページが最後ということになり、
全件取得できているということになります。

つまり、「total_pages」と「current_page」が同じ値になるまでループさせればいいのです！

そして、第1引数のURLの末尾に「?page=2」のようにページ数を追加して実行し、
2ページ目、3ページ目…と順番に取得していきましょう！

取得した請求書一覧データを操作するには、「JSON.parse()」を使ってデータを変換します。

function start() {
  // 省略
  let page = 1;
  do {
    // respの中に請求書一覧データ（最大100件）が入っている
    (resp => {
      // ログ出力
      console.log(resp);

      // データを変換
      resp = JSON.parse(resp);

      // 現在のページがトータルページ数未満の場合はpageを次のページにする（それ以外の場合はnull）
      page = resp.meta.total_pages <= resp.meta.current_page ? null : page + 1;
    })(getInvoices_(page).getContentText());
  // pageがnullの場合はループを抜ける
  } while (page);
}

function getInvoices_(page) {
  return UrlFetchApp.fetch('https://invoice.moneyforward.com/api/v2/billings?page=' + page, {
    // 省略
  });
}

終わりに

長くなりましたが、最後までお読みいただきありがとうございました！

次回は、今回取得したデータを基に、新たな請求書を作成していきます！お楽しみに！！