【はじめてのfreeeAPI】GASでリクエストを送りfreeeの事業所情報を更新する


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

クラウド会計ソフトfreeeのAPIを使って経理業務を自動化する初心者向けシリーズ「はじめてのfreeeAPI」をお届けしています。

前回の記事では、GASでリクエストを送りfreeeの事業所一覧を取得しました。画面操作をせずに、直接freeeからデータを取得できましたね。

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

今回のテーマは「データの更新」です。「データの取得」に比べると少し作業量が増えますが、丁寧に解説していきますので、一緒に操作しながら試してみてください。

データ更新のお題「事業所情報を更新する」を通じて、これらの練習をしてみます。

  • GASでfreeeにリクエストを送り、直接freeeのデータを更新する
  • リクエストするデータの作り方(JSON形式)を理解する

画面操作ではなく、API操作でデータを更新する流れをみていきましょう!

freeeの画面操作とAPI操作の比較

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

(前回のおさらい)事業所IDの確認

前回の記事では、GETリクエストで事業所一覧を取得して「事業所ID」を確認しました。

※今回のお題「事業所情報を更新する」で「事業所ID」を使用しますので、事業所情報を未取得の方は、まず前回の記事をご確認ください。

freee事業所IDの確認

freeeでは、1つのアカウントで複数の「事業所」を作成できるため、GASでfreeeAPIを操作するときには、どの事業所に対する処理かを指定するため「事業所ID」が必要になります。

リクエストとレスポンス

GASでfreeeAPIを操作するために理解しておくべき「2つの用語」も、再確認しておきましょう。

  1. リクエスト(要求)
  2. レスポンス(応答)

    「リクエスト」とは、freeeのデータサーバに対して「~の処理をお願いします」と要求することで、その種類は4つあります。

    1. GET「取得」←前回記事のお題
    2. POST「作成」
    3. PUT「更新」←今回記事のお題
    4. DELETE「削除」

    GETリクエストとPUTリクエストの違い

    GETリクエストは「データをください」という依頼です。手紙に例えると、空の封筒に宛先だけを書いて送り、その封筒にデータを入れて返送してもらうイメージです。

    GETリクエストのイメージ

    それに対して、PUTリクエストは「データの更新」なので、更新したい「データ」を送る必要があります。

    封筒に「データ」を入れて送り、処理の結果を返送してもらうイメージです。

    PUTリクエストのイメージ

    ※GETリクエストでも、封筒の側面に「~のデータ更新をお願い」と記述して送ることもできますが、セキュリティ上の問題があるのでやめておきましょう。(誰でもデータが見えてしまう「はがき」のイメージです)

    GETリクエストでデータを送らない

    APIでデータ更新するための準備

    今回のお題は「PUTリクエストで事業所データを更新する」です。

    まずは、今回新しく登場する用語「ボディ」を紹介します。ボディとは、APIにリクエストを送るときの「データ」のことです。

    手紙で例えると、外から見えないように封筒の中に入れて送る書類です。

    HTTPリクエストのボディのイメージ

    ボディ(body)とは「リクエストで送るデータのこと」と理解しておきましょう。

    APIで更新可能な項目を確認する

    freeeの事業所の項目はたくさんあります。

    • 事業所名
    • 電話番号
    • 業種
    • 法人番号 …他多数

    API経由でどの項目が更新できるのかを、freeeAPIリファレンスで確認しましょう。リファレンスの該当項目「事業所情報の更新」をクリックして展開します。

    freeeAPIリファレンスの事業所情報の更新

    Nameの列に2つの項目があります

    1. id *required(必須項目)
    2. Parameters
    • ①id(path)=リクエストURL(/companies/{id})に付与するパラメータ
    • Parameters(body)=ボディ
      →これが「freeeAPI経由で更新可能な項目」です。

    事業所情報更新のidとparameters

    「パラメータ例」とは「このような形式でボディを作成して送ってね」とfreeeAPIが指定してるものです。

    「パラメータ」詳細をクリックして、各パラメータの内容を確認してみましょう。

    事業所情報の更新のパラメータ例

    APIで更新可能な項目名・example(サンプルデータ)・制約(最小/最大値)等を確認できます。

    freeeAPIリファレンスの項目説明

    更新する項目を決める

    freeeAPIリファレンスのパラメータ詳細の中から、どの項目を更新するか決めましょう。freeeにログインして、画面上で「設定」→「事業所の設定」を開きます。

    freee事業所の設定

     

    当記事では、基本情報の「電話番号1」と「ファックス番号」をfreeeAPI経由で更新してみます。

    freeeの基本情報

     

    もう画面開いちゃってるし、2項目だけなら画面で更新した方が早いじゃん!と思いますが…、当記事の目的は「GASでfreeeAPIを操作して、freeeのデータを更新してみること」なので、ぜひ皆さんもコードを書きながら試してみてください。

    「電話番号1」と「ファックス番号」のパラメータ名を、freeeAPIリファレンスで確認します。パラメータ名とは、リクエストを送る時の項目名称です。

    freeeAPIリファレンスのパラメータ名と説明

    ※画面の項目名とリファレンスの表記が異なる場合もあります

    • 画面の項目名=ファックス番号
    • リファレンスの表記=FAX

    画面とリファレンスを照らし合わせると、このように確認できます。

    freee事業所情報の電話番号とFAX

    リクエストURLを確認する

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

    freeeAPIリファレンスの事業所情報

    freeeAPIでは、https://api.freee.co.jp/api/1 が固定値となり、それに続く部分が操作内容によって異なることを前回の記事でお伝えしました。

    • 固定値 https://api.freee.co.jp/api/1
    • 変動値 /companies/{id}  ※id = 事業所ID

    事業所IDが1234567の場合、リクエストURLはこのようになります。

    ボディ(更新データ)を作成する

    ここが今回の最大のポイントです。GASからfreeeに送るデータ「ボディ」を作成します。

    PUTリクエストのデータを作る

    GASでfreeeに送るデータはJSON形式です。JSONとは、JavaScriptでオブジェクトを記述するデータ形式です。

    項目名・パラメータ名・値を整理すると下記のようになり、

    画面上の項目名 パラメータ名
    電話番号1 phone1 (更新する値を設定)
    ファックス番号 fax (更新する値を設定)

    これをJSON形式にして、変数に格納すればボディの完成です。変数名はbodyにしておきましょう。

    以上で、データ更新に必要な情報が揃いました!

    事業所情報を更新するコード

    PUTリクエストを送るための準備が整いました。一部説明が必要なコードは次の項で解説しますので、まずはコードを実行してみましょう。

    レスポンスを確認します。レスポンスには全項目が記述されており、”phone1”と”fax”の値を見ると、リクエスト通りの値になっていることが確認できます。

    PUTリクエスト正常終了のログ

    freeeの画面をF5で再読込みをすると、2項目が更新できているのが確認できます。

    freeeAPIでPUTリクエストの結果

    画面をまったく触らずに、API経由で事業所情報の更新ができました。今回の目的「GASでfreeeAPIを操作して、freeeのデータを更新する」が成功です!

    リクエストに付与するパラメータ

    上記コードの一部を解説します。変数paramsに、リクエストに必要な5つのパラメータを格納しています。

    パラメータ 設定値
    method リクエストの種類、ここでは”put”を指定
    contentType コンテンツのタイプ、”application/json”を指定
    headers Authorizationの値に”Bearer”という文字列+アクセストークン
    payload ボディ(※送信するデータ本文をJSON文字列に変換する)
    muteHttpExceptions デフォルトはfalse、trueにすると、エラーが発生した場合レスポンスにエラーの全容が出力される

    ポイントは、payloadの値に「JSON文字列」を設定することです。変数bodyはJSON形式の「オブジェクト」であるため、stringifyメソッドで「文字列」に変換します。

    JSON.stringify(オブジェクト)

    リクエストに失敗した場合

    API通信では、リクエストに何らかの誤りがある場合でも、その結果が返ってきます。レスポンス(結果)にエラーメッセージが書かれているので確認しましょう。

    リクエストでエラーメッセージが返ってくる

    たとえば、「ボディ」のパラメータ ”fax” に全角ひらがな “あいうえお” をセットしてリクエストしてみると、

    このようなレスポンスが返ってくるので、「半角数字で入力してください」とエラーの内容が確認できます。

    リクエストのエラーメッセージ

    リファレンスにも「レスポンスサンプル」が載っているので、参考までにご覧ください。

    freeeAPIリファレンスのエラーサンプル

    以上が、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を操作してデータの取得・更新をしてみましょう。

    1. 【はじめてのfreeeAPI】GAS×freeeAPIで経理業務を自動化する最初の一歩!
    2. 【はじめてのfreeeAPI】GASとfreeeをつなぐ!連携認証の手順を一から紹介します
    3. 【はじめてのfreeeAPI】GASでリクエストを送りfreeeの事業所一覧を取得する
    4. 【はじめてのfreeeAPI】GASでリクエストを送りfreeeの事業所情報を更新する

      投稿者プロフィール

    もり
    もりITライター
    GoogleAppsScript, VBAを専門とするITライターです。

    退屈なことはプログラミングで片づけよう!
    自らの事務職経験を活かし、事務作業をとことんラクにできるITネタを発信していきます。

    個人ブログ『もりさんのプログラミング手帳』も運営中!

    お気軽にTwitterフォローしてくださいね!

    タイトルとURLをコピーしました