メインコンテンツへスキップ
見出し画像

【MFクラウド会計API】GASで口座明細から仕訳を作成し、複数行更新・証憑添付まで行う

  • 割引あり

はじめに

MFクラウド会計APIでは、これまでにも仕訳を直接登録できましたが、連携している金融機関やカードの明細を処理するAPIは提供されていませんでした。2026年7月14日の仕様更新により、連携先から収集した明細をAPIで取得し、その明細を起点に仕訳を作成できるようになりました。

この記事では、GASからAPIを呼び出し、次の流れで口座明細を複数行の仕訳へ変換し、証憑を添付する方法を説明します。

  • 連携サービスと口座を特定する

  • 仕訳登録に必要な科目などのIDを取得する

  • 未仕訳の口座明細を取得する

  • `journalize` で明細金額の仕訳を仮登録する

  • 作成した仕訳を取得し、PUTで複数行へ更新する

  • 更新後の仕訳に証憑を添付する

APIを利用するには、アプリ登録とOAuth 2.0認証が必要です。準備方法は、過去記事「【MFクラウド会計】API連携の準備とOAuth認証」で紹介しているため、本文は認証済みの前提で進めます。

この記事で作る仕組み

実務で使う全体像は、「口座明細を集める」「人が内容を確認して科目などを判断する」「判断結果を仕訳へ反映する」の3段階です。スプレッドシートは、APIから取得したデータを人が確認し、登録内容を決めるための入口として使います。

画像
口座明細を集め、内容を人が確認し、判断結果を仕訳へ反映する全体像

各Stepでは、この仕組みの裏側を理解できるようにGASからAPIを直接呼び出す例を示します。最後のおまけでは、取得したデータをスプレッドシートへ出力し、選択画面から仕訳を登録・編集できる完成版サンプルを紹介します。

💡 ポイント

今回の中心は、GET /api/v3/transactions で未仕訳明細を取得し、POST /api/v3/transactions/journalize で仮登録した仕訳を、PUT /api/v3/journals/{id} で最終形へ更新する流れです。

この記事で扱うAPI

Money Forwardの会計APIは、現在V3を使用します。APIのベースURLは次のとおりです。

https://api-accounting.moneyforward.com

今回使用する主なエンドポイントは次のとおりです。

  • `GET /api/v3/connected_accounts`:連携サービスを取得します

  • `GET /api/v3/accounts`:勘定科目を取得します

  • `GET /api/v3/transactions`:連携サービスで収集された明細を取得します

  • `POST /api/v3/transactions/journalize`:指定した明細から仕訳を作成します

  • `GET /api/v3/journals/{id}`:登録した仕訳を取得します

  • `PUT /api/v3/journals/{id}`:登録した仕訳を更新します

  • `POST /api/v3/vouchers`:証憑を新規保存し、仕訳に関連付けます

公式のAPI仕様は、Money Forward クラウド会計API で確認できます。APIの追加・変更はリリースノートにも掲載されるため、実装前に 公式リリースノート を確認する習慣をつけておくと安心です。

事前準備:明細連携の権限を確認する

本文ではOAuth認証の手順を繰り返しませんが、口座明細APIを使う前に、OAuthスコープとは別のユーザー権限を確認する必要があります。

先に自分のユーザーへ「マネーフォワード 明細連携」の権限を付ける

口座明細APIを利用する前に、アプリポータルで、OAuth認証に使う自分のユーザーへ明細連携の権限を付けます。「ユーザー」から自分のユーザー情報を開き、右上の「編集」をクリックして、「アプリ連携権限」で次の項目を有効にしてください。

  • `アプリ連携`

  • `クラウド会計・確定申告`

  • `マネーフォワード 明細連携`

画像
アプリポータルのユーザー情報で「マネーフォワード 明細連携」を付与している画面

⚠️ 重要
OAuthスコープの設定とは別に、ユーザー自身への「マネーフォワード 明細連携」の権限付与が必要です。この権限がないと、他のAPIを利用できても明細APIだけが403になる場合があります。権限を追加したあとは、mfc/accounting/transaction.read と mfc/accounting/transaction.write を含めてOAuth認証をやり直してください。

記事末尾の完成版GASには、認証情報の入力、OAuth認証、アクセストークン取得も組み込んでいます。完成版だけを試す場合も、先にこのユーザー権限を設定してください。

GASの共通APIクライアントを先に用意する

まず初めに、各Stepで使用する共通APIクライアントを用意します。APIを呼び出すたびに、アクセストークンの取得、ヘッダー設定、JSON化、エラーチェックを書くとコードが重複するためです。

共通関数に「HTTPメソッド」「エンドポイント」「Bodyに送るオブジェクト」を渡す形にしておくと、以降は引数とJSON Bodyを変えるだけで、マスタ取得、明細取得、仕訳登録、仕訳更新へ使い回せます。

function mfGet_(path, params) {
  const query = toQuery_(params || {});
  return mfRequest_('get', path + (query ? '?' + query : ''));
}

function mfPost_(path, body) {
  return mfRequest_('post', path, body);
}

function mfPut_(path, body) {
  return mfRequest_('put', path, body);
}

function toQuery_(params) {
  return Object.keys(params)
    .reduce(function(parts, key) {
      const values = Array.isArray(params[key]) ? params[key] : [params[key]];
      values.forEach(function(rawValue) {
        if (rawValue === '' || rawValue === null || rawValue === undefined) return;
        const value = /(^|_)ids?$/.test(key) ? normalizeApiId_(rawValue) : rawValue;
        parts.push(encodeURIComponent(key) + '=' + encodeURIComponent(value));
      });
      return parts;
    }, [])
    .join('&');
}

function normalizeApiId_(value) {
  try {
    return decodeURIComponent(String(value || ''));
  } catch (error) {
    return String(value || '');
  }
}

function encodeApiId_(value) {
  return encodeURIComponent(normalizeApiId_(value));
}

`mfRequest_()` の本体は、最後の完成版コードにまとめています。本文中の各Stepでは、HTTPメソッド、エンドポイント、必要なパラメータやBodyだけを指定し、この共通関数からAPIを呼び出します。

Step1: 連携サービスと口座を特定する

口座明細APIでは、口座の表示名ではなく、APIが発行したIDで取得対象を指定します。このIDは自分で決めたり画面表示から推測したりするものではなく、`GET /api/v3/connected_accounts` のレスポンスから取得します。

そのため、明細を取得する前に連携サービスと口座の一覧を取得し、連携口座マスタとして同期しておくことが前提になります。完成版GASでも、先に「マスタを同期」を実行して「連携口座」シートへ保存し、その同期結果から取得対象を選ぶ流れにしています。

`GET /api/v3/connected_accounts` を実行すると、現在の事業者に連携されているサービスや口座の情報を取得できます。

function fetchConnectedAccounts() {
  const response = mfGet_('/api/v3/connected_accounts');
  Logger.log(JSON.stringify(response, null, 2));
  return response.connected_accounts || [];
}

レスポンスは、連携サービスを親、その配下の個別口座を子とする構造です。明細取得では、次のどちらかのIDを使います。

  • `connected_account_id`:親にあたる連携サービス全体のIDです

  • `connected_sub_account_id`:子にあたる個別口座のIDです

たとえば、1つの銀行連携の配下に複数の口座がある場合、銀行連携全体を指定するのが `connected_account_id`、そのうち1口座だけを指定するのが `connected_sub_account_id` です。

特定の口座だけを取得する場合は `connected_sub_account_id`、サービス配下の全口座を取得する場合は `connected_account_id` を指定します。この2つは同時には指定しません。

⚠️ 重要
connected_sub_account_id へ渡すのは、子要素の id です。レスポンスに含まれる名前の似た sub_account_id や、会計マスタの補助科目IDではありません。

💡 ポイント
APIを使うプログラムは、対象を一意に識別できるIDを基準に処理します。一方、利用者はIDだけでは対象を判断しにくいため、操作画面には口座名を表示し、選ばれた口座に対応するIDをAPIへ送る形にすると扱いやすくなります。

口座を追加・削除した場合は、明細を取得する前に連携口座マスタを再同期します。

Step2: 仕訳に必要なマスタ情報を取得する

明細の内容だけでは仕訳を登録できません。仕訳APIは勘定科目なども表示名ではなくIDで受け取るため、仕訳登録の前に、勘定科目、補助科目、部門、税区分、取引先コードなどのマスタ同期が必要です。

勘定科目は、次のAPIで取得できます。

function fetchAvailableAccounts() {
  const response = mfGet_('/api/v3/accounts', { available: true });
  Logger.log(JSON.stringify(response, null, 2));
  return response.accounts || [];
}

レスポンスには、勘定科目の `id`、`name`、`account_group`、`category`、`sub_accounts` などが含まれます。仕訳登録時は画面に表示される科目名ではなく、レスポンスに含まれる `id` を指定します。

補助科目、部門、税区分なども同じ考え方で、あらかじめマスタAPIからIDを取得します。マスタの取得や仕訳の直接登録については、過去記事「【MFクラウド会計】APIで仕訳を登録してみよう」で詳しく説明しています。

本文ではレスポンスから必要なIDを読み取って関数へ渡します。後半のサンプルでは、取得したマスタをスプレッドシートへ保存し、表示名を選ぶと対応するIDが使われる形にします。

Step3: 未仕訳の口座明細を取得する

明細一覧は `GET /api/v3/transactions` で取得します。

特定の口座について未仕訳明細を取得する関数は、開始日・終了日・連携口座IDを引数で受け取る形にします。`connectedSubAccountId` には、Step1で取得した個別口座IDを渡します。

function fetchUnjournalizedTransactions(startDate, endDate, connectedSubAccountId) {
  const response = mfGet_('/api/v3/transactions', {
    start_date: startDate,
    end_date: endDate,
    connected_sub_account_id: connectedSubAccountId,
    journalizing_statuses: 'none',
    order: 'asc',
    per_page: 1000
  });

  Logger.log(JSON.stringify(response, null, 2));
  return response.transactions || [];
}

主なクエリパラメータは次のとおりです。

  • `start_date`、`end_date`:対象期間。日付の差は366日以内にします

  • `connected_account_id`:連携サービスで絞り込みます

  • `connected_sub_account_id`:連携口座で絞り込みます

  • `journalizing_statuses=none`:未仕訳に絞り込みます

  • `order=asc` または `order=desc`:並び順を指定します

  • `page`、`per_page`:ページングを指定します。`per_page` の上限は1,000件です

レスポンスのページ数は `metadata.total_pages` に含まれます。完成版では、現在の `page` が `metadata.total_pages` に達するまで繰り返し取得するため、1,000件を超える場合も次ページを取りに行きます。

レスポンスでは、仕訳登録に必要な次の情報を確認します。

  • `id`:明細ID

  • `date`:明細日

  • `value`:金額

  • `side`:入金か出金か

  • `content`:明細の内容

  • `journalizing_status`:仕訳状態

  • `connected_account_id`、`connected_sub_account_id`:明細の取得元

  • `voucher_file_ids`:明細側に存在する証憑ファイルID

最初は取得した明細をすぐ登録せず、ログやスプレッドシートへ一覧出力して内容を確認します。後半のサンプルでは、明細を `明細` シートへ出力し、選択した行だけをモーダルから登録します。

Step4: 口座明細から仕訳を作成する

明細を仕訳に変換するには、`POST /api/v3/transactions/journalize` を使用します。

最小限必要なのは `transaction_id` と `account_id` です。ここで指定する `account_id` は、明細金額の全額で最初の仕訳を作るための相手科目です。

必要に応じて、`transaction_date`、`sub_account_id`、`department_id`、`tax_id`、`invoice_kind`、`remark` などを追加します。`transaction_date` を省略した場合は、元明細の日付が使われます。

GASから実行する場合は、取得した明細の `id` と、マスタから選んだ値で組み立てたBodyを渡します。

function journalizeOneTransaction(transactionId, journalizeBody) {
  if (!journalizeBody || !journalizeBody.account_id) {
    throw new Error('マスタから勘定科目を選択してください。');
  }

  const payload = Object.assign({}, journalizeBody, {
    transaction_id: transactionId
  });

  const response = mfPost_('/api/v3/transactions/journalize', payload);
  Logger.log(JSON.stringify(response, null, 2));

  return response.journal;
}

`journalizeBody` には、Step2で取得した勘定科目の `id` を `account_id` として設定します。補助科目、部門、税区分を使う場合だけ、それぞれのIDも追加します。

ここで押さえておきたいのは、`journalize` APIだけでは複数行の仕訳を登録できないことです。Bodyには行ごとの金額を指定する項目がないため、まず1つの相手科目を選び、明細金額の全額で仮登録します。複数行にする処理はStep5で行います。

作成に成功すると、レスポンスには作成された `journal` が返ります。ここから `journal.id` を保存します。後続の仕訳更新や証憑添付では、この仕訳IDを使用します。

💡 ポイント
同じ明細からの重複登録を防ぐため、明細取得とステータス管理を組み合わせておくとよいでしょう。取得時は journalizing_statuses=none で未仕訳だけに絞り、処理後は transaction_id、journal.id、処理結果を保存します。再実行前にAPI上の状態と保存した結果を確認できるようにすると、二重登録を防ぎやすくなります。

明細を起点にした仕訳では、入金・出金の向きや指定した科目によって、登録される仕訳の内容を実際のテスト事業者で確認してください。会計上の借方・貸方の判断を、APIのフィールド名だけから推測して自動化しないことが大切です。

Step5: 登録した仕訳を取得し、複数行へ更新する

仕訳作成APIのレスポンスだけで処理を進めず、仕訳IDを使って登録内容を取得すると、実際に登録された値を確認できます。

function getJournal(journalId) {
  const response = mfGet_('/api/v3/journals/' + encodeApiId_(journalId));
  Logger.log(JSON.stringify(response, null, 2));
  return response.journal;
}

更新は `PUT /api/v3/journals/{id}` を使用します。変更した行だけを送るのではなく、取得した `transaction_date`、`journal_type`、`memo`、`tags` と、最終形の `branches` を含む `journal` Bodyを組み立てます。

function updateJournalBranches(journalId, branches) {
  const current = getJournal(journalId);
  const response = mfPut_('/api/v3/journals/' + encodeApiId_(journalId), {
    journal: {
      transaction_date: current.transaction_date,
      journal_type: current.journal_type,
      memo: current.memo || '',
      tags: current.tags || [],
      branches: branches
    }
  });

  Logger.log(JSON.stringify(response, null, 2));
  return response.journal;
}

処理は次の順番です。

  1. `journalize` で明細金額の全額を仮登録します

  2. 返された `journal.id` で仕訳を取得します

  3. 最終的な借方・貸方を組み立て、貸借合計を検算します

  4. 同じ仕訳IDへPUTし、複数行の仕訳へ更新します

借方2行・貸方1行は登録できるか

まず、貸借の行数が異なる実際の登録結果を示します。画像は借方1行・貸方2行の例ですが、借方2行・貸方1行でも、貸借合計を一致させる考え方は同じです。

画像
借方の普通預金420,000円を1行、貸方の売上高を400,000円と20,000円の2行で登録した結果

借方2行・貸方1行のように、貸借の科目数が異なる仕訳も考えられます。公式リファレンスの例では、1つの `branch` に `debitor` と `creditor` が並んでいます。一方、公開OpenAPIスキーマでは両方が必須とはされていないため、各明細を片側だけ持つ `branch` として表現する方法があります。

サンプルでは借方・貸方を独立した行として扱い、たとえば次の入力を3つの枝へ変換します。

  • 借方A:70円

  • 借方B:30円

  • 貸方C:100円

APIへは次の3枝として送ります。

  • 1枝目:`debitor` のみ、借方A 70円

  • 2枝目:`debitor` のみ、借方B 30円

  • 3枝目:`creditor` のみ、貸方C 100円

この形なら貸方Cを100円の1行として表現できます。片側を指定する場合も、その中の `account_id` と `value` は必須です。

⚠️ 重要
片側だけを持つ branch は公開スキーマに基づく実装です。公式のリクエスト例とは形が異なるため、借方2行・貸方1行などの代表パターンをテスト事業者で登録・再取得し、期待どおり表示されることを確認してから利用してください。

仕訳と元明細を追跡できるように、`journal.id` と `transaction_id` はセットで保存します。明細APIの `journalizing_statuses=registered` や、仕訳一覧APIの `transaction_ids` でも処理結果を確認できます。

Step6: 更新した仕訳に証憑を添付する

証憑の添付は、「証憑を保存する」「証憑IDを取得する」「その証憑IDを仕訳へ紐づける」という関係で捉えると分かりやすくなります。

`POST /api/v3/vouchers` では、ファイル名、Base64化したファイルデータ、Step5で更新した仕訳の `journal_id` を送ります。これにより、証憑の新規保存と仕訳への紐づけを1回のリクエストで行い、レスポンスの `voucher_file_ids` から発行された `file_id` を取得できます。

GASでGoogle Drive上のファイルを添付する場合は、ファイルのバイナリを取得してBase64に変換します。

function attachVoucherToJournal(journalId, driveFileId) {
  const file = DriveApp.getFileById(driveFileId);
  const blob = file.getBlob();

  const payload = {
    journal_id: journalId,
    voucher_files: [{
      file_name: file.getName(),
      file_data: Utilities.base64Encode(blob.getBytes())
    }]
  };

  const response = mfPost_('/api/v3/vouchers', payload);
  Logger.log(JSON.stringify(response, null, 2));

  const savedVouchers = response.voucher_file_ids || [];
  return savedVouchers.map(function(voucher) {
    return voucher.file_id;
  });
}

添付後は、仕訳を再取得して `voucher_file_ids` を確認します。同じ証憑を重複して添付しないよう、元明細や仕訳に保存済みの証憑IDも確認してください。

参考リンク

公式情報

過去記事

おまけ:スプレッドシートを操作画面にする

ここからは、本文で説明したAPI処理を、スプレッドシートから操作できる形にまとめます。APIを直接呼び出す仕組みを理解したあとに、日々の登録作業を行うための画面を追加するイメージです。

シート構成

サンプルでは、次のシートを作成します。

  • `連携口座`:連携サービス・口座のID、表示名、口座に紐づく勘定科目ID・補助科目ID

  • `勘定科目`:勘定科目ID・名称・カテゴリ

  • `補助科目`:補助科目ID・名称・親勘定科目ID

  • `税区分`:税区分ID・名称・税率

  • `部門`:部門ID・名称

  • `明細`:APIから取得した口座明細と、仕訳登録結果

  • `仕訳ヘッダ`:仕訳ID、明細ID、取引日、メモ、行数

  • `仕訳行`:仕訳ID、行番号、借方・貸方の金額と各種ID

マスタはAPIから取得してシートへ一括出力します。モーダルを開くたびにAPIへマスタを取りに行くのではなく、同期済みのシートを候補リストとして使う構成です。明細は、選択した口座と期間を条件にAPIから取得して「明細」シートへ出力します。

口座と期間を選んで明細を同期する

「マスタを同期」を実行したあと、メニューから「明細を同期(口座を選択)」を実行します。モーダルには、同期済みの「連携口座」シートをもとに次の候補が表示されます。

  • `【全口座】連携サービス名`:`connected_account_id` を使い、サービス配下の全口座を取得します

  • `連携サービス名 / 口座名`:`connected_sub_account_id` を使い、選んだ口座だけを取得します

同じ画面で開始日と終了日を指定し、選んだ口座の未仕訳明細を取得します。仕訳IDを持つ登録済み行や、仮登録後に更新待ちとなった行は残すため、明細を再同期したあとも元の行から編集を再開できます。

💡 ポイント
IDを直接貼り付けず、同期済みの表示名から選ぶことで、補助科目IDや古い口座IDを誤って送る事故を防ぎます。口座を追加・削除したときは、先に「マスタを同期」を実行してください。

明細から仕訳を登録・編集する画面

`明細` シートで対象行を選び、「選択中の明細を仕訳登録・編集」を実行します。仕訳IDの有無に応じて、同じ入口から新規登録と再編集を切り替えます。

  • 仕訳IDが空の未仕訳明細:新規登録画面を開きます

  • 仕訳IDがある明細:`GET /api/v3/journals/{id}` で現在の仕訳を取得し、編集画面を開きます

  • API上では仕訳済みなのにシートの仕訳IDが空の明細:`transaction_ids` で仕訳を検索し、取得したIDを書き戻します

モーダルには、明細の日付、入出金、金額、内容を表示し、その下に借方行と貸方行を分けて配置します。各仕訳行は次の並びです。

  • 1段目:勘定科目、補助科目、金額、税区分

  • 2段目:部門、取引先コード、インボイス区分

  • 3段目:摘要

勘定科目は、科目名、検索キー、カテゴリから候補を絞り込むサジェスト方式です。表示文字ではなく、候補に紐づく勘定科目IDをAPIへ送ります。

インボイス区分は「適格請求書あり」のチェックボックスにし、選んだ税区分に応じて次の値へ変換します。

  • チェックあり:`INVOICE_KIND_QUALIFIED`

  • チェックなし:`INVOICE_KIND_UNQUALIFIED_80`

  • 課税仕入れ関連以外:`INVOICE_KIND_NOT_TARGET`

💡 ポイント
課税仕入れ関連かどうかは、同期した税区分の名称・省略名・検索キーから判定します。独自名称を使っている場合は、完成版コードの判定条件を自社用に調整してください。

⚠️ 重要
勘定科目名を入力しただけではIDを確定できない場合があります。候補から選択してください。同名科目がある場合も、候補に表示されるカテゴリや検索キーを確認して選びます。

借方行と貸方行には別々の追加・削除ボタンがあり、科目数が異なる仕訳も入力できます。画面下部で借方合計と貸方合計を検算します。

入金では借方、出金では貸方に、連携口座から生成される「口座側仕訳行」を表示します。この行は編集・削除できず、摘要には元明細の内容を設定します。画面上で無効化するだけでなく、GAS側でも元の行と一致することを検証し、変更されていればAPIを呼び出しません。

登録ボタンを押すと、次の順番で処理します。

  1. 途中入力、金額、貸借一致、口座側仕訳行を検査します

  2. 日付を `YYYY-MM-DD` にそろえ、`journalize` で仮登録します

  3. 作成した仕訳を取得し、画面の借方・貸方でPUTします

  4. 必要な場合は証憑を保存・紐づけします

  5. 仕訳IDと処理結果を各シートへ書き戻し、完了後にモーダルを閉じます

PUTに失敗した場合も、仮登録済みの仕訳IDを「明細」シートへ残します。同じ明細行から編集画面を開けば、`journalize` を重ねずにPUTから再開できます。証憑添付だけが失敗した場合は、仕訳登録済みであることを明示して警告します。

登録済み仕訳を複数行で再編集する

再編集するときも「仕訳ヘッダ」ではなく、元の `明細` 行を選びます。仕訳IDを手入力せず、明細に保存済みのIDから対象仕訳を取得するため、元明細と仕訳の対応を追いやすくなります。

APIの `branches` を画面へ戻すときは、`debitor` を借方へ、`creditor` を貸方へ展開します。その後、連携口座の科目と一致する口座側仕訳行を固定し、相手側だけを編集できるようにします。

更新時は貸借をもう一度検算してPUTし、更新結果を「仕訳ヘッダ」「仕訳行」「明細」へ書き戻します。

💡 ポイント
本文ではAPIの動きを直接確認し、おまけでは利用者がIDを入力せず、同期済みマスタの表示名から選べる形にしています。

⚠️ 重要
このサンプルはあくまで動作確認用のサンプルです。複数人で使う場合のロックや権限管理、通信失敗時の再試行は別途設計してください。貸借一致を検査しても、会計上の科目・税区分が正しいとは限りません。

ここまで説明したAPI間の受け渡しを整理すると、次の流れになります。口座や科目のIDから始まり、明細ID、仕訳ID、証憑IDを次の処理へ引き継ぎます。

画像
口座と科目のIDを準備し、未仕訳明細、仕訳の仮登録と更新、証憑添付へ進むAPIフロー

参考:完成版GASコード

ここまでの処理をまとめたGASコードです。コードは長いため本文には展開せず、別ファイルにまとめています。OAuth2ライブラリと `MfTransactionJournal.gs` をスプレッドシートに紐づくGASへ追加してください。認証、シート処理、モーダルHTMLも1つのファイルにまとめています。

 
 
会計事務所や税理士事務所の視点から生成AIの活用に関して様々な視点から情報を提供していきます。#推しはGemini

あなたへのおすすめ