はじめに

今回、お仕事でfreee関連のツール作成を任命されました。そのため、freee APIを使うわけなのですが、どうも「403：アクセス権限がありません」的なエラーが出て先に進めません。このエラーで3日潰したので、きっと他にも困っている人がいるだろう...と思い、記事を書くことにしました。
ちなみに、筆者はゲームエンジニア(レベルデザイナー)です。

環境

どこまで書くべきか...
・freee API(人事労務)
・OAuth2.0
・GAS

問題

UrlFetchAppでfreee API(employees)を呼び出そうとしたが、「403：アクセス権限がありません」的なエラーが出る。

解決

(1) 権限(スコープ)が適切でない

例えば、employeeｓの場合、GETメソッドのため「従業員：参照」にだけチェックが入っていれば使えるはずです。これの設定が適切でない可能性があります。
freee API 人事労務

freee アプリストアアプリ管理画面

(2) リクエストURLが不正(筆者はこっち)

私は最初、以下のように書いていました。

function getEmployees() {
  const company_id = 00000000;//必要に応じて変えてください
  const accessToken = getService().getAccessToken();

  const options = {
    method: "get",
    headers: {
      'Authorization': 'Bearer ' + accessToken
    },
    payload:{
      'company_id': company_id
    }
  };

  const response = UrlFetchApp.fetch(`https://api.freee.co.jp/hr/api/v1/companies/${company_id}/employees`, options);
  const response_json = JSON.parse(response);
  return response_json;
}

これだと、「403：アクセス権限がありません」となってしまいます。
何がダメかというと、payloadを指定していることです。freee APIの中にも指定するやつはありますが、今回は不要なタイプです。
freee APIのemployeesを見直してみましょう。

つまり、パラメータの投げ方はこんな感じです。

パラメータ	投げ方
limit	クエリストリングで投げろ
offset	クエリストリングで投げろ
company_id	パスで投げろ(つまりURLの{company_id}に代入で満たしている)
with_no_payroll_calculation	クエリストリングで投げろ

そのため、payloadは使えないわけです。

ちなみに、payloadを使うパターンは「Request body」について言及がある時です。
以下は、freee API(会計)のdeals(POST)の例です。

最後に

いかがだったでしょうか。今回は、freee APIで起きた問題と正しい使い方について紹介しました。
私個人の感想ですが、freee APIはもうちょっと使いやすくするべきでは...？と思ってしまいます。というのも、freeeを使うのは会社の中でも人事や会計の人であり、非エンジニアでも使える設計にした方がいいわけです。一端のエンジニア(といってもレベルデザイナー)が3日も溶かして詰まったわけです。クエリストリングとかpayloadとか...少なくともGASとの連携が便利ですを謳っているなら、コードでの実例は欲しいところです。使いこなせれば便利なことに間違いないので、今後のfreee APIに期待です。

今回のように、Web APIの使い方や、GAS側の使い方、Unityの使い方など幅広く紹介していく予定です。
お役に立てましたら、いいね・LGTM・フォローの方、よろしくお願いします！