こんにちは！ITライターのもり(@moripro3)です！
クラウド会計ソフトfreeeのAPIを使って経理業務を自動化する初心者向けシリーズ「はじめてのfreeeAPI」をお届けしています。
前回の記事では、GASでリクエストを送りfreeeの事業所一覧を取得しました。画面操作をせずに、直接freeeからデータを取得できましたね。
今回のテーマは「データの更新」です。「データの取得」に比べると少し作業量が増えますが、丁寧に解説していきますので、一緒に操作しながら試してみてください。
データ更新のお題「事業所情報を更新する」を通じて、これらの練習をしてみます。
- GASでfreeeにリクエストを送り、直接freeeのデータを更新する
- リクエストするデータの作り方（JSON形式）を理解する
画面操作ではなく、API操作でデータを更新する流れをみていきましょう！
（この記事はfreee株式会社さまとのコラボ企画です。シリーズを通して、皆さんの働くの価値を上げられるよう皆さまをサポートしていきます！）
（前回のおさらい）事業所IDの確認
前回の記事では、GETリクエストで事業所一覧を取得して「事業所ID」を確認しました。
※今回のお題「事業所情報を更新する」で「事業所ID」を使用しますので、事業所情報を未取得の方は、まず前回の記事をご確認ください。
freeeでは、1つのアカウントで複数の「事業所」を作成できるため、GASでfreeeAPIを操作するときには、どの事業所に対する処理かを指定するため「事業所ID」が必要になります。
リクエストとレスポンス
GASでfreeeAPIを操作するために理解しておくべき「２つの用語」も、再確認しておきましょう。
- リクエスト（要求）
- レスポンス（応答）
「リクエスト」とは、freeeのデータサーバに対して「～の処理をお願いします」と要求することで、その種類は4つあります。
- GET「取得」←前回記事のお題
- POST「作成」
- PUT「更新」←今回記事のお題
- DELETE「削除」
GETリクエストとPUTリクエストの違い
GETリクエストは「データをください」という依頼です。手紙に例えると、空の封筒に宛先だけを書いて送り、その封筒にデータを入れて返送してもらうイメージです。
それに対して、PUTリクエストは「データの更新」なので、更新したい「データ」を送る必要があります。
封筒に「データ」を入れて送り、処理の結果を返送してもらうイメージです。
※GETリクエストでも、封筒の側面に「～のデータ更新をお願い」と記述して送ることもできますが、セキュリティ上の問題があるのでやめておきましょう。（誰でもデータが見えてしまう「はがき」のイメージです）
APIでデータ更新するための準備
今回のお題は「PUTリクエストで事業所データを更新する」です。
まずは、今回新しく登場する用語「ボディ」を紹介します。ボディとは、APIにリクエストを送るときの「データ」のことです。
手紙で例えると、外から見えないように封筒の中に入れて送る書類です。
ボディ（body）とは「リクエストで送るデータのこと」と理解しておきましょう。
APIで更新可能な項目を確認する
freeeの事業所の項目はたくさんあります。
- 事業所名
- 電話番号
- 業種
- 法人番号 …他多数
API経由でどの項目が更新できるのかを、freeeAPIリファレンスで確認しましょう。リファレンスの該当項目「事業所情報の更新」をクリックして展開します。
Nameの列に2つの項目があります
- id *required（必須項目）
- Parameters
- ①id（path）＝リクエストURL（/companies/{id}）に付与するパラメータ
- ②Parameters（body）＝ボディ
→これが「freeeAPI経由で更新可能な項目」です。
「パラメータ例」とは「このような形式でボディを作成して送ってね」とfreeeAPIが指定してるものです。
「パラメータ」詳細をクリックして、各パラメータの内容を確認してみましょう。
APIで更新可能な項目名・example（サンプルデータ）・制約（最小/最大値）等を確認できます。
更新する項目を決める
freeeAPIリファレンスのパラメータ詳細の中から、どの項目を更新するか決めましょう。freeeにログインして、画面上で「設定」→「事業所の設定」を開きます。
当記事では、基本情報の「電話番号１」と「ファックス番号」をfreeeAPI経由で更新してみます。
もう画面開いちゃってるし、２項目だけなら画面で更新した方が早いじゃん！と思いますが…、当記事の目的は「GASでfreeeAPIを操作して、freeeのデータを更新してみること」なので、ぜひ皆さんもコードを書きながら試してみてください。
「電話番号１」と「ファックス番号」のパラメータ名を、freeeAPIリファレンスで確認します。パラメータ名とは、リクエストを送る時の項目名称です。
※画面の項目名とリファレンスの表記が異なる場合もあります
- 画面の項目名＝ファックス番号
- リファレンスの表記＝FAX
画面とリファレンスを照らし合わせると、このように確認できます。
リクエストURLを確認する
リクエストURLとは、APIにアクセスするためのURLです。操作したい内容によってURLが異なります。
freeeAPIでは、https://api.freee.co.jp/api/1 が固定値となり、それに続く部分が操作内容によって異なることを前回の記事でお伝えしました。
- 固定値 https://api.freee.co.jp/api/1
- 変動値 /companies/{id} ※id = 事業所ID
事業所IDが1234567の場合、リクエストURLはこのようになります。
ボディ（更新データ）を作成する
ここが今回の最大のポイントです。GASからfreeeに送るデータ「ボディ」を作成します。
GASでfreeeに送るデータはJSON形式です。JSONとは、JavaScriptでオブジェクトを記述するデータ形式です。
"パラメータ" : 値, "パラメータ" : 値, "パラメータ" : 値, ・・・
項目名・パラメータ名・値を整理すると下記のようになり、
| 画面上の項目名 | パラメータ名 | 値 |
|---|---|---|
| 電話番号１ | phone1 | （更新する値を設定） |
| ファックス番号 | fax | （更新する値を設定） |
これをJSON形式にして、変数に格納すればボディの完成です。変数名はbodyにしておきましょう。
var body = {
"phone1" : "11-1111-1111",
"fax" : "99-9999-9999"
};
以上で、データ更新に必要な情報が揃いました！
事業所情報を更新するコード
PUTリクエストを送るための準備が整いました。一部説明が必要なコードは次の項で解説しますので、まずはコードを実行してみましょう。
function updateCompany() {
//freeeAPIのサービスからアクセストークンを取得
var accessToken = getService().getAccessToken();
//freeeに送信するデータ(JSON形式のオブジェクト)
var body = {
"phone1": "11-1111-1111",//電話番号１
"fax": "99-9999-9999"//FAX
};
//リクエストに付与するパラメータ
var params = {
"method" : "put",
"contentType" : "application/json", //データの形式を指定
"headers" : {"Authorization":"Bearer " + accessToken}, //Bearerの後ろに半角スペース
"payload" : JSON.stringify(body), //データ本文（オブジェクトをJSON文字列に変換）
muteHttpExceptions : true //エラーが発生した場合、レスポンスにエラー全文を出力する
};
//リクエストURL(事業所IDxxxxxxxは各自設定)
var requestUrl = 'https://api.freee.co.jp/api/1/companies/xxxxxxx';
var response = UrlFetchApp.fetch(requestUrl, params);
Logger.log(response);
}
レスポンスを確認します。レスポンスには全項目が記述されており、”phone1”と”fax”の値を見ると、リクエスト通りの値になっていることが確認できます。
freeeの画面をF5で再読込みをすると、２項目が更新できているのが確認できます。
画面をまったく触らずに、API経由で事業所情報の更新ができました。今回の目的「GASでfreeeAPIを操作して、freeeのデータを更新する」が成功です！
リクエストに付与するパラメータ
上記コードの一部を解説します。変数paramsに、リクエストに必要な5つのパラメータを格納しています。
| パラメータ | 設定値 |
|---|---|
| method | リクエストの種類、ここでは”put”を指定 |
| contentType | コンテンツのタイプ、”application/json”を指定 |
| headers | Authorizationの値に”Bearer”という文字列＋アクセストークン |
| payload | ボディ（※送信するデータ本文をJSON文字列に変換する） |
| muteHttpExceptions | デフォルトはfalse、trueにすると、エラーが発生した場合レスポンスにエラーの全容が出力される |
var params = {
"method" : "put",
"contentType" : "application/json", //データの形式を指定
"headers" : {"Authorization":"Bearer " + accessToken}, //Bearerの後ろに半角スペース
"payload" : JSON.stringify(body), //データ本文（オブジェクトをJSON文字列に変換）
muteHttpExceptions : true //エラーが発生した場合、レスポンスにエラー全文を出力する
};
ポイントは、payloadの値に「JSON文字列」を設定することです。変数bodyはJSON形式の「オブジェクト」であるため、stringifyメソッドで「文字列」に変換します。
リクエストに失敗した場合
API通信では、リクエストに何らかの誤りがある場合でも、その結果が返ってきます。レスポンス（結果）にエラーメッセージが書かれているので確認しましょう。
たとえば、「ボディ」のパラメータ ”fax” に全角ひらがな “あいうえお” をセットしてリクエストしてみると、
var body = {
"phone1": "11-1111-1111",//電話番号１
"fax": "あいうえお"//FAX
};
このようなレスポンスが返ってくるので、「半角数字で入力してください」とエラーの内容が確認できます。
リファレンスにも「レスポンスサンプル」が載っているので、参考までにご覧ください。
以上が、GASでfreeeAPIを操作してデータを更新する一連の流れです。
まとめ
連載「はじめてのfreee API」の第4回目では、これらを紹介しました。
- GASでfreeeAPIを操作して、freeeのデータを更新する流れ
- リクエストするデータの作り方（JSON形式）
画面を操作することなくデータの取得・更新ができるAPIの仕組みは素晴らしいですね。この仕組みを活用すれば、色々な作業が効率化できます。
freeeに取引を登録する場合、画面で一件ずつ登録するのは時間がかかります。CSVインポート機能もありますが、スプレッドシートのデータをCSV形式に変換する手間もあります。そんな時に、GASとfreeeAPIを使って、スプレッドシートのデータをそのまま一括登録できたら便利ですね。
ぜひ、GAS × freeeAPIを習得して、経理業務の自動化に役立ててみてください。
これにて「はじめてのfreee API」シリーズは最終回です。お読みいただきありがとうございました。
次シリーズから実践編を紹介していきます。どうぞお楽しみに！
連載目次：【GAS初心者向け】はじめてのfreeeAPI
GoogleAppsScriptを使用して「クラウド会計ソフトfreee」のAPIを操作する初心者向けシリーズ。GAS × freee APIで何ができるのか？連携方法は？を紹介しています。実際にfreee APIを操作してデータの取得・更新をしてみましょう。
