マネーフォワードクラウド請求書APIによる請求書一覧のデータを読み取ってみよう！

photo credit: shixart1985 Closeup of reading glasses on book. via photopin (license)

みなさん、こんにちは！
タカハシ(@ntakahashi0505)です。

GASによるマネーフォワードクラウド請求書APIの操作についてできる限りていねいに紹介をするシリーズをお送りしています。

前回の記事はこちら。

マネーフォワードクラウド請求書APIから請求書一覧の取得をテストしてみよう！

GASによるマネーフォワードクラウド請求書APIの操作についてできる限りていねいに紹介をするシリーズです。今回は、マネーフォワードクラウド請求書APIから請求書一覧の取得をテストてみよう！をお送りします。

請求書一覧の取得について、ドキュメントページでリクエストのテストをしてみました。

それで、レスポンスも表示されていたのですが、とっても長ーいデータだったんですよね…

ということで、今回はその中身を解析していきます。

マネーフォワードクラウド請求書APIによる請求書一覧のデータを読み取ってみよう！です。

行ってみましょう！

前回のおさらい
請求書一覧のレスポンスの内容
1回のリクエストだけでは全件は取得できない
まとめ
連載目次：【初心者向け】GASでマネーフォワード請求書API

前回のおさらい

前回は、以下のマネーフォワードクラウド請求書APIのドキュメントページを使って、請求書一覧の取得のテストを行いました。

https://invoice.moneyforward.com/api/v2/swagger_ui

リクエストをする際の、リクエストURL、メソッド、パラメーターなどについて確認しつつ、無事にリクエストを行うことができました。

それで、そのレスポンスとして、以下の「Response body」の部分、とっても長ーいデータが得られたのですが、それがどういう構成になっているかを知る必要がありますよね。

今回は、この部分を解説していきます。

請求書一覧のレスポンスの内容

では、請求書一覧のレスポンスの内容について見ていきましょう。

先ほどの表示されたレスポンスからさらに少し下にスクロールすると、「Example Value」つまりレスポンスのサンプルデータがありますので、そちらを見ていきましょう。

ちなみに左上のCodeが「200」となっているのがリクエスト成功時のレスポンスです。

このレスポンスのデータはJSON形式と呼ばれるもので、JavaScriptのオブジェクトとほぼ一緒の形式です。

オブジェクトや配列がわかれば、順番に紐解いていくことができます。

さて、請求書一覧のレスポンスは大きく３つのパートに分かれていますので、ひとつひとつ確認していきましょう。

請求書のデータ

まず、冒頭の部分に「”data”」とありますが、ここがいわゆる請求書のデータです。

たくさん項目がありちょっと複雑なので主要なものだけ抽出してデフォルメすると、以下のようになります。

{
  "data": [
    {
      "id": ID,
      "attributes": {
        "office_name": 事業所名,
        "partner_name": 取引先名,
        "title": 件名,
        "total_price": 税込価格,
        "sales_date": 売上計上日,
        "due_date": 支払日
      }
  },
  …
}

dataプロパティは配列になっていて、その要素のひとつひとつが請求書の一件を表します。

請求書はオブジェクト形式になっていて、idプロパティが請求書IDを文字列で、attributesが請求書の内容をオブジェクトで持っています。

請求書の内容を取り出すには、さらにtitleプロパティやtotal_priceプロパティを取り出せばOKです。

請求書に含まれる品目データ

スクロールして中頃までいくと、「”includes”」とあります。ここは請求書に含まれる品目データです。

おそらく請求書一覧の取得で、品目を取り出すということはそれほど多くないと思います。

というのも、品目を取得したいなら、それ用のリクエストをすることができます。

ということで、ここで品目に関しての解説は割愛します。

取得に関するメタデータ

そして、一番下までスクロールすると「”meta”」というパートがありますが、請求書一覧の取得に関するメタデータです。

また主な部分だけ抜粋すると以下のようになっています。

{
  …
  "meta" : {
    "total_count": 件数,
    "total_pages": 全ページ数,
    "current_page": 現在のページ数,
    "per_page": 1ページあたりの件数
  }
}

metaプロパティでオブジェクトが取得でき、さらにその中のtotal_countプロパティで件数を、total_pagesプロパティで全ページ数というように取得できます。

1回のリクエストだけでは全件は取得できない

さて、ここで一点問題があります。

実は、１回のリクエストでは全件の請求書データを取得できないのです。

実際にリクエストをしたレスポンスを再度見てみましょう。

トータルの請求書の件数が258件で、全部で3ページあるのですが、今回のリクエストでは1ページ目だけ100件しか取得してないことになっています。

ただ、1ページあたりの表示数を100を超える数字にすると、以下のように受け付けてくれません。

つまり、2ページ目の101件目以降の請求書データを取得するには、ページ数を変更して必要なページの回数だけリクエストをしないといけないということです。

まとめ

以上、マネーフォワードクラウド請求書APIによる請求書一覧のデータを読み取ってみよう！でした。

APIの活用では、今回のようなレスポンスで得られるJSONデータの中身を紐解いていき、ほしいデータをどうやって取り出すかというのを検討する手順がほぼ必ずあります。

いろいろなリクエストを試して、実戦を積んでいきましょうね。

次回は、実際にGASで請求書一覧の取得を進めていきたいと思います。

GASでマネーフォワード請求書の請求書一覧を取得するスクリプト

GASによるマネーフォワードクラウド請求書APIの操作についてできる限りていねいに紹介をするシリーズです。今回は、GASでマネーフォワード請求書の請求書一覧を取得するスクリプトについてお伝えしていきます。

どうぞお楽しみに！

連載目次：【初心者向け】GASでマネーフォワード請求書API

マネーフォワード請求書APIを使用することで、GASからマネーフォワード請求書のデータを取得したり、操作をしたりすることが可能です。このシリーズでは、そのはじめの一歩として、マネーフォワード請求書APIとは何か？またGASによるアクセスの初歩をお伝えしていきます！