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

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リファレンスを参照してください。

マイナンバーカードの同一性​

マイナンバーカードを2回読み取るフロー（本人確認情報を照合しない場合 / 本人確認情報を照合する場合）では、1回目の読み取り（券面事項入力補助AP）と2回目の読み取り（利用者証明用電子証明書）に同一のマイナンバーカードが使用されることをMynaConnectが保証します。

1回目と異なるマイナンバーカードが使用された場合、そのセッションで自己情報を取得することはできません。GetSelfPersonalDataRequestStatus はステータス ERROR・エラー理由 INVALID_CARD_USED を返し、GetSelfPersonalDataRequestResult から自己情報が返却されることはありません。

このため事業者サービスは、GetUserIdentity で取得した基本4情報を、同じセッションで取得する自己情報の名義人の情報として扱えます。

注記

2回の読み取りは、同一のマイナンバーカードに加えて**同一の端末（マイナポータルアプリ）**で行う必要があります。1回目と2回目で端末を変えた場合も INVALID_CARD_USED となり、セッションはやり直しになります。

注意

2回の読み取りは、いずれも実物のマイナンバーカードで行う必要があります。スマートフォンのマイナンバーカード（スマホ用電子証明書）が読み取られた場合、同一性を判定できないため INVALID_CARD_USED となります。特にPCブラウザ向けサービスでQRコードを経由する場合は、マイナポータル側でスマートフォンのマイナンバーカードが既定の方法として選択されるため、エンドユーザーへの案内が必要です。詳しくはPCブラウザ（QRコード経由）でのマイナンバーカードの選択をご覧ください。

自己情報の取得結果の形式​

GetSelfPersonalDataRequestResult は、同じ自己情報を parsed と raw の2つの表現で返します。通常は型付きで扱える parsed を使用し、マイナポータルAPIから取得した内容をそのまま保管・検証したい場合に raw を使用します。

取得できる自己情報の項目と、各項目の意味・コード体系については、マイナポータルAPI仕様公開サイト 自己情報取得API 取得情報一覧をご参照ください。

parsed（パース済みデータ）​

parsed は google.protobuf.Any の配列で、特定個人情報ごとに1要素が格納されます。各要素の中身は、pocketsign.mynaconnect.spd.v1 パッケージに定義された TM + 特定個人情報名コード のmessageです。

  • messageの定義はAPIリファレンス（pocketsign.mynaconnect.spd.v1）で確認できます
  • 各フィールド名は、マイナポータルAPIのデータ項目コード（TK から始まるコード）を小文字にしたものです
  • provider フィールドには、その特定個人情報の情報提供元機関名が格納されます

Any を実際のmessageに展開して利用します。Goの場合は次のように書けます。

for _, a := range resp.Msg.Parsed {
    message, err := a.UnmarshalNew()
    if err != nil {
        // 未知の特定個人情報名コードなど、展開できない場合の処理
        continue
    }

    switch m := message.(type) {
    case *spdv1.TM00000000000107:
        // m.Provider や m.Tk... を参照する
    }
}
注記

Any の展開には、pocketsign.mynaconnect.spd.v1 の生成コードが必要です。Goでは対象のパッケージをimportしていないと型を解決できません。他の言語でも、使用するクライアントライブラリの方法で spd.v1 の型を読み込んでおく必要があります。

実装例は実装デモアプリケーションもご参照ください。

raw（生データ）​

raw は、マイナポータルAPIから取得した自己情報をそのまま格納した文字列です。情報提供元機関名と、それに対応する特定個人情報のXMLを交互に並べたJSONの配列になっています。

[
  "〇〇〇〇〇局",
  "（1件目の特定個人情報のXML）",
  "△△△△△機構",
  "（2件目の特定個人情報のXML）"
]

XMLの構造はマイナポータルAPIの仕様に準じます。parsed は、この各XMLを対応するmessageに変換したものです。取得した内容をそのまま保管したい場合や、独自にパースしたい場合に使用してください。

注記

マイナポータルAPIが「回答内容なし」を返した場合、raw は空文字、parsed は空配列になります。これは正常な応答です。詳しくはエラーハンドリングをご参照ください。

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

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

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

セッションの状態​

GetSelfPersonalDataRequestStatus は、自己情報取得API利用セッションの状態を SelfPersonalDataRequestStatus で返します。事業者サービスはこの状態を見て、本人確認情報の照合や自己情報の取得へ進むタイミングを判断します。

注記

このドキュメントでは、ステータスを SELF_PERSONAL_DATA_REQUEST_STATUS_ を省いた短縮表記で記載しています。実際の列挙値は SELF_PERSONAL_DATA_REQUEST_STATUS_PENDING のように接頭辞が付くため、レスポンスに PENDING という文字列がそのまま入るわけではありません。値の表現は使用するクライアントライブラリによっても異なります。正確な列挙値はSelfPersonalDataService APIリファレンスをご確認ください。

ステータス意味事業者サービスの対応
PENDINGエンドユーザーの認証・承認を待っています。マイナンバーカードの読み取りや情報提供への同意がまだ完了していない状態です一定間隔をおいて再度 GetSelfPersonalDataRequestStatus を呼び出します
FETCHINGエンドユーザーが情報提供に同意し、MynaConnectがマイナポータルから自己情報を取得しています一定間隔をおいて再度 GetSelfPersonalDataRequestStatus を呼び出します
NEED_TO_VERIFY_USER1回目のマイナンバーカード読み取りが完了し、事業者サービスによる本人確認情報の照合を待っています。本人確認情報を照合する場合のフローでのみ返りますGetUserIdentity で基本4情報を取得して照合し、SubmitUserIdentityVerificationResult で結果を送信します
SUCCESS自己情報の取得に成功しましたGetSelfPersonalDataRequestResult で自己情報を取得します
EXPIREDエンドユーザーが有効期限内に操作を完了しませんでしたポーリングを打ち切り、必要に応じて CreateSelfPersonalDataRequestSession でセッションを作成し直します
ERROR自己情報の取得に失敗しましたエラー理由に応じてエンドユーザーへ案内し、ポーリングを打ち切ります。やり直す場合は CreateSelfPersonalDataRequestSession でセッションを作成し直します
UNSPECIFIED未定義の値です。通常の連携フローでは返却されません未知のステータスとして扱い、ポーリングを継続したうえで一定時間で打ち切ってください

1回目のマイナンバーカード読み取りの完了を判定する​

1回目の読み取り（基本4情報の取得）が完了したことを判定できるのは、本人確認情報を照合する場合のフローのみです。このフローでは、1回目の読み取りが完了して事業者サービスへコールバックした時点で、GetSelfPersonalDataRequestStatus は NEED_TO_VERIFY_USER を返します。この値を、照合処理（GetUserIdentity の呼び出し）を開始する契機として使ってください。

本人確認情報を照合しない場合と本人確認情報を取得しない場合のフローでは、1回目の読み取り後に事業者サービスへコールバックせず、MynaConnect上で続けて2回目の読み取りに進みます。この間ステータスは PENDING のままで、1回目の読み取り完了を個別に判定することはできません。これらのフローでは SUCCESS になるまで待ってください。

状態遷移​

ステータスは次のように遷移します。SUCCESS・EXPIRED・ERROR は終端の状態で、これ以上変化しません。EXPIRED と ERROR になったセッションは再開できないため、やり直す場合は CreateSelfPersonalDataRequestSession で新しいセッションを作成し、エンドユーザーをマイナンバーカードの読み取りから再度誘導してください。

注記

照合を成功（ok=true）として送信すると、ステータスは FETCHING ではなく一度 PENDING（2回目のマイナンバーカード読み取り待ち）に戻ります。2回目の読み取りと情報提供への同意が完了した時点で FETCHING に進みます。ポーリング処理でステータスが後戻りしたように見えても異常ではありません。

セッションの有効期限​

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

注記

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

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

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

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

本人確認情報を照合する場合のフローでは、1回目の読み取り後に事業者サービスが本人確認情報を照合している時間も、この15分に含まれます。エンドユーザーが2回目のマイナンバーカード読み取りに進む前に15分を超えると、セッションは有効期限切れになります。照合処理は速やかに完了させ、エンドユーザーをMynaConnectへリダイレクトさせてください。

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

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

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

レート制限とポーリング間隔​

レート制限​

SelfPersonalDataService APIには、現時点で事業者サービスごとに適用しているレート制限値はありません。ただし無制限の呼び出しを保証するものではなく、サービス保護のために将来的に制限を設ける場合があります。必要以上に高頻度な呼び出しは避け、GetSelfPersonalDataRequestStatus をポーリングする場合は後述のポーリング間隔の目安に従ってください。

ポーリング間隔の目安​

GetSelfPersonalDataRequestStatus をポーリングする場合は、3秒以上の間隔を空けてください。

ポーリングは、終端のステータス（SUCCESS / EXPIRED / ERROR）に達した時点で停止してください。あわせて、終端のステータスに達しない場合に備えて、事業者サービス側でも打ち切りの上限時間を設けることを推奨します。

読み取り完了の検知とポーリングの関係​

1回目のマイナンバーカードの読み取りが完了したことは、本人確認情報を照合する場合のフローでは、エンドユーザーが事業者サービスへコールバックした時点で判明します。コールバックを受けてから GetSelfPersonalDataRequestStatus を1回呼び出せばステータス NEED_TO_VERIFY_USER が得られるため、読み取り完了の検知を早めるためにポーリング間隔を詰める必要はありません。

ポーリングが必要になるのは、主に非同期モードで自己情報の取得完了を待つ場合です。この待機はエンドユーザーの操作の有効期限（15分）の対象外であるため、ポーリング間隔がエンドユーザーの持ち時間を削ることはありません。

認証​

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

Authorization: Bearer <APIトークン>

例:

Authorization: Bearer OHabaTHrbodveeKRwjYePMTPUizcungcERxeIarmnyZMkjrkzLONnuWwcLIXgCDn

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

エラーハンドリング​

自己情報取得APIとの連携で発生するエラーは、次の2種類に分かれます。

種類現れ方例
APIの呼び出しに失敗する各APIがConnect / gRPCのステータスコードでエラーを返すAPIトークンが誤っている、指定したMynaConnectセッションIDが存在しない
セッション内の処理に失敗するAPIの呼び出し自体は成功し、GetSelfPersonalDataRequestStatus がステータス ERROR を返すエンドユーザーが情報提供に同意しなかった、マイナポータルAPIがエラーを返した

エンドユーザーの操作によって発生するエラーの大半は後者です。事業者サービスはセッションの状態とエラー理由を見て、エンドユーザーへの案内とフローのやり直しを制御してください。

失敗した場合のエンドユーザーの戻り先​

自己情報の取得に失敗した場合も、MynaConnectはエラー専用の画面を表示せず、CreateSelfPersonalDataRequestSession で指定された戻り先URIへエンドユーザーをリダイレクトします。 成功した場合と同じ導線で事業者サービスへ戻るため、コールバックを受けた事業者サービスは、必ず GetSelfPersonalDataRequestStatus でステータスを確認してから画面を出し分けてください。

エラーの理由（情報提供に同意しなかった、異なるマイナンバーカードが使用された、マイナポータルAPIがエラーを返した、など）がMynaConnectの画面でエンドユーザーに示されることはありません。エンドユーザーへのエラーの案内は事業者サービスの責務となります。

エンドユーザーの遷移先は状況によって次のように分かれます。

状況エンドユーザーの遷移先事業者サービスへのコールバック
自己情報の取得に失敗した（同意しなかった、カードが異なる、マイナポータルAPIのエラーなど）戻り先URIへリダイレクト発生する
セッションの有効期限が切れた後にMynaConnectの画面へアクセスした、フローを再開できない状態になったMynaConnectの案内ページ（「最初からやり直してください」「このタブを閉じてください」）発生しない
エンドユーザーがブラウザを閉じるなどして操作を中断した遷移しない発生しない
注意

上表のとおり、エンドユーザーが事業者サービスへ戻ってこないまま終わるセッションがあります。作成したセッションは事業者サービス側で追跡し、コールバックがないままエンドユーザーの操作の有効期限（15分）を過ぎた場合は、失敗したセッションとして扱ってください。このときステータスは EXPIRED になり、そのセッションで自己情報を取得することはできません。やり直す場合は CreateSelfPersonalDataRequestSession で新しいセッションを作成します。

エラー理由​

ステータスが ERROR の場合、GetSelfPersonalDataRequestStatus のレスポンスの error_reason に理由が入ります。ERROR 以外のステータスでは UNSPECIFIED になります。

エラー理由もセッションの状態と同様に短縮表記で記載しています。実際の列挙値は SELF_PERSONAL_DATA_REQUEST_ERROR_REASON_USER_CANCELLED のように SELF_PERSONAL_DATA_REQUEST_ERROR_REASON_ の接頭辞が付きます。

エラー理由発生条件事業者サービスの対応
USER_CANCELLEDエンドユーザーがマイナポータルで情報提供に同意しなかった場合、またはマイナンバーカードの読み取りを明示的に中止した場合エンドユーザーの意思による中断です。やり直せることを案内し、必要なら新しいセッションでフローを再開してください
INVALID_CARD_USED1回目と2回目で異なるマイナンバーカードまたは端末が使用された場合（マイナンバーカードの同一性）、または事業者サービスが SubmitUserIdentityVerificationResult に ok=false を送信した場合本人以外のカードが使われた可能性があります。本人のマイナンバーカードでやり直すよう案内してください
API_ERROR_RETURNEDマイナポータルAPIがエラーを返した場合。マイナポータルAPIや、その後段のシステム（中間サーバなど）のメンテナンス・閉塞によっても発生することがあります同じ条件でやり直しても再度失敗する場合があります。照会条件やAPIサービスの設定、および利用可能時間で案内しているマイナポータルAPIの稼働状況を確認し、解決しない場合はポケットサインへお問い合わせください
INTERNALMynaConnect内部でエラーが発生した場合時間をおいてやり直しても解決しない場合はポケットサインへお問い合わせください
UNSPECIFIEDエラーが発生していない場合、または理由が未定義の場合ステータスが ERROR 以外のときはこの値になります
取得結果が空になる場合

照会条件に該当する自己情報が存在しない場合、マイナポータルAPIは「回答内容なし」を返します。これは正常な応答であり、エラーではありません。

この場合もステータスは SUCCESS になり、GetSelfPersonalDataRequestResult は中身が空の自己情報（raw が空文字、parsed が空配列）を返します。事業者サービスは、取得に失敗した場合とは区別し、「該当する情報がなかった」ケースとして扱ってください。

APIが返すエラーコード​

エラーはConnect / gRPCのステータスコードで返ります。すべてのAPIで共通して発生するものは次のとおりです。

コード発生条件
unauthenticatedAuthorization ヘッダーの形式が不正、またはAPIトークンが無効
invalid_argumentリクエストのフィールドが制約に違反している（UUID形式、URI形式、必須項目など）
internalMynaConnect内部のエラー。エラーの詳細は返却されません

各APIに固有のエラーは次のとおりです。

APIコード発生条件
CreateSelfPersonalDataRequestSessioninvalid_argument指定したAPIサービスが存在しない、または認証したテナントのものでない
CreateSelfPersonalDataRequestSessioninvalid_argumentredirect_uri が、事前登録したコールバックURIをプレフィックスとして持たない
GetSelfPersonalDataRequestStatusnot_found指定したMynaConnectセッションIDのセッションが存在しない、または認証したテナントのものでない
GetSelfPersonalDataRequestResultnot_foundセッションが存在しない、自己情報を既に取得済み、または有効期限を過ぎて破棄された
GetSelfPersonalDataRequestResultfailed_precondition自己情報の取得がまだ完了していない（ステータスが SUCCESS になる前に呼び出した）
GetUserIdentitynot_foundセッションが存在しない、本人確認情報を既に取得済み、または有効期限を過ぎて破棄された
GetUserIdentityfailed_precondition1回目のマイナンバーカードの読み取りがまだ完了していない
SubmitUserIdentityVerificationResultnot_foundセッションが存在しない
SubmitUserIdentityVerificationResultfailed_precondition1回目のマイナンバーカードの読み取りがまだ完了していない
SubmitUserIdentityVerificationResultalready_exists検証結果を既に送信済み

別のテナントのAPIサービスやセッションを指定した場合は、存在しないものとして扱われます。

自己情報を取得する前に自己情報の取得の有効期限（10分）を過ぎた場合、GetSelfPersonalDataRequestStatus は SUCCESS を返したままですが、GetSelfPersonalDataRequestResult は not_found を返します。この場合も自己情報を再取得することはできないため、新しいセッションでフローをやり直してください。