【追記】
この記事のプログラムは2023年3月時点でのMFクラウド請求書API（v3.0.0）を使用しています。
v3.1.0にて、こちらの記事で紹介している「請求書作成API」が非推奨になり、
今後使用できなくなる予定であることが発表されました。
連載記事を全てお読みいただいた後に、
以下の記事を参考にv3.1.0への移行をお願いいたします。

こんにちは！

突然ですが、約1ヶ月前にこんな重大ニュースが発表されていたのをご存知ですか？↓

これまで私が紹介していたマネーフォワードクラウド請求書APIはv2だったのですが、
v2のサポートが2023年6月末で、提供が同年9月末で終了するので、
v2提供終了までの約半年間でv3に対応してね～という内容です。

…半年という猶予期間って世の平均的にどうなんですかね？（私には短く感じてしまう…）

公式のv3スタートアップガイドはこちら。

ということで、以前紹介したGASとマネーフォワードクラウドの連携コードをv3に移行すべく、
サポートに何度も問い合わせ悪戦苦闘しながらも何とか形にできましたので、
今回はそれをご紹介します！

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

1. API準備篇
2. 認証篇
3. 請求書データ取得篇
4. 請求書作成篇
5. 自動化篇

これらの記事のコードを書き換えていくので、未読の方は先にご一読いただければ幸いです！

認証方法の変更

最初に、これまではマネーフォワードクラウド請求書の機能でAPI連携設定をしていましたが、
v3ではマネーフォワードクラウド全体でのAPI連携設定をするためのアプリポータルができました。

「Client ID」と「Client Secret」もv2とv3で異なるので、
アプリポータルで連携用アプリを新規作成して再度認証設定を行っていきましょう。
※公式マニュアルはこちら

アプリポータルにログインし、左のメニューから「アプリ開発[開発者向け]」をクリックし、
「新規追加」ボタンをクリックします。

アプリ名称は自由な名前を設定し、リダイレクトURIはv2と同じものを設定します。

クライアント認証方式はCLIENT_SECRET_POSTを選択し、「作成」ボタンをクリックしてください。

「Client ID」と「Client Secret」が発行されるので、これをGASに設定し直します。

以前はクラシックエディタを使用しないとこれらを設定できなかったのですが、
現在は設定できるようになっていますので簡単に説明します。

GASを開き、左のメニューから歯車マークの「プロジェクトの設定」をクリックします。

最下部に「スクリプトプロパティ」という箇所があるので、こちらに設定し、保存しましょう。

ここまでできたらプログラムに戻り、認証用関数「getService_()」を以下の通り書き換えます。

書き換えたら「auth()」を実行し、v2で行った認証作業と同じように、
出力された認証URLをブラウザに貼り付けて認証作業を行いましょう。

function auth() {
  // 認証用URLを取得しコンソールに出力
  console.log(getService_().getAuthorizationUrl());
}

function getService_() {
  // スクリプトのプロパティを取得
  const PROPERTIES = PropertiesService.getScriptProperties();

  // 指定した名前でサービスを作成（名前は何でもOK）
  return OAuth2.createService('moneyforward')
    .setAuthorizationBaseUrl('https://api.biz.moneyforward.com/authorize')
    .setTokenUrl('https://api.biz.moneyforward.com/token')
    .setClientId(PROPERTIES.getProperty('CLIENT_ID'))
    .setClientSecret(PROPERTIES.getProperty('CLIENT_SECRET'))
    .setCallbackFunction('callback')
    .setPropertyStore(PropertiesService.getUserProperties())
    .setScope('mfc/invoice/data.write');
}

v2との違いは以下の通りです。

• 「setAuthorizationBaseUrl()」の引数のURLをv3のものに変更
• 「setTokenUrl()」の引数のURLをv3のものに変更
• 「setScope()」の引数のスコープをv3のものに変更
  • 請求書情報取得のみの場合：「mfc/invoice/data.read」
  • 請求書作成等更新を行う場合：「mfc/invoice/data.write」

この情報は今でこそv3の請求書APIドキュメントに記載されているのですが、
実はv3の発表直後の各ドキュメント・マニュアルには、
スコープに何を指定すればいいのかが一切記載されていなかったんですよ！！

以前は「read」か「write」でよかったのですが、請求書だけのAPI認証設定でなくなったので、
当然「read」「write」では動かなくなっていたんですよね…。

これ、私が最速でサポートに問い合わせて記載してもらったんですよ！！褒めて！！！
※当時本当に悩み苦しみました

請求書APIの変更

【追記】
v3.2.1から、新形式請求書作成APIで直接品目追加ができるようになりました。
リクエストボディに配列itemsを追加し、配列内のオブジェクトに「item_id」を設定してください。
また、v3.2.6にて、「item_id」が必須でなくなり、
任意の名前や単価で品目を自由に追加することができるようになりました。
詳細はこちらをご覧ください。

認証ができたので、次は請求書を作成するコードの変更です。

最大の変更点は、請求書作成APIで品目を指定できなくなったことです（改悪…）。

v3では、請求書作成APIを実行し、その戻り値で請求書IDを取得し、
それを用いて請求書への品目追加APIを品目の数だけ実行して品目を登録する、という流れになります。

そして、大変残念なことに、この請求書への品目追加API、「item_id」が必須となっており、
任意の名前や単価で品目を自由に追加することができません…。

涙を堪えつつ、「item_id」を確認していきましょう…。

マネーフォワードクラウド請求書にログインし、
左のメニューから「マスタ管理」→「品目」をクリックし、
請求書に追加したい品目の「編集」ボタンをクリックします。

編集画面のURLは下記のようになっています。

https://invoice.moneyforward.com/items?action=edit&id=[item_id]

ここの「&id=」に続く文字列が「item_id」です！

では、「item_id」が確認できたので、請求書作成プログラムを作り直していきましょう。

// 請求書作成（引数で取引先の部門を指定）
function createNewInvoice_(department) {
  // 請求書IDを返却
  return JSON.parse(UrlFetchApp.fetch('https://invoice.moneyforward.com/api/v3/billings', {
    method: 'POST',
    contentType: 'application/json',
    headers: {
      accept: 'application/json',
      Authorization: 'Bearer ' + getService_().getAccessToken()
    },
    payload: JSON.stringify({
      department_id: department,
      billing_date: Utilities.formatDate(new Date(), 'JST', 'yyyy-MM-dd'),
      due_date: Utilities.formatDate((d => {
        d.setMonth(d.getMonth() + 1);
        d.setDate(0);
        return d;
      })(new Date()), 'JST', 'yyyy-MM-dd')
    })
  })).id;
}

// 請求書への品目追加（引数で請求書IDと品目を指定）
function attachItems_(billing, items) {
  // 品目は複数指定できるよう配列にしてループ
  items.forEach(item => {
    UrlFetchApp.fetch(`https://invoice.moneyforward.com/api/v3/billings/${billing}/items`, {
      method: 'POST',
      contentType: 'application/json',
      headers: {
        accept: 'application/json',
        Authorization: 'Bearer ' + getService_().getAccessToken()
      },
      payload: JSON.stringify({
        item_id: item
      })
    });
  });
}

APIのURLをv3のものに書き換えるのを忘れないように注意してくださいね。

v2より請求書APIドキュメントが親切になっており、
リクエストボディの必須項目が明文化されています。

これによると、「sales_date」や「billing_number」は必須ではないようで、指定しなくても、
マネーフォワードクラウド請求書の帳票設定に従って請求書に設定してくれることを確認済みです。

後はこれらの関数を、
「department（department_id）」「items（item_idの配列）」を指定して呼び出せばOKです！

サポートをご希望の方へ

v3への移行方法のご紹介は以上になりますが、これを自力でやるのはちょっと難しいかなという方、
できればマンツーマンで解説してほしいという方、
v3の請求書作成API以外のAPIを使いたいからサポートしてほしいという方、
様々いらっしゃるかと思います。

そのようなお困りの方々向けのサポート等のご相談、
こちらにて承っておりますので、
是非お気軽にお問い合わせください！

可及的速やかにお返事させていただきます！

また、請求書APIそのものの詳細な仕様に関するご質問は、
お手数ですがマネーフォワードクラウド請求書のサポートをご利用ください。
※私の体感ですが正式な回答を得るまで結構待つ必要があります

終わりに

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

この記事を多くの方々に読んでもらえれば、
私が頑張ってサポートに問い合わせた努力が報われると思うので、是非拡散お願いします…！

v1・v2がどのぐらいの利用ユーザーがいたのかは分かりませんが、
提供終了まで半年を切っているので、慌てられている方々の助けに少しでもなれば幸いです！

そして、いつかマネーフォワードクラウドにも、
kintoneのようなAPIについて質問できるコミュニティサイトができればいいなと思う今日この頃です。