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

2022年5月24日 freeeAPI

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

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

事業所IDを取得したい

freee APIの操作でしばしば必要になるのが、事業所IDです。この事業所IDは、freeeにログイン後に右上の事業所名にカーソルを合わせた時に確認できる事業所番号とは別物です。残念ながらfreeeのUI画面では確認する方法はありません。

この事業所IDは、勘定科目、取引先、品目、税区分などなど…ありとあらゆるAPI操作で必要なパラメーターとなります。

ということで、早速取得していきたいと思います。

注意事項

GAS x freeeAPIライブラリ利用にあたっての注意事項です。

2022/05/23 現在こちらのライブラリはBeta版です（おそらくずっと…）。本ライブラリを使用したことによって発生したいかなる結果の責任は負いかねますので、使用者の自己責任にてのみご使用ください。

言うまでもなく会計・経理のデータは非常にセンシティブなので、事前にテスト事業所などでしっかりとテストを行った上で利用してください。現状、テスト甘めでアップデートしていっています。

使用者ご自身の経理業務、所属している企業の経理業務、税理士・会計事務所に所属する方が業務で使用する場合は、無償でご自由にお使いください。その他のケース（本ライブラリを利用して有償のサービスを提供する等）は、事前にご相談いただきますようお願い致します。

ログインアカウントで操作できる事業所はひとつか複数か

様々なユースケースがあるかと思いますが、個人や法人で経理業務でfreeeを使用されている方は、自身のアカウント（メールアドレス）に紐付けられている事業所はひとつということが多いと思います。

この場合ですと、事業所IDは一度取得してしまえば、あとは同じIDを使い続けるだけなので、毎回APIで取得する必要はありません。

プロパティストアなどに格納して、定数に代入して使うのが良いと思います。

士業の方や税理士・会計事業所にお勤めの方などの場合は、1つのアカウントで多くの事業所を操作している場合もあろうかと思います。この場合は、この事業所IDを簡単に取得できるメソッドは便利かなと思います。

とは言え、1つのスプレッドシート等で複数の事業所の操作をするのは、セキュリティ的にも意図しない間違いを生じさせないためにも避けたほうが良いかと思うので、こちらも最終的にはプロパティストアへの格納が正解かもしれません。

ライブラリを使用しないで事業所一覧を取得するには

これまたいつものように恩師の外部リンクで申し訳ないのですが、以下の記事の通りに進めれば、事業所の一覧の情報を格納したオブジェクトが取得できますので、そこから必要な情報を抽出することができます。

【はじめてのfreeeAPI】GASでリクエストを送りfreeeの事業所一覧を取得する

どういうことがバックグラウンドで行われているかのイメージは重要なので、オブジェクトの知識を習得した上で、こちらの記事を踏襲して実践してみることをオススメします。

その上で取得できた事業所情報オブジェクトの一覧を効率的に利用する方法を別途準備することで、実務上は大変効率化されます。

function getCompanyId() {

  // IDを取得した事業所の表示名
  const companyDisplayName = '開発用テスト事業所';

  //freeeAPIからアクセストークンを取得
  const accessToken = getService().getAccessToken();

  //事業所一覧を取得するリクエストURL  
  const requestUrl = 'https://api.freee.co.jp/api/1/companies';

  //freeeAPIへのリクエストに付与するパラメータ
  const params = {
    method: 'get',
    headers: { 'Authorization': 'Bearer ' + accessToken }
  };

  //リクエストを送信しレスポンス取得し、レスポンスから指定した事業所名に一致するIDをログ出力
  const response = UrlFetchApp.fetch(requestUrl, params).getContentText();
  const json = JSON.parse(response);
  const companies = json.companies;
  for (const company of companies) {
    if (company.display_name === companyDisplayName) { console.log(company.id) }
  }
}

上記のコードがライブラリを使用しない場合の事業所の表示名からIDをログ出力するスクリプトです。最後のconsole.log(company.id)の部分をreturn company.id としてcompanyDisplayNameとaccessTokenを引数として受け取る関数にすれば、表示名からIDが取得できます。

GAS x freeeAPIライブラリを使用してシンプルに

前述したコードと同様の働きをGAS x freeeAPIライブラリで実践するには、以下のように書きます。

function demoMyCompanyId() {
  const accessToken = getService().getAccessToken(); // アクセストークン

  /* 指定した名称の事業所IDを返すメソッド */
  const company_id = freeeAPI.myCompanies(accessToken).getMyCompanyId('開発用テスト事業所');
  console.log(company_id);

}

かなりスッキリしましたね。

煩雑になりやすいAPIのリクエスト関連のGASをライブラリにまとめることで、スッキリとシンプルなコードで、やりたいことが実現できてしまいます。

GAS x freeeAPIライブラリの基本的な構造・呼び出し方

GAS x freeeAPIライブラリでいろいろな操作をする場合は、上記の画像のようにコードを書きます。

freeeAPI → ライブラリの呼び出し
myCompanies(アクセストークン) → 事業所操作オブジェクトを生成するファクトリ関数
getMyCompanyId（事業所表示名） → MyCompaniesオブジェクトのメンバーである指定した名称（表示名）の事業所IDを返すメソッド

という3段階の流れで色々な処理を実行してくれます。

ライブラリの呼び出し部分はすべての操作対象のデータ種別で共通
操作オブジェクトは勘定科目、事業所、取引、請求書などデータ種別ごとに用意
データ種別ごとにいくつかの処理を実行してくれるメソッドを用意

という構造になっています。

事業所操作クラス（※クラスはオブジェクト生成の雛形）には、以下3つのメソッドを用意しています。

getMyCompanies() – 全ての事業所情報を配列で返すメソッド
getMyCompanyId(company_name) – 指定した名称の事業所IDを返すメソッド
getMyCompanies2Sheet(sheetName) – 指定したシート名のシートに事業所情報一覧を取得するメソッド

ライブラリに定義されているメソッドなどは、GASのコードの自動補完が使用できないので、以下のようなダミーの関数をdummy.gsのように別のgsファイルに用意しておくと便利です。

/* 050 freee事業所情報に関するクラス */

/**
 * MyCompaniesインスタンス生成後、全ての事業所情報を配列で返すメソッド
 * @return  {Array.<Object>}  aryCompanies - 全ての事業所オブジェクトを格納した配列
 */

function getMyCompanies() {
  throw new Error('MyCompaniesインスタンスを生成してから実行してください。');
}

/**
 * MyCompaniesインスタンス生成後、指定した名称の事業所IDを返すメソッド
 * @param   {string}  company_name - 事業所表示名
 * @return  {number}  company_id - 事業所ID
 */

function getMyCompanyId(company_name) {
  throw new Error('MyCompaniesインスタンスを生成してから実行してください。');
}

/**
 * MyCompaniesインスタンス生成後、指定したシート名のシートに事業所情報一覧を取得するメソッド
 * @param   {string}  sheetName - 事業所情報を取得したいシート名
 * @return  {SpreadsheetApp.Range} データ更新した範囲のRangeオブジェクト
 */

function getMyCompanies2Sheet(sheetName) {
  throw new Error('MyCompaniesインスタンスを生成してから実行してください。');
}

ライブラリの導入前の事前準備や導入の仕方などは、以下の記事をご参考ください。