【GAS×freeeAPI】指定条件の取引一覧を取得する「リクエストURL」の作り方と仕組み

こんにちは！ITライターのもり(@moripro3)です！

クラウド会計ソフトfreeeのAPIを使って経理業務を自動化するネタをお届けしています。

このシリーズでは、freeeとチャットワークを連携して「当日入金予定の取引一覧を自動でチャットワークに送信するツール」を作成します。

成果物のイメージがこちら！入金予定のある日に、取引一覧が自動でチャットワークに届きます。

前回の記事では、ノンプログラミングでfreeeのデータをスプレッドシートに出力できる拡張機能「会計freee連携アドオン」を導入・使用しました。

ノンプログラミングでOK！「会計freee連携アドオン」でスプレッドシートにデータを取得する

【GAS×freeeAPI】「当日入金予定の取引一覧を自動でチャットワークに送信する」シリーズの第1回目。会計freee連携アドオンの導入方法・データの取得方法、および、GAS×freeeAPIとの違いを紹介しています。

今回の記事では、GASでfreeeAPIを操作してデータを取得するための「リクエストURL」の作成方法を紹介します。

freeeAPIリファレンスの「リクエストURL生成機能」の紹介
リクエストURLの仕組み（URLとパラメータ）

シリーズを通してfreeeAPIを使いこなし、経理業務の自動化を進めていきましょう！

（この記事はfreee株式会社さまとのコラボ企画です。シリーズを通して、皆さんの働くの価値を上げられるようサポートしていきます！）

データを取得するGETリクエスト
取引一覧を取得するリクエストURL
まとめ・次回予告
連載目次：【GAS×freeeAPI】当日入金予定の取引一覧を自動でチャットワークに送信する

データを取得するGETリクエスト

シリーズ1の記事で、APIを操作する4種類のリクエストを紹介しました。

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

GoogleAppsScriptでクラウド会計ソフトfreeeのAPIを操作するシリーズ。GETリクエストでfreeeの事業所一覧を取得するコードと、freeeAPIリファレンスの読み方を紹介しています。

GET「データの取得」
POST「データの作成」
PUT「データの更新」
DELETE「データの削除」

このツールで作るのは「取引データを取得する処理」なので、リクエストの種類は「GET」です。

シリーズ1で紹介した「事業所一覧を取得する」コードがこちらでした。

function getCompanies() {
  
  //freeeAPIのサービスからアクセストークンを取得
  var accessToken = getService().getAccessToken();
  
  //リクエストを送る時に付与するパラメータ
  var params = {
    "method" : "get",
    "headers" : {"Authorization":"Bearer " + accessToken}//Bearerの後ろに半角スペースが入る
  };
  
  //事業所一覧を取得するためのリクエストURL
  var requestUrl = 'https://api.freee.co.jp/api/1/companies';
  
  var response = UrlFetchApp.fetch(requestUrl, params);
  Logger.log(response);//レスポンスをログ出力
  
}

取引データを取得する場合も基本の流れは同じで、freeeAPIにアクセスするための「リクエストURL（変数requestUrl）」を変更するだけでOKです。

※freeeAPIを操作するためには、スプレッドシートとfreeeAPIの連携・認証などの作業が必要です。

シリーズ1の記事で設定方法を紹介しています。上記のスクリプトを実行してデータ取得を試してみたい方は、こちらの記事をご覧のうえ設定してみてください。

【はじめてのfreeeAPI】GASとfreeeをつなぐ！連携認証の手順を一から紹介します

GoogleAppsScriptでクラウド会計ソフトfreeeのAPIを操作するシリーズ。GASでfreeeを操作するために必要な「freeeマイアプリの作成」と「連携」の手順を、画面キャプチャ盛りだくさんで丁寧に紹介しています。

取引一覧を取得するリクエストURL

この項では、指定条件に合致する取引一覧を取得するための「リクエストURL」を作成します。

リクエストURLとは、APIにアクセスするためのURLです。操作内容や取得データによってURLが異なります。

リクエストパラメータ

リクエストURLを作成するために重要な「リクエストパラメータ」という単語を確認しておきましょう。

リクエストパラメータとは、リクエストを送る時に、URLに付与して一緒に送る「データ」です。

「データ」とは「条件」のことです。何も条件を指定しないと、すべてのデータを取得できます。「○○の条件に合致するデータをください」と指定することも可能です。

このツールの目的である「当日の入金予定の取引一覧」を取得するためには、下記4つの条件を「パラメータ」として付与します。

事業所ID
収支区分が「入金」
ステータスが「未決済」
支払期日が「当日日付」

リクエストパラメータを一から作るのは少々大変なので、freeeAPIリファレンスの「リクエストURL生成機能」を紹介します。

リクエストURLの自動生成機能

freeeAPIリファレンスのDeals（取引）にアクセスします。

「取引（収入／支出）一覧の取得」の項目をクリックして展開します。

「Try it out」をクリックします。

Descriptionの欄を見て、下記①～⑤を入力します。

①事業所ID「取得対象の事業所ID」を入力
②決済状況「unsettle」を選択
③収支区分「income」を選択
④-1「支払期日（開始日）」当日日付をyyyy-mm-dd形式で入力（例：2019-08-01）
④-2「支払期日（終了日）」④-1と同じ日付を入力
⑤取得レコードの件数（任意）
→デフォルト20件の設定であるため、ここでは最大件数の100を指定します

①～⑤まで入力したら「Execute」（実行）のボタンをクリックします。

※パラメータ名に赤文字で *required とあるものは必須パラメータです。「/deals 取引一覧の取得」ではcompany_idのみが必須指定です。

Request URLの欄に、指定の条件を含んだリクエストURLが生成されました。マウスのドラッグで範囲選択してコピーできます。

リクエストURLの仕組み

リファレンスの機能を使って、リクエストURLを簡単に生成することができました。

https://api.freee.co.jp/api/1/deals?company_id=9999999&status=unsettled&type=income&start_due_date=2019-08-01&end_due_date=2019-08-01&limit=100

これを一から作るのは大変なので、一から作るよりも「自動生成機能」を使った方がラクです。

ただ、freeeAPIを使いこなすためには、リクエストURLの仕組みは知っておいたほうがよいので、この項で詳しく解説していきます。

リクエストURLは「①URL」と「②パラメータ」の2つに分けて考えます。

①URL

URLの部分は2種の値で構成されています。

freeeAPI共通値：https://api.freee.co.jp/api/1
データ毎の固有値： /deals

取引データの固有値は /deals です。これはfreeeAPIリファレンスでも確認できます（赤枠部）

②パラメータ

取得したいデータの条件を記述します。ツールの条件を一覧にまとめます。

項目名	パラメータ名	値
事業所ID	company_id (*required)	取得対象の事業所ID
決済状況	status	unsettled
収支区分	type	income
支払期日（開始日）	start_due_date	当日日付（yyyy-mm-dd）
支払期日（終了日）	end_due_date	当日日付（yyyy-mm-dd）
取得最大件数	limit	省略した場合は20（ここでは最大値100とする）

これらのパラメータは、「パラメータ名」と「値」を = で結合して「パラメータ名=値」とし、それらを & で結合します。

パラメータ名=値&パラメータ名=値&　・・・　&パラメータ名=値

URLとパラメータを結合

URL（①）とパラメータ（②）は ? で結合します。

ここまでの条件をまとめると、リクエストURL全体の書式は以下のようになります。

URL?パラメータ名=値&パラメータ名=値&・・・&パラメータ名=値

具体例をみてみましょう。例えばパラメータが2つの場合、

パラメータ1：事業所ID(company_id) = 9999999
パラメータ2：決済状況(status) = unsettled(未決済)

リクエストURLはこうなります。

ここまで理解できたら、もう一度リクエストURL全体を見てみましょう。長くて複雑に感じますが、よく見ると、決まった条件で順番に結合しているだけなのです。

https://api.freee.co.jp/api/1/deals?company_id=9999999&status=unsettled&type=income&start_due_date=2019-08-01&end_due_date=2019-08-01&limit=100

まとめ・次回予告

「当日入金予定の取引一覧を自動でチャットワークに送信する」シリーズの第2回目では、これらを紹介しました。

freeeAPIリファレンスの「リクエストURL生成機能」の使い方
リクエストURLの作り方と仕組み
- 「URL」と「パラメータ」を ? で結合する
- 各パラメータは & で結合する（パラメータ名=値&パラメータ名=値）

さて、当日入金の取引一覧を取得するリクエストURLは作成できましたが、今のままでは「当日」が固定値になっています。

このツールは、スクリプトを日次で自動実行させるので、「支払期日」＝「スクリプト実行時の日付」となるようパラメータを設定する必要がありますね。

そこで次回は、これらの処理を紹介していきます。

スクリプト実行時の日付（当日日付）を取得する関数を作成し、リクエストURLの「支払期日」のパラメータを置き換える
freeeAPIにGETリクエストを送り、当日入金予定の取引一覧を取得する

【GAS×freeeAPI】GETリクエストで当日入金予定の取引一覧を取得する

「当日入金予定の取引一覧を自動でチャットワークに送信する」シリーズの第3回目。スクリプト実行時の「当日日付」を取得する関数を作成し、リクエストURLの日付パラメータを置き換え、GETリクエストでレスポンスを取得します。

連載目次：【GAS×freeeAPI】当日入金予定の取引一覧を自動でチャットワークに送信する

「クラウド会計ソフトfreee」のAPIをGASで操作して経理業務を自動化するシリーズ。「当日入金予定の取引一覧を自動でチャットワークに送信するツール」の作成を目標とします。