認証フロー

以下にAPIを利用するために必要な事前認証の処理フローを３つの場面に分けて説明します。

用語	説明
ユーザー	アプリケーションを利用するユーザ
アプリケーションサーバ	貴社が提供するアプリケーションが稼働するサーバ
ネクストエンジンサーバー	弊社が提供するネクストエンジンアプリを管理するサーバ
APIサーバー	弊社が提供するネクストエンジンと連携するAPIサーバ
uid	アプリを起動したユーザーを識別するためのID
state	アプリを起動したユーザーのstate。stateには有効期限があります（５分）。有効期限が切れた場合は再取得する必要があります。
client_id	アプリを識別するためのID。ネクストエンジンの「アプリを作る」 -> 該当アプリの「編集」 -> 「API」タブにあるクライアントID
client_secret	アプリを識別するためのID。ネクストエンジンの「アプリを作る」 -> 該当アプリの「編集」 -> 「API」タブにあるシークレットクライアント
access_token	ネクストエンジンAPIを利用する為のトークン。有効期限は1日です。有効期限が切れた場合は再取得する必要があります。 refresh_tokenの期限が有効であれば、API実行時に自動で更新されます。
refresh_token	ネクストエンジンAPIを利用する為のトークン。有効期限は3日です。有効期限が切れた場合は再取得する必要があります。access_tokenが更新された場合、同時に更新されます。

ネクストエンジンにログイン後、ネクストエンジンのアプリメニューから起動した場合の処理の流れです。

番号	概要	備考
1	アプリを起動	アプリ登録時に設定した「Redirect URI」にURLパラメータuid, stateを付与した状態でリダイレクトします。
2	access_tokenの取得	uid, state, client_id, client_secretを元にAPIサーバーにaccess_token, refresh_tokenの発行を依頼します。
3	データアクセス	APIを用いてデータの取得・更新などを実行します。 access_tokenの有効期限が切れていてrefresh_tokenの有効期限内の場合は、実行結果と共に新しいaccess_tokenとrefresh_tokenを返却します。

アプリケーションサーバに直接アクセスした場合の処理の流れです。

番号	概要	備考
1	NEログインuid,state取得	client_idを元にネクストエンジンサーバーにuid及びstateの発行を依頼します。未ログイン状態の場合はログイン画面が返却されます。ログイン後、設定されているリダイレクトURLに遷移します。
2	access_tokenの取得	uid, state, client_id, client_secretを元にAPIサーバーにaccess_token, refresh_tokenの発行を依頼します。
3	データアクセス	APIを用いてデータの取得・更新などを実行します。 access_tokenの有効期限が切れていてrefresh_tokenの有効期限内の場合は、実行結果と共に新しいaccess_tokenとrefresh_tokenを返却します。

WEBアプリ以外でAPIを利用する場合（例：バッチ処理）

番号	概要	備考
1	アクセストークン取得	APIを利用するためにaccess_token,refresh_tokenを事前に取得します。取得方法は上記と同じです。
2	アクセストークンの保持	取得したaccess_token,refresh_tokenを保持しておきます。実装はアプリケーション側で用意してください。
3	バッチ処理の実行	APIを用いてデータの取得・更新などを実行します。 access_tokenの有効期限が切れていてrefresh_tokenの有効期限内の場合は、実行結果と共に新しいaccess_tokenとrefresh_tokenを返却します。 定期的にAPIへアクセスすることでaccess_tokenとrefresh_tokenの有効期限切れを防ぐ仕組みを作ることをお勧めします。

ネクストエンジンAPIにおけるrefresh_tokenについて

各エンドポイントにリクエストする際、access_tokenに加えrefresh_tokenも併用することで、初回ユーザー認証のみでAPIを利用し続ける事が出来るようになるパラメータです。

refresh_tokenの必要性

access_tokenのみの場合

access_tokenのみでネクストエンジンAPIを利用する事が出来ますが、access_tokenの有効期限が切れた際、ユーザーの認証(リダイレクト)が必要になり、アプリ側では処理の途中で有効期限が切れた際の考慮が必要になります。

(例えば受注更新->出荷確定を行うアプリの場合、受注更新後にaccess_tokenの有効期限が切れた場合は、ネクストエンジンサーバーへのリダイレクト後に出荷確定処理から戻れるように考慮する必要があります)

refresh_token併用時

access_tokenに加えrefresh_tokenも併用してネクストエンジンAPIを利用するとaccess_tokenの有効期限が切れた際、refresh_tokenの有効期限内であればその時実行したAPIが【正常終了】し、

新しいaccess_token及びrefresh_tokenが返却されます。

次回から新しいaccess_token及びrefresh_tokenを使う事で、初回ユーザー認証のみでAPIを利用する事が出来るようになります。

また処理の途中でaccess_tokenの有効期限が切れてもアプリの一連の処理が正常終了する為、一連の処理の途中で有効期限が切れてしまった際の考慮が不要になります。

そのためセキュリティ上の懸念(※)がある場合を除きrefresh_tokenを用いてネクストエンジンAPIを利用することを推奨致します。

※ 悪意のある攻撃者にユーザーのaccess_token、refresh_tokenが漏洩すると、ユーザーのデータが漏洩し続けてしまう可能性がありますaccess_token、refresh_tokenは漏洩しないように、細心のご注意をお願い致します。

利用方法

SDKを利用する方

自動的に認証され利用されます。

各エンドポイントにリクエスト後、access_token,refresh_tokenに変更があった場合はアプリ側でユーザ毎に保持する必要があります。（ネクストエンジンAPIからのレスポンス毎に保存するようにしてください）

以降はSDKのインスタンスを生成する時に、アプリ側で保存したaccess_tokenとrefresh_tokenを指定して下さい。

SDKを利用されない方

認証フローを参考にaccess_tokenの取得まで実施し、access_token及びrefresh_tokenを取得し目的のAPIを利用します。

各API利用後、access_token,refresh_tokenに変更があった場合は、アプリ側でユーザー(uid)毎にアプリ側で保持する必要があります。（APIを実行後、毎回保存しても問題ありません）

以降はAPIを利用する時に、アプリ側で保存したaccess_tokenとrefresh_tokenを指定して下さい。

補足説明

• access_tokenの有効期限は1日、refresh_tokenの有効期限は3日です。有効期限は、「最初にaccess_tokenを発行した日時、又は最後にaccess_tokenの有効期限が切れてaccess_tokenが更新された日時からの日数」です
• バッチ等認証なしで定期的にAPIを利用する場合、2日より前に定期的にAPIを実施し有効期限が切れないように利用することを推奨します（refresh_tokenの有効期限も切れた際は、access_tokenの有効期限切れと同じ002004のエラーになります。新しいaccess_tokenが発行されたにもかかわらず、古いaccess_tokenで実行した場合は、002002のエラーになります）
• 同一ユーザーに対してマルチスレッドでAPIを利用する事は推奨しません（access_token,refresh_tokenが更新されたタイミングで、同一ユーザーに対する全スレッドのaccess_token,refresh_tokenも更新された値に変更する必要があり、アプリ側のaccess_token,refresh_tokenの管理が困難になる為）
• access_token・refresh_tokenの更新は、リクエストがエラーになった場合も更新されます。access_token・refresh_tokenをアプリで保持する際はエラー時も保持するようにして下さい