POST /api/v1/zoloz/idrecognition/initialize
ZOLOZ initialize API は、ZOLOZ で ID 認識プロセスを初期化するために使用されます。ID 認識プロセスのための一意のトランザクション ID が生成され、後続の ZOLOZ サーバーとのすべてのインタラクションで使用されます。この API はべき等ではありません。
構造
リクエストパラメーター
フィールド名 | データ型 | 最大長 | デフォルト値 | 説明 |
bizId | String | 32 | - | 必須。追跡目的の一意のビジネス ID。たとえば、加盟店のビジネス関連データベースのシーケンス ID。 注: ZOLOZ サーバーは、このフィールドの値の一意性チェックを実行しません。追跡を改善するために、加盟店サーバーでビジネス ID の一意性を保証することを強くお勧めします。 |
metaInfo | String | 512 | - | 必須。SDK とユーザーのデバイスに関するメタ情報。 このフィールドの値は、ZOLOZ SDK から JSON 文字列形式で返されます。たとえば、
注: 返された値は直接渡すだけでよいので、変更しないでください。 |
userId | String | 64 | - | 必須。加盟店ユーザー ID、または特定のユーザーを識別するために使用できるその他の識別子。たとえば、携帯電話番号、メールアドレスなど。userId フィールドの値は、たとえばハッシュ化によって事前に非機密化することを強くお勧めします。 |
docType | String | 16 | - | 必須。ドキュメントの種類。たとえば、アップロードするドキュメントがパスポートの場合は、この属性の値を 00000001003 に設定します。このフィールドの値は、null または空の文字列にしないでください。サポートされているドキュメントの種類については、サポートされているドキュメントの種類と返される OCR 結果を参照してください。 |
autoDocTypes | List<String> | 200 | - | オプション。ドキュメントの種類のリストを指定します。 または のいずれかを指定してください。
内の項目の値 |
pages | String | 32 | ドキュメントの種類でサポートされているすべてのページ | オプション。ID 認識を実行するドキュメントページ。コンマで区切ります。ドキュメントページの範囲については、サポートされているドキュメントの種類と返される OCR 結果を参照してください。 |
serviceLevel | String | 32 | IDRECOGNITION0002 | オプション。3 つのレベルがサポートされています。
|
operationMode | String | 32 | STANDARD | オプション。ID 確認プロセスを実行する操作モードを指定します。次の値がサポートされています。
|
h5ModeConfig | Object | - | オプション。H5 ID 認識フローの構成設定を指定します。詳細については、h5ModeConfigを参照してください。 | |
productConfig | ProductConfig | - | - | オプション。IDR プロダクトのより詳細な制御を指定します。詳細については、productConfig を参照してください。 |
レスポンスパラメーター
フィールド名 | データ型 | 説明 |
result | 必須。API リクエストの結果。ステータスやエラーコードなど、API リクエストの結果に関する情報が含まれています。 | |
transactionId | String | オプション。ID 認識プロセス用に ZOLOZ サーバーによって生成される一意のトランザクション ID。この ID は、ID 認識 checkresult API リクエストの入力パラメーターとして使用されます。 注: プロセス中にエラーが発生した場合 (例: 無効な引数)、トランザクション ID は返されません。 |
clientCfg | String | オプション。SDK 接続と動作に関するパラメーターを含む、クライアント構成情報。このフィールドの値は、result.resultStatus フィールドが |
productConfig
次の表は、productConfig データモデルで指定できるフィールドを示しています。
フィールド名 | データ型 | 最大長 | デフォルト値 | 説明 |
pageInfoCheck | Array | - | null | 情報チェックが必要な場合は、サポートされている情報チェックコンポーネントの配列を指定する必要があります。このフィールドの有効な値については、DOC なりすましチェックの詳細を参照してください。 |
consistencyCheck | List<ConsistencyCheckItem> | - | null | オプション。DOC なりすましチェック内で整合性チェックを実行するかどうかを指定します。整合性チェックは、選択したドキュメントにのみ適用されます。 整合性チェックが必要な場合は、サポートされている情報チェックコンポーネントの配列を指定する必要があります。このフィールドの有効な値については、整合性チェックデータ構造を参照してください。 |
allowExpiredDocument | String | - | ドキュメントの種類によってデフォルト値が異なります。
| オプション。期限切れのドキュメントを許可するかどうかを指定します。次の値がサポートされています:
注: 無効な値はデフォルトオプションに戻り、期限切れのドキュメントが検出されたら ID 認識プロセスを一時停止します。 |
cropFaceImageFromDoc | String | 1 | N | オプション。キャプチャしたドキュメント画像の顔領域をトリミングするかどうかを指定します。有効な値は次のとおりです。
|
enableOCR | String | - | N | オプション。OCR 機能を有効にするかどうか。値は次のとおりです。
● |
spoofMode | String | 10 | CLOSED | オプション。このパラメーターは、ドキュメントのなりすまし防止レベルを指し、次のように定義されます。
注: この機能を使用するには、Spoof プロダクトを購入する必要があります。 |
ConsistencyCheckItem データ構造
commonConsistencyCheck
フィールド名 | データ型 | 値の範囲 | 説明 | サポートされている ID / 国または地域 / docType / チェック対象の OCR フィールド |
type | String | commonConsistencyCheck | DOC なりすましチェック内での OCR フィールドの整合性チェック | Mykad / マレーシア / 00600000001 / ID_NUMBER
|
mrzVisualConsistencyCheck
フィールド名 | データ型 | 値の範囲 | 説明 | サポートされている ID / 国または地域 / docType / チェック対象の OCR フィールド |
type | String | mrzVisualConsistencyCheck | DOC なりすましチェック内で MRZ (機械可読ゾーン) と VIZ (目視検査ゾーン) の両方を持つ OCR フィールドの整合性チェック | - |
details | List<String> | 各 docType でサポートされている ocr フィールドを参照 | 整合性チェックの詳細に ocr フィールドを指定します。
| MyVisa / マレーシア / 00600000011 /
|
パスポート (MRZ と VIZ の両方) / CHN, HKG, TWN, MAC, PHL, SGP, MYS / 00000001006 /
|
passportCountryCheck
フィールド名 | データ型 | 値の範囲 | 説明 | サポートされている ID / 国または地域 / docType / チェック対象の OCR フィールド / デフォルトの国コード |
type | String | passportCountryCheck | OCR 結果の | |
valueRange | List<String> | デフォルトの国コードと同じである必要があります。 | type が passportCountryCheck の場合、 | 以下の docType の場合、valueRange はデフォルトの国または地域コードのリストである必要があります
|
各項目は ISO_3166-1_alpha-3 に準拠する必要があります | 以下の docType については、
|
結果
結果処理ロジック
リクエスト結果ごとに、実行されるアクションが異なります。詳細については、以下を参照してください。
result.resultStatus の値が
Sの場合、ZOLOZ initialize API は正常に呼び出され、一意のトランザクション ID が返されます。result.resultStatus の値が
Fの場合、ZOLOZ initialize API の呼び出しは失敗します。考えられる理由の詳細については、エラーコードとメッセージを確認してください。エラーコード
一般的なエラーコード
一般的なエラーコードの完全なリストについては、「一般的なエラーコード」セクションの エラー処理 トピックをご参照ください。
API 固有のエラーコード
次の表は、ID 認識 initialize API に固有の考えられるエラーコードを示しています。
resultCode | resultStatus | 説明 |
SUCCESS | S | API 呼び出しは成功しました。 |
HIGH_RISK | F | 高リスクが検出されました。ユーザーアカウントは、リスクエンジンによって戦略的にクールダウンされています。 |
ACCOUNT_SERVICE_SUSPEND | F | ユーザーアカウントは、リスクエンジンによってブラックリストに登録されています。 |
DEVICE_NOT_SUPPORT | F | デバイスタイプはサポートされていません。 |
OS_NOT_SUPPORT | F | デバイスのオペレーティングシステムはサポートされていません。 |
SDKVERSION_NOT_SUPPORT | F | ZOLOZ SDK のバージョンはサポートされていません。 |
INVALID_ARGUMENT | F | 入力パラメーターが無効です。どのパラメーターが無効かの詳細については、結果メッセージまたは関連ログを確認してください。 |
SYSTEM_ERROR | F | その他の内部エラー。エラーの詳細については、返された結果メッセージと関連ログを確認してください。 |
サンプル
リクエストサンプル
統合モードごとに、リクエスト構造が少し異なります。H5 モードで ID 認識プロセスが開始された場合は、さらに h5ModeConfig というオブジェクトを指定する必要があります。詳細については、次の 2 つのリクエストサンプルを参照してください。
ネイティブリクエストサンプル
次のサンプルは、App SDK モードで ID 確認プロセスが開始された場合のリクエストの例を示しています。
{
"bizId": "2017839040588699",
"userId": "123456abcd",
"autoDocTypes":["08520000001","08520000002"],
"productConfig": {
"consistencyCheck": [
{
"type": "commonConsistencyCheck" // 共通整合性チェック
},
{
"details": [
"NAME",
"SEX"
],
"type": "mrzVisualConsistencyCheck" // MRZビジュアル整合性チェック
}
],
"pageInfoCheck": [
{
"name": "id"
},
{
"name": "symbol"
},
{
"name": "name"
}
],
"allowExpiredDocument": "Y",
"cropFaceImageFromDoc": "Y",
"enableOCR":"Y",
"spoofMode":"STANDARD"
},
"metaInfo": "{
\"deviceType\": \"deviceType\",
\"appVersion\": \"1.0\",
\"osVersion\": \"7.1.1\",
\"appName\": \"com.company.wallet\",
\"bioMetaInfo\": \"3.37.0:262144,0\",
\"apdidToken\": \"mock-apdidToken\",
\"deviceModel\": \"MI 6\",
\"zimVer\": \"2.0.0\"
}"
}H5 RealId リクエストサンプル
次のサンプルは、H5 モードで ID 認識プロセスが開始された場合のリクエストの例を示しています.
{
"bizId": "2017839040588699",
"userId": "123456abcd",
"autoDocTypes":["08520000001","08520000002"],
"metaInfo": "MOB_H5",
"h5ModeConfig":{
"completeCallbackUrl":"https://sg-production-cdn.zoloz.com/page/zoloz-doc-fe/index.html",
"interruptCallbackUrl":"http://xxx.html"
},
"productConfig": {
"consistencyCheck": [
{
"type": "commonConsistencyCheck" // 共通整合性チェック
},
{
"details": [
"NAME",
"SEX"
],
"type": "mrzVisualConsistencyCheck" // MRZビジュアル整合性チェック
}
],
"pageInfoCheck": [
{
"name": "id"
},
{
"name": "symbol"
},
{
"name": "name"
}
],
"allowExpiredDocument": "Y",
"cropFaceImageFromDoc": "Y",
"enableOCR":"Y",
"spoofMode":"STANDARD"
}
}レスポンスサンプル
次のサンプルは、ZOLOZ サーバーから返されるレスポンスの例を示しています。
{
"result": {
"resultStatus": "S",
"resultCode": "SUCCESS",
"resultMessage": "Success" // 成功
},
"transactionId":"G000000005FID20200304000000000001570702",
"clientCfg": "……"
}詳細情報
h5ModeConfig
次の表は、h5ModeConfig オブジェクトで指定できるフィールドを示しています。
フィールド名 | データ型 | 最大長 | デフォルト値 | 説明 |
state | String | 128 | フィールドの値。 | オプション。顧客のコンテキストを復元するために使用される識別子。このフィールドは任意の文字列値に設定できます。その後、ZOLOZ SDK が加盟店のアプリケーションにコールバックするときに、値がパラメーターとして渡されます。値が設定されていない場合は、transactionId フィールドの値が使用されます。 |
completeCallbackUrl | String | 128 | - | 必須。ID 確認プロセス全体が完了したときにブラウザがリダイレクトされるコールバック URL を指定します。 |
interruptCallbackUrl | String | 128 | - | 必須。プロセスが中断されたときにブラウザがリダイレクトされるコールバック URL を指定します。 |
isIframe | String | 1 | N | オプション。Web ページを Iframe で開く必要がある場合は、このパラメーターを Y に設定する必要があります。 サポートされている値: Y / N |
uiCfg | String | 256 | null | オプション。JSON 文字列形式のカスタム UI 構成。今のところ、、、、および のみがサポートされています。 例： 設定されている場合 |