freee APIで401が出続ける。原因は /api/1/companies の先頭を使っていたことだった
freee APIを使った督促ツールを作り、アプリストアの審査に出しています。
審査の事前確認フォームに提出するデモ画面を撮っていたら、アプリがまったく動かないことに気づきました。しかもエラーは1つも表示されていませんでした。
原因は2つ重なっていました。
/api/1/companies の先頭の事業所を保存していた(真因)
エラー時に自動リダイレクトしていたため、1が見えなかった
1は、事業所が1つしかない環境では絶対に再現しません。同じ踏み方をする人がいそうなので書きます。
・前回:freeeアプリストアに個人で申請するまで、結局いくらかかったか(https://zenn.dev/hachihou_system/articles/freee_api_tool)
・前々回:freee APIで督促ツールを作ろうとしたら、前提が5回崩れた(https://zenn.dev/hachihou_system/articles/freee-api-tokusoku)
作ったもの: https://tokusoku.onrender.com
症状:連携しても、連携画面に戻ってくる
デモ撮影のため連携し直したところ、こうなりました。
・アプリを開くと、待たずにfreeeの事業所選択画面へ飛ぶ
・事業所を選んで「許可する」を押すと、また同じ画面に戻る
・エラーメッセージは一切出ない
最初は無料プランのスリープを疑いました。Renderの無料プランは15分で停止するので、/callback が起動待ちに巻き込まれてコードを失っているのでは、と考えました。
外れでした。
切り分け:どこまでが正常か
推測を重ねる前に、事実を3つ取りました。
サーバーの応答(Cookieなし)
コマンドラインでトップページを取得すると、ランディングページのHTMLが正常に返りました。リダイレクトもしていません。サーバーは無実です。
/help を開く
正常に表示されました。問題は / だけです。
サーバーが正常で、/ だけがおかしい。差はCookieです。セッションがある状態でだけ挙動が変わる。つまりログイン済みとして扱われ、アプリ本体のHTMLが返っている。
APIを直接開く
ブラウザで /api/state を開きました。
{"error":"freeeへのアクセス権限がありません。","relogin":true}
出ました。画面には一度も出ていなかったエラーです。
原因その1:自動リダイレクトがエラーを隠していた
アプリ本体のJSにこれがありました。
if (d.relogin) { location.href = '/login'; return; }
「ログインが切れていたら、連携し直させる」という素直な実装のつもりでした。実際に起きたのはこれです。
/ → 画面 → /api/state が失敗
→ 自動で /login → freee認可 →「許可する」→ /callback(成功)
→ / → 画面 → /api/state がまた失敗 → 以下、無限
再認可では解決しない失敗を、再認可で直そうとしていました。
location.href で遷移するので、エラー本文は一瞬たりとも表示されません。利用者にも、開発者にも、何も伝わらない。
自己回復の仕組みは、回復しない失敗を1つでも含むと無限ループになります。そして画面遷移で隠れるので、原因に辿り着けません。
まず自動リダイレクトを外し、エラー本文と再連携ボタンを表示するように変えました。
原因その2:/api/1/companies は、連携していない事業所も返す
エラーを表示させたら、こう出ました。
freeeとの連携が切れています。再度連携してください。(/api/1/deals)
/api/1/deals が401。しかも /callback の中で呼んでいる /api/1/companies は成功しています(失敗していればエラー画面になっていた)。
同じトークンで、片方は通り、片方は401。
コールバックはこうなっていました。
comps = cl.get("/api/1/companies").get("companies", [])
c0 = comps[0] # ← 先頭を採っていた
freeeの認可画面には、こう書かれています。
あなた個人の情報の取得や所属事業所情報の取得
「八邦システム」以外の事業所の事業所名やログイン権限などの情報が含まれます
つまり /api/1/companies は、連携を許可していない事業所も返します。
私のアカウントには事業所が2つあり、先頭は開発用テスト事業所でした。利用者が別の事業所を選んでも、先頭のIDを保存してしまう。
・/api/1/companies … 一覧の取得自体は許可されている → 通る
・/api/1/deals?company_id=<許可していない事業所> → 401
「連携は成功したのに、以降のAPIが全滅する」という、分かりにくい壊れ方でした。
なぜ今まで動いていたのか
プライベートアプリで開発していた頃は、選ぶ事業所と先頭がたまたま一致していました。事業所が1つしかない開発環境では、この不具合は絶対に再現しません。
直し方
許可の有無を推測せず、freeeに聞くことにしました。
c0 = None
for c in comps:
try:
cl.get(f"/api/1/companies/{c['id']}") # 参照できるか試す
c0 = c
break
except ApiError:
continue
prompt=select_company を指定していても、どれが選ばれたかはトークンから直接は分かりません。実際に参照できるかどうかで判定するのが確実でした。
推測は外れていた
エラーを隠している間、私はこう考えていました。
パブリックアプリの「口座明細の参照」は銀行明細取得申請の承認が前提のはずだ。
申請は提出済みだが審査中。だから walletables が403になっているのだろう。
状況に合っていて、もっともらしい仮説でした。そして完全に外れていました。
エラーを表示させた瞬間に確定しました。所要時間は数十秒です。
推測を重ねる前に、まずエラーを見えるようにする。分かってはいたことですが、隠していたのが自分の書いたコードだったのが情けないところです。
ところで、403のリダイレクトは必須要件だった
自動リダイレクトを外した直後、審査フォームでこれを読みました。
承認されていない権限(スコープ)を必要とするAPIエンドポイントを呼び出した場合、403エラーが返却されるようになりました。
403エラーを検知した際の認可画面等へのリダイレクト機能が必須となりました
外したばかりの機能が、要件でした。
ただ、要求されているのは403のときです。今回のループは401で起きていました。分けて考えれば両立します。
・401(トークン切れ) … 再認可で直る可能性が高いが、直らないこともある → 遷移せず、理由を表示する
・403(権限不足) … 認可し直せば権限を追加できる → 認可画面へ遷移する
そのうえで、403側にも歯止めを入れました。
if (d.reauth) {
const last = +sessionStorage.getItem('reauth_at') || 0;
if (Date.now() - last > 60000) { // 60秒に1回まで
sessionStorage.setItem('reauth_at', Date.now());
location.href = '/login'; return;
}
}
// 60秒以内に再発 → 遷移せず、freeeが返した内容をそのまま表示する
要件は満たしつつ、認可しても解決しない場合に無限往復しない。同じ失敗を繰り返さないための最低限です。
403を意図的に起こす
審査には「実装されていること」を示す必要があります。しかし権限は必要なものだけを要求しているので、普通に使っていると403は起きません。
確認用の入口を用意しました。
if request.args.get("scope_test") == "1":
client_for(u).get("/api/1/invoices", {"company_id": u["company_id"]})
承認を受けていない /api/1/invoices をわざと呼びます。返ってきたのはこれでした。
{"error":"access_denied","message":"このアプリケーションにはアクセス権限がないエンドポイントです"}
freee自身の応答が画面に出るので、「403を検知している」ことを自分の主張ではなく事実として示せます。
提出物:「freee側画面」が存在しないアプリ
審査フォームは、動作確認としてこれを求めます。
③ 今回申請する主要な連携機能(データの取得や作成)を実行し、正しくfreee側で処理されたことがわかるfreee側画面まで
本アプリは参照のみで、freeeに一切書き込みません。該当する画面が存在しません。
黙って出せば「③が不足」で差し戻されます。提出PDFの1ページ目に理由を書きました。
更新・作成・削除の権限を一切要求していないため、freee側にデータを作成・変更する処理を行わず、
「freee側で処理されたことがわかるfreee側画面」は原理的に存在しません。
「出せません」ではなく「構造上存在しません、代わりにこれで示します」と書く。参照専用であることの説明そのものになるので、むしろ有利な材料だと考えました。
なお設問ごとに最大5ファイルという制限があります。画面キャプチャは22枚あったので、設問ごとに1本のPDFにまとめ、各ページに「この画面が何を示すか」の注釈を付けました。ファイル名にはアプリ名を入れ、個人名は入れない指定でした。
まとめ
今日直したのは3つです。
・発見を遅らせた原因:エラー時の自動リダイレクト。回復しない失敗があると無限ループになる
・未実装だった要件:403検知時の認可画面へのリダイレクト。ループ防止と両立させた
いま審査待ちです。フォームには「通常3週間〜4週間」とありました。
このまま気づかず審査されていたら、担当者の画面でも同じ無限ループが起きて、「起動しないアプリ」として差し戻されていたと思います。デモを撮るために自分で一通り触ったのが、結果的に唯一の検証機会でした。
使ってくれる方を探しています
前回も書きましたが、私は会社員で、自分の請求書がありません。未払いに困った当事者ではないので、このツールが本当に役に立つのかを自分では確かめられません。
パブリックアプリは審査の承認を待たずに20事業所まで利用できます。freee会計で掛売上(未決済取引)を登録している個人事業主・フリーランスの方で、試してもよいという方がいらっしゃればご連絡ください。
督促を実際に送っていただく必要はありません。連携して画面を開き、何が表示されたかを教えていただくだけで、私が自分では確かめられないことがほぼ分かります。
・権限は参照のみです。freeeの帳簿に書き込むことはできません
・取引先の情報はサーバーに保存していません
・設定画面からいつでも連携解除とデータ削除ができます
・使い方(https://tokusoku.onrender.com/help)
・利用規約(https://tokusoku.onrender.com/terms)
・プライバシーポリシー(https://tokusoku.onrender.com/privacy)
ご連絡は、この記事のコメント欄か Kyosuke.o@hachihou.onmicrosoft.com までお願いします。
※ 無料プランのため、初回アクセスは起動に50秒ほどかかります。