ここでは、freee APIを活用したアプリを開発する際、設計と実装が必要な事業所選択機能について説明をします。
事業所の選択とは
freeeのユーザーは、1アカウント中に複数の事業所を持つことができます。（事業所とアカウントの関係についてはヘルプページ：freeeのアカウントについてをご覧ください。）アプリの利用を開始する際、ユーザーは（アプリが画面遷移を行い）認証用URLで表示された画面からアプリとの連携を認可します。この時、freeeがデフォルトで提供する認証用URLを使ってアプリが実装されていれば、ユーザーは複数の事業所から、アプリ連携を許可したい単一の事業所を選択することができます。ユーザーがアプリにアクセスをさせたい事業所を選ぶことを、「事業所の選択」と呼びます。
大半のアプリについては、freeeがアプリ管理画面で提供するデフォルトの認証用URLを用いて開発を行えば問題ありません。
（一度のログインで）アカウント内の複数事業所へのアクセスが必要なアプリの実装方法
アプリのユースケースによっては、一度のログインで、アカウント内の複数事業所へのアクセスを行いたい場合があります。この場合、アプリはデフォルトで表示されている認証用URLの末尾にある”&prompt=select_company”を削除した認証用URLを利用する必要があります。またその上で、開発者自身でアプリに事業所選択機能（ユーザーが事業所を意図的に指定できる機能）を実装する必要があります。これは利用者が意図しない事業所にデータを登録したり、参照したりしないようにするためです。
尚、freeeアプリストアにアプリを公開する場合は、審査時に”事業所選択”について考慮がされているかを確認します。考慮がされていない場合はアプリの公開を承認できません。そのためfreeeは、freeeがアプリ管理画面でデフォルトで提供する”事業所選択の機能が実装されている認証用URL”を利用して開発を行うことを推奨します。
| 項目 | デフォルトの認証用URLを 利用する場合 | &prompt=select_companyを外した認証用URLを 利用する場合（非推奨） |
|---|---|---|
| ユーザーがアプリ利用開始時に行う操作 | アプリ連携を認可したい、アカウント内の一つの事業所を選択する。 | アカウント内の全ての事業所に対するアクセスを認可する。 |
| 適切なユースケース | アプリがアカウント内の単一の事業所にのみアクセスができれば良い場合。 | アプリがアカウント内の複数事業所にアクセスをする必要がある場合。 例）アドバイザーが顧問先の管理に使うレポーティング系アプリで、1度のログインで事業所を切り替えながらデータを参照する。 |
| 注意点 | アプリはユーザーが許可した一つの事業所にのみアクセスをすることができます。 | freeeアプリストアにアプリを公開する場合は、審査時に事業所選択が考慮されているか確認し、考慮されていない場合はアプリの公開を承認できません。 |
freeeが提供する事業所選択の機能について
認証用URLの末尾で&prompt=select_companyを指定すると、アプリ開発者は事業所選択の機能を自身で実装する必要がありません。freeeが提供する事業所選択機能を利用することができます。
ユーザーが複数事業所に所属している場合、ユーザーは事業所選択画面に遷移してから、事業所を選択後に認可画面に遷移し認可します。
ユーザーが単一の事業所にのみ所属している場合は、事業所選択画面は表示されず、直接認可画面に遷移し認可を行います。
上記の遷移で認可した場合にはtokenレスポンスにcompany_idというパラメータが含まれます。
事業所を指定するAPIの場合、上記トークンレスポンスによって返却されたcompany_idを指定してアクセスする必要があります。そのため、company_idをトークンと共に保存して下さい。
上記の遷移におけるアプリからのアクセスが可能となる情報の詳細について
- ユーザー情報及び、所属している事業所名、権限は選択した事業所に関係なくアクセスが可能です。
- 事業所の詳細情報(アプリストアでアプリ開発者が設定したリソース)は選択した事業所でのみアクセスが可能です。
&prompt=select_companyを外した場合の事業所選択の実装について
※認証用URLの末尾で&prompt=select_companyを指定し、freeeが提供する事業所選択機能を有効にしている場合は、本項の考慮は不要です。
前述のとおり、ユーザーによっては複数の事業所へのAPIコールが可能となるため、連携設定時にアクセス対象の事業所をユーザーが選択するプロセスが必要です。
具体的には、API認可後の操作でユーザーがアクセス対象の事業所を選択する機能を実装する必要があります。
freeeアプリストアにアプリを公開する場合は、審査時にこの仕様が考慮されているか確認し、考慮されていない場合はアプリの公開を承認できませんのでご注意ください。
以下は、リピート取引登録アプリの例です。
