GAS x freeeAPIライブラリのトリセツ「勘定科目・取引先・メモタグの等マスタ項目をスプレッドシートに取得しよう」

2022年6月18日 freeeAPI

ノンプログラマー（ITを専門職としない人材）が、Google Apps Script（以下GAS）でfreee APIを簡単に操作するためのライブラリを作成しています。

ノンプログラマーのためのスキルアップ研究会（以下ノンプロ研）で受講したfreee API講座の内容をベースに作成しています。

freee APIを操作するには各マスタ項目のIDが必要

勘定科目
取引先
品目
部門
メモタグ
税区分

といったマスタ項目には名称の他にAPI用のIDが振られています。このIDはいつものfreeeのUIの画面では確認できません。また、基本的にAPIから取得したデータは、各マスタ項目の名称は含まれておらず、IDのみがレスポンスとして返ってきます。そのため、せっかく取得したデータもそのままだと、ちんぷんかんぷんの状態です。

それ以外にも「タグの表記ゆれ」の修正などマスタ項目の一括更新などを行いたい場合も、まずは今の状態のマスタをシートに取り込みたいのではないでしょうか。

今日は、GAS x freeeAPIライブラリを使って、各マスタ項目の取得の仕方を紹介します。

事前準備

GAS x freeeAPIライブラリの導入などの事前準備はこちらの記事を参考にしてください。

GAS x freeeAPIライブラリのトリセツ「事前準備」

事前準備を終えた上で、必要になってくるのは、いつもの通りアクセストークンと操作対象の事業所IDです。

事業所IDの取得方法は以下で紹介しています。

GAS x freeeAPIライブラリのトリセツ「事業所IDを取得してみよう」

基本的には、事業所IDは変わる事は無いので、スクリプト実行の都度取得（APIをコール）するのではなく、プロパティストアやグローバル定数に代入しておくのが良いと思います。

勘定科目一覧をスプレッドシートに取得してみよう

早速、勘定科目のマスタ一覧を取得してみたいと思います。

/* 勘定科目マスタシートに勘定科目をすべて取得する関数 */

function getAccountItemsMaster() {
  const accessToken = getService().getAccessToken();
  const company_id = *******; // 操作したい事業所のID
  freeeAPI.accountItems(accessToken, company_id).getAccountItems2Sheet('勘定科目マスタ');
}

GAS x freeeAPIライブラリを導入していれば、上記のコードで「勘定科目マスタ」という名称のシートが作成されて、そこに勘定科目一覧が取得できます。※ 既に同じ名前のシートがある場合は、上書きされます。

おさらいですが、、GAS x freeeAPIライブラリの基本的な構造は上記のようになっています。今回の勘定科目のシートへの取得の場合でいうと…

freeeAPI → ライブラリの呼び出し
accountItems(アクセストークン, 事業所ID) → 勘定科目操作オブジェクトを生成するファクトリ関数
getAccountItems2Sheet（シート名） → AccountItemsオブジェクトのメンバーである、名前で指定したシートに勘定科目一覧を取得するメソッド

となります。

AccountItemsクラスにはこの他にも

getAllAccountItems() – 全ての勘定科目オブジェクトを配列で取得するメソッド
getIdByName(勘定科目名) – 指定した名前の勘定科目のIDを返すメソッド

などを用意してあります。

freeeAPI.accountItems(accessToken, company_id).getIdByName('勘定科目名');

あまり使いませんが、上記のようなコードで勘定科目の名称からそのIDが何であるかを取得できたりします。

その他マスタ項目取得もできちゃいます

取引先
品目
部門
メモタグ
税区分

なども以下のコードでそれぞれシートに取得できます。シート名は、お好きな名称に変えて頂いてもOKです。

/* 取引先マスタシートに取引先をすべて取得する関数 */

function getPartnersMaster() {
  const accessToken = getService().getAccessToken();
  const company_id = *******; // 操作したい事業所のID
  freeeAPI.partners(accessToken, company_id).getPartners2Sheet('取引先マスタ');
}

/* 品目マスタシートに品目をすべて取得する関数 */

function getItemsMaster() {
  const accessToken = getService().getAccessToken();
  const company_id = *******; // 操作したい事業所のID
  freeeAPI.items(accessToken, company_id).getItems2Sheet('品目マスタ');
}

/* 部門マスタシートに部門をすべて取得する関数 */

function getSectionsMaster() {
  const accessToken = getService().getAccessToken();
  const company_id = *******; // 操作したい事業所のID
  freeeAPI.sections(accessToken, company_id).getSections2Sheet('部門マスタ');
}

/* メモタグマスタシートにメモタグをすべて取得する関数 */

function getTagsMaster() {
  const accessToken = getService().getAccessToken();
  const company_id = *******; // 操作したい事業所のID
  freeeAPI.tags(accessToken, company_id).getTags2Sheet('メモタグマスタ');
}

/* 税区分マスタシートに税区分をすべて取得する関数 */

function getTaxesMaster() {
  const accessToken = getService().getAccessToken();
  const company_id = *******; // 操作したい事業所のID
  freeeAPI.taxes(accessToken, company_id).getTaxes2Sheet('税区分マスタ');
}

これらは登録されているタグを全て取得するものばかりですが、品目・取引先・メモタグなどは、更新された日付などを指定して絞り込んで取得することもできます。

freeeAPI.partners
freeeAPI.items
freeeAPI.tags

で生成されたオブジェクトにはqueriesというプロパティを設定していて、会計リファレンスの各エンドポイントでパラメーター（≒ 絞り込み条件）として用意されているものは、このqueries以下のプロパティで指定できます。

以下は、取引先マスタの絞り込みの例です。

const freeeAPI_Partners = freeeAPI.partners(accessToken, company_id);
freeeAPI_Partners.queries.start_update_date = '2022-06-17';
freeeAPI_Partners.getPartners2Sheet('取引先マスタ');

一例ですが、GASのトリガー機能とあわせて、1週間以内に追加・更新された取引先を取得してチャットツールに通知するとかができます。