開発をはじめる方へ
ドキュメント
お問い合わせ

aggregation_statusの一覧

口座情報を返すAPIのaggregation_statusの値一覧及び説明

Suggest Edits

ゲストユーザー様が、口座情報をMoneytreeに登録するには、 まず、Moneytreeの画面で、登録する各金融サービスに認証情報を入力したり、金融機関様ご提供のOpen APIにおいては、認証認可をしていただく必要があります。その際、ウェブサイトにログインするユーザネームやパスワードなどを入力いただいた後に、さらに合言葉などの追加認証が求められる場合もあります。

successのステータスになるまで（つまり無事に口座情報の取得ができるまで）極力Moneytree LINKの画面で誘導しますが、仮に無事に接続したとしても、時間が経つことに連れて、または個別の事情によって登録が通常運用のステータスから外れることもありますので、口座一覧のAPIを呼ばれる時に、aggregation_statusとして可能な値を一覧化しております。

🚧

aggregation_statusの追加について

アグリゲーションするサービスの種類の多様化、および実装ロジックの改善・向上などの理由から、aggregation_statusで戻ってくる値が、将来追加される可能性があります。その場合、事前に通知する努力はいたしますが、そちらのMT LINK APIの実装に当たって新しい値が返される可能性があります。そうした場合でも、可能な限り、ハンドリングできるように実装してください。

通常系のステータス

通常はとある登録（そして紐付いている口座）がsuccessのステータスにあります。これは、以前無事にデータを取得している意味です。Request Refresh APIのご利用及びお客様による行動によって、都度にデータを取得することになり、ステータスがrunning.*になることが通常運用上あります。

Aggregation Status内容Moneytreeの画面上の表記（例）
running.authデータ取得中。該当する金融機関またはサイトにおけるユーザー認証の段階。Refresh Request APIを利用すると、Refreshされる口座の全てはこのステータスになる。接続中
running.dataデータ取得中。ユーザー認証は正常に完了し、口座情報を追加で取得中。明細をダウンロード中
running.intelligenceデータ取得は完了。取得データを処理し、Moneytreeのシステムに保存中の段階。新しい取引明細を分析中
success上記３つのrunning.*ステータスを経て、新しいデータの取得が完了した時のステータス。なお、処理がすべて正常に完了したことを意味するため、新しいデータ（例：残高の変化、新しい取引明細など）が追加されたとは限らない。ただ今更新されました
（successになってからの時間を計算して出すため、「３分前に更新されました」となどもあり）
guest.intervention.requiredユーザー認証は正常に完了したものの、お客様自身が確認しなければならない項目があるため、データ取得が不可能な状態を表すエラーステータス。

例として金融機関などの場合、利用規約の変更などにより、ログイン直後のページで、規約の同意を求める内容が表示されている場合など。また、何らかの理由により、お客様が更新・確認するまでは当該サービスが利用できない時などに発生。

Request Refresh APIを利用した場合、データ取得が開始されるが、再度このステータスに戻るケースが発生することもある。		直接ログインしてください
inactiveかつてお客様が利用していた口座だが、現在利用されないためデータ取得を行わない口座を意味するステータス。

お客様の指示があれば、再度利用できるため、このステータスから別のステータスになる場合もある。		自動更新が無効になっています

🚧

「Moneytreeの画面上の表記」について

ここに記載されている文言は、金融サービス管理・一覧画面（vaultページ）により、一部異なる場合や、今後変更される可能性があります。

待機中のステータス

弊社にお客様に正しい認証情報が連携されていても、ログインをする時に追加認証が聞かれることがあります（画像認証など）。人間（口座の本人）が仲介して入力しない限り、基本はデータの取得ができなくなるため、下記のステータスになったら、そちら側のソフトなどで、お客様に知らせて弊社の画面にて追加認証を行っていただく必要があるでしょう。

また、毎回聞かれるような画像認証及びワンタイムパスワード認証の場合、毎回弊社の画面による入力がUX上よくないため、MT LINKのAPIにて該当する画像データ、お客様による入力の連携が可能です。

待機の時間は約３分です（RefreshのAPIを呼んでから）が、仕様上の決まりはないです。待機が長くなると、自動的に該当する認証エラーのステータスになります。また、待機中のステータスからrunningになり、再度待機中になる場合があります（例：合言葉の質問が２つある場合など）。

2018年9月現在、新たな待機中のステータスの追加を検討しておりませんが、必要に応じて追加する可能性があります。追加した場合、suspended.から始まる文字列で定義します。

Aggregation Status内容弊社の画面上の表記
suspended.missing-answer.auth.securityユーザー認証は成功したが、合言葉などの、追加の認証が求められている状態。金融機関により、ランダムに入力を求められるケースもある。追加情報が必要
suspended.missing-answer.auth.otpユーザー認証は成功したが、ワンタイムパスワードなどの追加の認証が求められている状態。通常、ワンタイムパスワードには主に以下の３つのパターンが存在する：

1) 金融機関やお客様の設定などにより毎回の入力を求められるパターン。

2) 実質的に上の１と同じだが、お客様のログイン設定に確認を求められるパターン（例：セキュリティ向上のため、お客様がワンタイムパスワード機能を有効にした）。

3) 金融機関やサービスなどのリスクベース認証によって尋ねられるパターン。例えば、普段ログインしている端末、ネットワーク環境と異なる経由でログインしようとした場合など。この場合、多くの金融機関では、一度入力すると以降は聞かれない。

このステータスになった場合は、お客様の操作が必要になるため、入力する必要があることを明記し、入力画面を表示して、APIによりパスワードを入力させるか、MT LINK の金融機関一覧画面へ誘導する必要がある。		ワンタイムパスワードが必要
suspended.missing-answer.auth.captchaユーザー認証は成功したが、画像認証（CAPTCHA）のような追加の認証が求められている状態。画像認証は主に２つのパターンが存在する：

1) 金融機関やお客様の設定などにより毎回の取得に聞かれるパターン。

2) 金融機関やサービスなどのリスクベース認証によって尋ねられるパターン。例えば、普段ログインしている端末、ネットワーク環境と異なる経由でログインしようとした場合など。この場合、多くの金融機関では、一度入力すると以降は聞かれない。

このステータスになった場合は、お客様の操作が必要になるため、入力する必要があることを明記し、入力画面を表示して、APIによりパスワードを入力させるか、MT LINK の金融機関一覧画面へ誘導する必要がある。		画像認証が必要
suspended.missing-answer.auth.puzzleユーザー認証は成功したが、パズル認証（画像認証の一種）が要求されている状態。初回登録時などに求められることが多い。

ワンタイムパスワードや画像認証と異なり、API経由で入力手段を提供するのが困難なため、MT LINK の金融機関一覧画面へ誘導する必要がある。		パズル認証が必要

認証関連のエラーステータス

Aggregation Status内容弊社の画面上の表記
auth.creds.invalid入力情報が正しくないためにユーザー認証でエラーが発生した時のステータス。例えば、Moneytreeに登録後、該当する金融機関などのサイトでユーザー・パスワードなどの認証情報を変更した場合、Moneytree側にも更新した内容を入力する必要がある。

また、金融機関によっては正しい認証情報であっても、一定期間毎に再認証を求めるため、「auth.creds.invalid」を受信する場合がある。

Moneytreeでログインできないため、Moneytree上で再認証しない限り、データも更新できなくなる。		認証情報に誤りがあります
auth.creds.security.invalidユーザー認証において、合言葉などの追加認証で失敗し、エラーとなった時のステータス
主に以下の２つのパターンがある：

1) お客様がMoneytreeのページ経由で合言葉などを入力したが、その内容が間違っている場合

2) 追加認証が要求され、ステータスがsuspended.missing-answer.auth.securityになったが、一定期間追加認証が行われなかったため、そのまま失敗と判断されたケース

お客様がMoneytreeの金融機関登録画面から再度回答を入力する必要がある。認証が完了していないため、auth.creds.invalid同様、認証が完了するまでMoneytreeではデータを更新できない。		認証情報に誤りがあります
auth.creds.otp.invalid認証中に、ワンタイムパスワードでエラーが発生した場合のステータス。主に以下の２つのパターンがある：

1) お客様がワンタイムパスワードを入力したが、間違っていた場合

2) ワンタイムパスワードが要求され、ステータスがsuspended.missing-answer.auth.otpになったものの、一定期間ワンタイムパスワードが入力されなかったため、そのまま失敗と判断されたケース。
auth.creds.invalid同様、認証が完了するまでMoneytreeではデータを更新できない。		ワンタイムパスワードが必要
auth.creds.captcha.invalidお客様が入力した画像認証の回答に誤りがある画像認証に誤りがあります
auth.creds.puzzle.invalidユーザー認証しようとしたが、パズル認証のエラーでデータ取得が失敗した時のステータス。２つのパターンがある：

1) お客様がパズル認証の回答をしたが、内容が間違っていた場合

2) パズル認証が要求され、ステータスがsuspended.missing-answer.auth.puzzleになったものの、一定期間回答の入力がないまま一定の時間が経過した場合

お客様に弊社の金融機関登録画面にて修正または回答していただく必要がある。auth.creds.invalid同様、認証が完了するまでMoneytreeではデータを更新できない。		パズル認証に誤りがあります
auth.creds.locked.temporary複数の箇所から短時間で数回ログインした場合など、何らかの理由でサービスへのアクセスがロックされている状況。

一定時間経過後、利用可能となる可能性があるが、Moneytreeに登録されている情報が正しくないケースが多いため、お客様にMoneytreeの金融機関登録画面から、再度認証データを入力する必要がある場合が多い。認証できていない状態のため、auth.creds.invalid同様、認証が完了するまでMoneytreeではデータを更新できない。		ロックされています
auth.creds.locked.permanentユーザー認証に複数回失敗した場合など、ユーザーがロックされている状況。

このステータスになると、ユーザー認証自体できない場合がほとんどであり、お客様が金融機関のサポート窓口などでロック解除の手続きなどをしないと利用できない。auth.creds.invalid同様、認証が完了するまでMoneytreeではデータを更新できない。		ロックされています

エラーのステータス

Aggregation Status内容弊社の画面上の表記
error.service.unavailableサービス利用時間外などのため、ユーザー認証できない状態。

サービス利用時間外の場合がほとんどであるため、このステータスの場合は、十分に時間を置かないかぎり、Request Refresh APIをリクエストしてもステータスは変わらない可能性が高い。		金融機関がメンテナンス中
error.sessionユーザー認証において、二重ログインなどの理由でエラーとなり、ログインに失敗した状態。

多くの場合、お客様がMoneytreeに同じ口座を重複して登録している場合や、PCなど別の端末から銀行インターネットバンキングへログインした状態のままMoneytreeが認証しようとした場合などに発生。

この状態からRequest Refresh APIを利用した場合、こうした問題が発生しない状況になれば、正常に更新できる可能性が高い。		ログアウトしてください
error.networkユーザー認証を試みた際に、ネットワーク上の問題でエラーが発生したと判定された状態。実装上は、error.service.unavailableと同等の問題として判断してよい。

この状態からRequest Refresh APIを利用した場合、該当する問題が解決されている状況であれば、正常に更新できる。		一時的な接続エラー
error.temporaryユーザー認証を試みた際、Moneytreeのシステム上、予期しないエラーが発生し、かつ、一時的なエラーと判断された状態。
主に、3つのケースがある：

1) 対象金融機関のサイトが更新されるなどして、Moneytreeのアグリゲーション処理がエラー終了した場合。Moneytree側の修正が必要。新規サービス対応のテストフェーズ中にあるケースが多い。また、対象金融機関のレスポンスが著しく遅い時に、同様のエラーになることもある。

2) Moneytreeの処理において、一定時間内にアグリゲーション処理が完了できず、タイムアウトとなった場合。

3) その他の予期しないシステムエラーなど。

この状態からRequest Refresh APIを利用した場合、1以外のケースでは、成功する可能性もある。		一時的な接続エラー
error.permanentユーザー認証を試みた際、Moneytreeのシステム上、予期ができないエラーが発生し、一時的でない恒久的なエラーと判定された状態。主に、2つのケースがある：

1) 対象金融機関のサイトが更新されるなどして、Moneytreeのアグリゲーション処理中に、認識できないページ、コード、またはデータが取得されたため、システム保護の目的で処理をエラー終了させたケース。Moneytree側の修正が必要。

2) その他予期できないシステムエラー。

この状態からRequest Refresh APIを利用した場合は、ステータスは更新されない可能性が高い。		一時的な接続エラー
error.unsupportedユーザは認証されるが、金融データを取得しようとする際に、Moneytreeのシステムが現時点では解決できない状況が発生すること。

例えば、金融機関側のエラーや制限により、金融データを提供できない場合などです。

この状態からRequest Refresh APIを使用した場合、ステータスは更新されない可能性が高いです。		一時的な接続エラー

Updated 9 months ago