POST /api/v1/zoloz/idrecognition/checkresult

ZOLOZ checkresult API は、実行中の ID 認識プロセスのステータスと、基本的なドキュメント検証結果と詳細なドキュメント検証結果を含むその他の対応する結果に関する結果をリクエストするために使用されます。この API はべき等です。

構造

リクエストパラメーター

フィールド名	データ型	最大長	デフォルト値	説明
bizId	String	32		必須。追跡目的のための一意のビジネス ID。たとえば、加盟店のビジネス関連データベースからのシーケンス ID。注: ZOLOZ サーバーは、このフィールドの値の一意性チェックを実行しません。追跡を改善するために、加盟店サーバーでビジネス ID の一意性を保証することを強くお勧めします。
transactionId	String	64		必須。initialize API のレスポンスで返される一意のトランザクション ID。
isReturnImage	String	1	Y	オプション。レスポンスで画像データを返すかどうか。値: `Y`: レスポンスで画像データを返します。 `N`: レスポンスで画像データを返しません。
extraImageControlList	List<String>	-		オプション。追加のドキュメント画像を返すかどうかを指定します。次の値がサポートされています: `DOC_FRONT_ANGLE`: 複数の角度でキャプチャされたドキュメントの表紙画像を返します。 `DOC_FRONT_FLASH`: フラッシュライトをオンにしてキャプチャされたドキュメントの表紙画像を返します。 `DOC_BACK_ANGLE`: 複数の角度でキャプチャされたドキュメントの裏表紙画像を返します。 `DOC_BACK_FLASH`: フラッシュライトをオンにしてキャプチャされたドキュメントの裏表紙画像を返します。 `CROPPED_FACE_FROM_DOC`: キャプチャされたドキュメント画像のトリミングされた顔領域を返します。注: 追加画像が返される可能性は、これらの画像が正常にキャプチャされたかどうかに依存します。これは、統合モードと、initialize API で設定された `serviceLevel` 値の両方によって決まります。

レスポンスパラメーター

フィールド名	データ型	説明
result	Result	必須。API リクエスト結果。ステータスやエラーコードなど、API リクエストの結果に関する情報が含まれています。
extInfo	ExtInfo	オプション。ドキュメント検証の詳細情報。このフィールドは、フィールドの値が result.resultStatusフィールドが設定されています`S` に設定されている場合にのみ使用できます。詳細については、ExtIDInfo を参照してください。

結果

結果処理ロジック

リクエスト結果が異なる場合、実行されるアクションも異なります。詳細は以下を参照してください。

の値がresult.resultStatusです S の場合、ZOLOZ checkresult API は正常に呼び出され、ドキュメント検証に関する結果が返されます。
の値がresult.resultStatusです F の場合、ZOLOZ checkresult API の呼び出しは失敗します。考えられる理由の詳細については、エラーコードとメッセージを確認してください。エラーコード。

一般的なエラーコード

一般的なエラーコードの完全なリストについては、「一般的なエラーコード」セクション (エラー処理 トピック内) を参照してください。

API 固有のエラーコード

次の表は、ID 認識 checkresult API に固有の考えられるエラーコードを示しています。

resultCode	resultSatus	説明
SUCCESS	S	ユーザーがトランザクションを完了しました。
PROCESSING	S	ユーザーがフロー全体を完了していません。
INVALID_ARGUMENT	F	入力パラメーターが無効です。どのパラメーターが無効かの詳細については、結果メッセージまたは関連ログを確認してください。
SYSTEM_ERROR	F	その他の内部エラー。エラーの詳細については、結果メッセージまたは関連ログを確認してください。
UNUSABLE	F	ユーザーはクールダウン戦略によってブロックされています。
LIMIT_EXCEEDED	F	ユーザーが同じトランザクション内で試行回数が多すぎます。

サンプル

リクエストサンプル

次のサンプルは、加盟店サーバーが送信するリクエストの例を示しています。

{
    "bizId": "2017839040588699",
    "transactionId": "G000000005FID20200304000000000001570702",
    "extraImageControlList": [
        "DOC_FRONT_ANGLE",
        "DOC_FRONT_FLASH"
    ]
}

レスポンスサンプル

次のサンプルは、ZOLOZ サーバーが返すレスポンスの例を示しています。

{
  "extInfo": {
    "certType":"00600000001",
    "docEdition":2,
    "imageContent": ["base64string.....", "base64string....."],
    "ocrResult": {
      "ID_NUMBER": "xxxx",
      "COUNTRY": "xxxxx",
      "SEX": "M"
    },
    "ocrResultDetail": {
      "MRZ_ID_NUMBER": {
        "name": "ID_NUMBER",
        "source": "MRZ",
        "value": "xxxx"
      },
      "VISUAL_ID_NUMBER": {
        "name": "ID_NUMBER",
        "source": "VISUAL",
        "value": "xxxx"
      },
      "MRZ_SEX": {
        "name": "SEX",
        "source": "MRZ",
        "value": "M"
      },
      "MRZ_COUNTRY": {
        "name": "COUNTRY",
        "source": "MRZ",
        "value": "xxxx"
      }
    },
    "spoofResult": {
      "TAMPER_CHECK": "Y",
      "MATERIAL_CHECK": "Y",
      "SCREEN_RECAPTURE_CHECK": "Y"
    },
    "recognitionErrorCode": "",
    "recognitionResult": "Y",
    "extraImages": {
      "DOC_FRONT_ANGLE": "/9j/4AA..[omitted]..PxA="
    }
  },
  "result": {
    "resultCode": "SUCCESS",
    "resultMessage": "success",
    "resultStatus": "S"
  }
}

詳細情報

ExtIdInfo

次の表は、ExtIdInfo データモデルで指定できるフィールドを示しています。

フィールド名	データ型	説明
recognitionResult	String	ドキュメント検証プロセスの実行ステータスを指定します。可能な値とその意味は次のとおりです。 `Y`: ドキュメント検証プロセスは正常に実行されました。 `N`: ドキュメント検証プロセスは失敗しました。ドキュメント検証プロセスが正常に実行された場合は必須です。
certType	String	ID タイプ。身分証明書のタイプを指定します。ドキュメント検証プロセスが正常に実行された場合は必須です。
docEdition	Integer	身分証明書の版を指定します。 `1`～`3`: 身分証明書の版。詳細は、サポートされているドキュメントタイプと返される OCR 結果を参照してください。 `0`: 身分証明書を分類できないか、ドキュメントタイプが間違っています。 `-1`: 不明なエラー。
imageContent	List<String>	身分証明書の画像 (存在する場合)。画像は base64 でエンコードする必要があります。このフィールドは、ドキュメント検証プロセスが正常に実行された場合にのみ指定されます。
extraImages	Map<String,String>	オプション。返される追加のドキュメント画像を指定します。このフィールドは、request.extraImageControlList で指定できます。キーは、request.extraImageControlList で指定された値です。値は、base64 でエンコードされた画像コンテンツです。リクエストされた画像が見つからない場合、値は "" になります。
ocrResult	Map	OCR 結果。ID に関する情報が含まれています。ドキュメント検証プロセスが正常に実行された場合は必須です。身分証明書のタイプに応じて、異なる ID 情報のセットが認識されます。詳細については、サポートされているドキュメントタイプと返される OCR 結果を参照してください。
ocrResultDetail	Map<String, OcrResultDetail>	OCR 結果の詳細。このフィールドは、`mrzVisualConsistencyCheck` は initialize API で
spoofResult	Map	オプション。なりすましチェック結果。改ざん、ドキュメント資料の信憑性、画面再キャプチャに関するチェック結果の情報が含まれています。詳細については、spoofResult を参照してください。
recognitionErrorCode	String	オプション。ドキュメント検証プロセスのエラーの詳細を指定します。可能な値とその意味は次のとおりです。 `NO_REQUIRED_ID`: アップロードされた画像から認識された ID が、指定された身分証明書タイプと一致しません。 `BLUR`: アップロードされた身分証明書画像がぼやけています。 `NO_FACE_DETECTED`: 指定された身分証明書から認識されるはずの顔が、アップロードされた画像から期待どおりに検出されませんでした。 `NOT_REAL_DOC`: アップロードされた身分証明書画像が偽物として検出されました。 `EXPOSURE`: アップロードされた身分証明書画像が露出オーバーです。 `UNKNOWN`: その他すべての認識エラー。
recognitionErrorDescription	String	ドキュメント検証の失敗理由を指定します。

spoofResult

次の表は、なりすましチェック結果に含まれる詳細情報を示しています。

フィールド名	データ型	説明
TAMPER_CHECK	String	必須。入力された身分証明書が改ざんチェックに合格したかどうかを指定します。身分証明書がチェックに合格しない場合、つまり改ざんされたと検出された場合は、`N` の値が返されます。それ以外の場合は、`Y` が返されます。
MATERIAL_CHECK	String	必須。身分証明書の素材が信憑性チェックに合格したかどうかを指定します。身分証明書の素材がチェックに合格しない場合、たとえば白黒で検出された場合は、`N` の値が返されます。それ以外の場合は、`Y` が返されます。
SCREEN_RECAPTURE_CHECK	String	必須。身分証明書が画面再キャプチャチェックに合格したかどうかを指定します。身分証明書がチェックに合格しない場合、つまりアップロードされた画像が画面から再キャプチャされた画像として検出された場合は、`N` の値が返されます。それ以外の場合は、`Y` が返されます。
SECURITY_FEATURE_CHECK	String	オプション。現在、HK 身分証明書のみをサポートしています。偽造カードを認識するために、身分証明書の一部のセキュリティ機能を検証します。
INFORMATION_CHECK	String	オプション。現在、HK 身分証明書のみをサポートしています。政府の規則に従って、ID 番号などの ID カードの情報を検証します。