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

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

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

前回の記事はこちら。

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

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

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

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

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

行ってみましょう!

スポンサーリンク

前回のおさらい

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

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

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

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

マネーフォワードクラウド請求書APIドキュメントの請求書一覧の取得の実行結果

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

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

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

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

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

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

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

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

請求書のデータ

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

請求書一覧のレスポンスの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”」とあります。ここは請求書に含まれる品目データです。

請求書一覧のレスポンスのincludes

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

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

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

取得に関するメタデータ

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

請求書一覧のレスポンスのmeta

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

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

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

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

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

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

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

請求書一覧の実際のレスポンスのmeta

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

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

1ページあたりの件数は100を超えることはできない

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

まとめ

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

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

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

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

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

どうぞお楽しみに!

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

マネーフォワード請求書APIを使用することで、GASからマネーフォワード請求書のデータを取得したり、操作をしたりすることが可能です。このシリーズでは、そのはじめの一歩として、マネーフォワード請求書APIとは何か?またGASによるアクセスの初歩をお伝えしていきます!
  1. はじめてのマネーフォワード請求書API~その概要とおおまかな手順
  2. マネーフォワード請求書APIへのアクセスをテストしてみよう!
  3. GAS用のマネーフォワード請求書APIアプリケーションを作成する手順
  4. GASでAPIを操作をする強い味方「OAuth2 for Apps Script」ライブラリとその導入
  5. GASでマネーフォワードクラウド請求書APIへの認証とアクセストークンの取得を行う方法
  6. OAuth2 for Apps Scriptライブラリを使ってサービスを作るスクリプトを解説
  7. OAuth2 for Apps Scriptライブラリはどうやって認証用URLを作成しているのか
  8. OAuth2 for Apps Scriptライブラリはどうやってアクセストークンを取得するのか
  9. GASではじめてのマネーフォワードクラウド請求書APIへリクエスト
  10. マネーフォワードクラウド請求書APIから請求書一覧の取得をテストしてみよう!
  11. マネーフォワードクラウド請求書APIによる請求書一覧のデータを読み取ってみよう!
  12. GASでマネーフォワード請求書の請求書一覧を取得するスクリプト
  13. GASでマネーフォワードクラウド請求書の請求書一覧をスプレッドシートに書き出す方法
  14. マネーフォワードクラウド請求書の請求書一覧の全件をスプレッドシートに書き出すスクリプト
タイトルとURLをコピーしました