freee APIの使い方－事業所の選択について

ここでは、freee APIを活用したアプリを開発する際、設計と実装が必要な事業所選択機能について説明をします。

事業所の選択とは

freeeのユーザーは、1アカウント中に複数の事業所を持つことができます。（事業所とアカウントの関係についてはヘルプページ：freeeのアカウントについてをご覧ください。）アプリの利用を開始する際、ユーザーは（アプリが画面遷移を行い）認証用URLで表示された画面からアプリとの連携を認可します。この時、freeeがデフォルトで提供する認証用URLを使ってアプリが実装されていれば、ユーザーは複数の事業所から、アプリ連携を許可したい単一の事業所を選択することができます。ユーザーがアプリにアクセスをさせたい事業所を選ぶことを、「事業所の選択」と呼びます。

大半のアプリについては、freeeがアプリ管理画面で提供するデフォルトの認証用URLを用いて開発を行えば問題ありません。

事業所選択の画面 — freeeがデフォルトで提供する認証用URLから表示される”事業所選択画面”

（一度のログインで）アカウント内の複数事業所へのアクセスが必要なアプリの実装方法

アプリのユースケースによっては、一度のログインで、アカウント内の複数事業所へのアクセスを行いたい場合があります。この場合、アプリはデフォルトで表示されている認証用URLの末尾にある”&prompt=select_company”を削除した認証用URLを利用する必要があります。またその上で、開発者自身でアプリに事業所選択機能（ユーザーが事業所を意図的に指定できる機能）を実装する必要があります。これは利用者が意図しない事業所にデータを登録したり、参照したりしないようにするためです。

尚、freeeアプリストアにアプリを公開する場合は、審査時に”事業所選択”について考慮がされているかを確認します。考慮がされていない場合はアプリの公開を承認できません。そのためfreeeは、freeeがアプリ管理画面でデフォルトで提供する”事業所選択の機能が実装されている認証用URL”を利用して開発を行うことを推奨します。

項目	デフォルトの認証用URLを利用する場合	&prompt=select_companyを外した認証用URLを利用する場合（非推奨）
ユーザーがアプリ利用開始時に行う操作	アプリ連携を認可したい、アカウント内の一つの事業所を選択する。	アカウント内の全ての事業所に対するアクセスを認可する。
適切なユースケース	アプリがアカウント内の単一の事業所にのみアクセスができれば良い場合。	アプリがアカウント内の複数事業所にアクセスをする必要がある場合。例）アドバイザーが顧問先の管理に使うレポーティング系アプリで、1度のログインで事業所を切り替えながらデータを参照する。
注意点	アプリはユーザーが許可した一つの事業所にのみアクセスをすることができます。	freeeアプリストアにアプリを公開する場合は、審査時に事業所選択が考慮されているか確認し、考慮されていない場合はアプリの公開を承認できません。