こんにちは！ITライターのもり(@moripro3)です！
クラウド会計ソフトfreeeのAPIを使って経理業務を自動化するネタをお届けしています。
このシリーズでは、freeeとチャットワークを連携して「当日入金予定の取引一覧を自動でチャットワークに送信するツール」を作成します。
成果物のイメージがこちら！入金予定のある日に、取引一覧が自動でチャットワークに届きます。
前回の記事では、ノンプログラミングでfreeeのデータをスプレッドシートに出力できる拡張機能「会計freee連携アドオン」を導入・使用しました。
今回の記事では、GASでfreeeAPIを操作してデータを取得するための「リクエストURL」の作成方法を紹介します。
- freeeAPIリファレンスの「リクエストURL生成機能」の紹介
- リクエストURLの仕組み（URLとパラメータ）
シリーズを通してfreeeAPIを使いこなし、経理業務の自動化を進めていきましょう！
（この記事はfreee株式会社さまとのコラボ企画です。シリーズを通して、皆さんの働くの価値を上げられるようサポートしていきます！）
データを取得するGETリクエスト
シリーズ1の記事で、APIを操作する4種類のリクエストを紹介しました。
- 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の記事で設定方法を紹介しています。上記のスクリプトを実行してデータ取得を試してみたい方は、こちらの記事をご覧のうえ設定してみてください。
取引一覧を取得するリクエスト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を簡単に生成することができました。
これを一から作るのは大変なので、一から作るよりも「自動生成機能」を使った方がラクです。
ただ、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全体の書式は以下のようになります。
具体例をみてみましょう。例えばパラメータが2つの場合、
- パラメータ1：事業所ID(company_id) = 9999999
- パラメータ2：決済状況(status) = unsettled(未決済)
リクエストURLはこうなります。
ここまで理解できたら、もう一度リクエストURL全体を見てみましょう。長くて複雑に感じますが、よく見ると、決まった条件で順番に結合しているだけなのです。
まとめ・次回予告
「当日入金予定の取引一覧を自動でチャットワークに送信する」シリーズの第2回目では、これらを紹介しました。
- freeeAPIリファレンスの「リクエストURL生成機能」の使い方
- リクエストURLの作り方と仕組み
- 「URL」と「パラメータ」を ? で結合する
- 各パラメータは & で結合する（パラメータ名=値&パラメータ名=値）
さて、当日入金の取引一覧を取得するリクエストURLは作成できましたが、今のままでは「当日」が固定値になっています。
このツールは、スクリプトを日次で自動実行させるので、「支払期日」＝「スクリプト実行時の日付」となるようパラメータを設定する必要がありますね。
そこで次回は、これらの処理を紹介していきます。
- スクリプト実行時の日付（当日日付）を取得する関数を作成し、リクエストURLの「支払期日」のパラメータを置き換える
- freeeAPIにGETリクエストを送り、当日入金予定の取引一覧を取得する
連載目次：【GAS×freeeAPI】当日入金予定の取引一覧を自動でチャットワークに送信する
「クラウド会計ソフトfreee」のAPIをGASで操作して経理業務を自動化するシリーズ。「当日入金予定の取引一覧を自動でチャットワークに送信するツール」の作成を目標とします。
- ノンプログラミングでOK！「会計freee連携アドオン」でスプレッドシートにデータを取得する
- 【GAS×freeeAPI】指定条件の取引一覧を取得する「リクエストURL」の作り方と仕組み
- 【GAS×freeeAPI】GETリクエストで当日入金予定の取引一覧を取得する
- 【GAS×freeeAPI】APIリクエストのレスポンスから必要データのみを取り出す
- 【GAS×freeeAPI】オブジェクトからデータを取り出してスプレッドシートに書き出す
- 【GAS×freeeAPI】スプレッドシートのデータからチャットワーク通知用の本文を作成する
- 【GAS×freeeAPI】当日入金予定の取引一覧を毎日自動でチャットワークに送信する
