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

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

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

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

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

freeeシリーズ2成果物イメージ

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

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

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

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

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

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

スポンサーリンク

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

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

【はじめてのfreeeAPI】GASでリクエストを送りfreeeの事業所一覧を取得する
GoogleAppsScriptでクラウド会計ソフトfreeeのAPIを操作するシリーズ。GETリクエストでfreeeの事業所一覧を取得するコードと、freeeAPIリファレンスの読み方を紹介しています。
  1. GET「データの取得」
  2. POST「データの作成」
  3. PUT「データの更新」
  4. 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を作成するために重要な「リクエストパラメータ」という単語を確認しておきましょう。

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

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

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

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

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

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

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

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

freeeAPIリファレンスの項目を展開する

 

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

リクエストURLを作成するためのTryitout

 

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

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

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

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

リクエストURLのパラメータ入力1
リクエストURLのパラメータ入力2
リクエストURLのパラメータ入力3

 

Request URLの欄に、指定の条件を含んだリクエスト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リファレンスでも確認できます(赤枠部)

リクエストURLのデータ毎の値を確認する

②パラメータ

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

項目名 パラメータ名
事業所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はこうなります。

HTTP通信のリクエスト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で操作して経理業務を自動化するシリーズ。「当日入金予定の取引一覧を自動でチャットワークに送信するツール」の作成を目標とします。

  1. ノンプログラミングでOK!「会計freee連携アドオン」でスプレッドシートにデータを取得する
  2. 【GAS×freeeAPI】指定条件の取引一覧を取得する「リクエストURL」の作り方と仕組み
  3. 【GAS×freeeAPI】GETリクエストで当日入金予定の取引一覧を取得する
  4. 【GAS×freeeAPI】APIリクエストのレスポンスから必要データのみを取り出す
  5. 【GAS×freeeAPI】オブジェクトからデータを取り出してスプレッドシートに書き出す
  6. 【GAS×freeeAPI】スプレッドシートのデータからチャットワーク通知用の本文を作成する
  7. 【GAS×freeeAPI】当日入金予定の取引一覧を毎日自動でチャットワークに送信する
タイトルとURLをコピーしました