メインコンテンツまでスキップ

SelfPersonalDataService API

自己情報取得APIとの連携機能を利用するには、PocketSign MynaConnect API内に定義されているSelfPersonalDataService APIを使用します。

このAPIは、Connect プロトコルに対応しています。 Connect プロトコルについては Verify APIも参照してください。

このAPIを使用した実装デモアプリケーションを公開しています。利用時にはデモアプリケーションの実装も参考にしてください。

API概要​

自己情報取得APIとの連携では、以下の5つのAPIを使用します。連携フローによって、一部使用しないAPIがあります。

基本的なAPI呼び出しの流れは以下です。

1. CreateSelfPersonalDataRequestSessionによって、 MynaConnectセッションIDを発行します​

  • 後続のAPIではこのMynaConnectセッションIDを使って、セッションの状態やエンドユーザーの本人確認情報や自己情報の照会結果の取得等を行います
  • また、同時にPocketSign MynaConnectへのリダイレクトさせるURLを発行します
  • このAPIの呼び出しで、エンドユーザーがMynaConnectから事業者のサービスにコールバックしてくるためのURLも指定します

2. 事業者サービスはMynaConnectへのリダイレクトURLにエンドユーザーをブラウザでリダイレクトさせます​

  • MynaConnectにリダイレクト後、MynaConnectはマイナンバーカードの読み取りを含むマイナポータルとの連携処理を行います
  • マイナポータルとの連携処理後、MynaConnectはCreateSelfPersonalDataRequestSessionで指定された事業者サービスのリダイレクトURIにエンドユーザーをリダイレクトします
  • 事業者サービスへリダイレクトするタイミングは、APIサービスに設定された 自己情報取得結果の受け取りモード によって異なります
    • 同期モード（デフォルト）: MynaConnect上での自己情報取得が完了してから事業者サービスへリダイレクトします
    • 非同期モード: 取得完了を待たずに即座に事業者サービスへリダイレクトし、自己情報の取得はバックグラウンドで進みます。詳しくは非同期モードでの結果取得をご覧ください

3. 事業者サービスはエンドユーザーがMynaConnectからコールバックしてきたら、GetSelfPersonalDataRequestStatusでセッションの状態を確認します​

  • 本人確認情報を照合する必要がある場合は、ここで処理が分岐します。詳しくは本人確認情報を照合する場合をご覧ください。
  • 非同期モードの場合は、コールバック時点ではまだ取得処理中（ステータスが PENDING または FETCHING）のことがあります。状態が SUCCESS になるまで GetSelfPersonalDataRequestStatus を一定間隔でポーリングしてください。

4. 状態が成功であれば、GetSelfPersonalDataRequestResultで、自己情報を取得します​

  • 事業者サービスは取得した自己情報を使った処理・サービスをエンドユーザーに提供します。
注意

PocketSign MynaConnectはエンドユーザーから取得した個人情報を一時的に保持しますが、GetSelfPersonalDataRequestResult及びGetUserIdentityで事業者サービスがそれらの情報を取得した時に、MynaConnect上から情報は削除されるため、一度取得した情報を再度取得することはできません。

具体的なシーケンスについては、連携フロー別のドキュメントをご覧ください。

詳細なAPI定義はSelfPersonalDataService APIリファレンスを参照してください。

本人確認情報（基本4情報）のテキストデータ形式​

GetSelfPersonalDataRequestResult および GetUserIdentity で返却される本人確認情報（基本4情報: 氏名・性別・住所・生年月日）は、マイナンバーカードの券面事項入力補助APから取得した情報です。

このうち 氏名と住所のテキストデータは、マイナンバーカードに格納されているテキストデータをそのまま返却します。 そのため、利用する際にはパースが必要になる場合があります。詳細はVerifyガイドの証明書に記載された情報をご参照ください。

セッションの有効期限​

CreateSelfPersonalDataRequestSession で作成した自己情報取得API利用セッションには、2つの有効期限があります。

注記

ここで説明する有効期限は、CreateSelfPersonalDataRequestSession などの個々のAPIリクエスト単位のタイムアウト（Connectプロトコルの Connect-Timeout-Ms ヘッダーで指定するもの）とは異なります。個々のAPIレスポンスは通常1秒以内に返却されます。

エンドユーザーの操作の有効期限（15分）​

セッションの作成から、エンドユーザーがマイナポータルでマイナンバーカードの読み取りと同意するかどうかの選択を行い、MynaConnectから事業者サービスにコールバックするまでの有効期限は 15分 です。

エンドユーザーが15分以内に操作を完了しなかった場合、GetSelfPersonalDataRequestStatus はステータス EXPIRED を返します。この場合、事業者サービスは CreateSelfPersonalDataRequestSession でセッションを作成し直してください。

自己情報の取得の有効期限（10分）​

MynaConnectがマイナポータルの自己情報取得APIから自己情報を取得して一時的に保持してから、事業者サービスが GetSelfPersonalDataRequestResult でその自己情報を取得するまでの有効期限は 10分 です。

GetSelfPersonalDataRequestStatus がステータス SUCCESS を返す状態に変化してから10分以内に GetSelfPersonalDataRequestResult を呼び出してください。10分を経過すると、MynaConnectが一時的に保持している自己情報は破棄され、取得できなくなります。

認証​

SelfPersonalDataService APIは、テナントのAPIトークンを用いて認証します。PocketSign Platform上で取得したトークンを、APIへのリクエストの Authorization ヘッダーに以下の形式で指定してください。

Authorization: Bearer <APIトークン>

例:

Authorization: Bearer OHabaTHrbodveeKRwjYePMTPUizcungcERxeIarmnyZMkjrkzLONnuWwcLIXgCDn

APIトークンの作成方法は、APIトークンの作成をご覧ください。

エラーハンドリング​

注記

このセクションは現在作成中です。

このトピックについて知りたい場合は、お問い合わせください。