POST /api/v1/zoloz/connect/initialize

ZOLOZ Connect initialize API は、ZOLOZ で顔認証プロセスを初期化するために使用されます。プロセスの一意のトランザクション ID が生成され、後続の ZOLOZ サーバーとのすべてのインタラクションで使用されます。この API はべき等ではありません。

構造

リクエストパラメーター

フィールド名	データ型	最大長	説明
bizId	文字列	32	必須。追跡目的の一意のビジネス ID。たとえば、加盟店のビジネス関連データベースのシーケンス ID。注：ZOLOZ サーバーは、このフィールドの値の一意性チェックを実行しません。追跡を改善するために、加盟店サーバーでビジネス ID の一意性を保証することを強くお勧めします。
metaInfo	文字列	512	必須。SDK とユーザーのデバイスに関するメタ情報。このフィールドの値は、ZOLOZ SDK から JSON 文字列形式で返されます。例： `"{\"apdidToken\":\"69b74bfe-bf7f-4d3b-ac59-907ee09e7955\",\"appName\":\"com.zoloz.atomic.client\",\"appVersion\":\"1.0.9\",\"bioMetaInfo\":\"3.46.0:2916352,0\",\"deviceModel\":\"MI 6\",\"deviceType\":\"android\",\"osVersion\":\"9\",\"zimVer\":\"1.0.0\"}"`。注：返された値は直接渡すだけでよいため、変更しないでください。
userId	文字列	64	必須。加盟店ユーザー ID、または特定のユーザーを識別するために使用できるその他の識別子。たとえば、携帯電話番号、メールアドレスなど。 userId フィールドの値を事前に非センシティブ化することを強くお勧めします。たとえば、値をハッシュ化します。
sceneCode	文字列	64	オプション。データ分析のためにビジネスシーンを指定します。異なるシーンのデータパフォーマンスを区別したい場合は、ビジネスの目的に応じて sceneCode フィールドを異なる値に設定することをお勧めします。たとえば、login、riskVerify、payment、 changePassword などです。
serviceLevel	文字列	32	オプション。顔のライブネス検出のサービスレベルを指定します。次の値がサポートされています。 `CONNECT0001`：このレベルでは、ライブネス検出を実行します。UI はユーザーに新しいページにジャンプするように要求しないため、ユーザーの離脱が少なくなります。これは通常、高い合格率が要求されるシナリオで使用されます。 `CONNECT0002`：デフォルト値。このレベルでは、なりすまし防止を実行します。ZOLOZ SDK は、まばたき検出方式でなりすまし防止チェックを実行します。 `CONNECT0003`：このレベルでは、なりすまし防止を実行します。 ZOLOZ SDK は、複数のアクション検出方式でなりすまし防止チェックを実行します。注：H5 モード接続は serviceLevel をサポートしていません。
operationMode	文字列	32	オプション。本人確認プロセスを実行する操作モードを指定します。次の値がサポートされています。 `CLOSED`：すべてのアルゴリズムとリスク管理ルールは適用されません。テストフェーズでは、アルゴリズムとリスク管理ルールがテストプロセスに影響を与えないように、この操作モードを使用できます。 `STANDARD`：デフォルト値。標準の推奨レベルが適用されます。 `LOOSE`：比較的緩いレベルが適用されます。低リスクのシナリオでは、この操作モードを使用できます。 `STRICT`：比較的厳格なレベルが適用されます。高リスクのシナリオでは、この操作モードを使用できます。注：H5 モード接続は operationMode をサポートしていません
h5ModeConfig	H5ModeConfig		オプション。H5 モードの構成設定を指定します。詳細については、以下の h5ModeConfig セクションを参照してください。
productConfig	ProductConfig		オプション。Connect プロダクトのより詳細な制御を指定します。詳細については、productConfig を参照してください。注：productConfig、serviceLevel、operationMode を同時に設定した場合、serviceLevel も operationMode も有効になりません。これは、これらのパラメーターが競合しているためです。代わりに、ZOLOZ は productConfig のみを読み取ります。

レスポンスパラメーター

フィールド名	データ型	説明
result	結果	必須。API リクエストの結果。ステータスやエラーコードなど、API リクエストの結果に関する情報が含まれています。
transactionId	文字列	オプション。顔認証プロセス用に ZOLOZ サーバーによって生成される一意のトランザクション ID。この ID は、Connect checkresult API リクエストの入力パラメーターとして使用されます。注：プロセス中にエラーが発生した場合（例：無効な引数）、トランザクション ID は返されません。
clientCfg	文字列	オプション。SDK 接続と動作に関するパラメーターを含む、クライアント構成情報。このフィールドの値は、result.resultStatus フィールドが `"S"` の場合にのみ指定されます。

結果

結果処理ロジック

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

値がresult.resultStatusですS の場合、ZOLOZ Connect initialize API が正常に呼び出され、一意のトランザクション ID が返されます。
値がresult.resultStatusですF の場合、ZOLOZ Connect initialize API の呼び出しは失敗します。考えられる理由の詳細については、エラーコードとメッセージを確認してください。

一般的なエラーコード

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

API 固有のエラーコード

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

resultCode	resultStatus	説明
SUCCESS	S	API 呼び出しは成功しました。
UNABLE_GET_IMAGE	F	参照ソースが見つかりません（登録前に検証を試みたことが原因）。
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 モードで開始された場合は、さらに h5ModeConfig というオブジェクトを指定する必要があります。

詳細については、次の 2 つのリクエストサンプルを参照してください。

ネイティブ接続リクエストサンプル

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

{
  "bizId":"test-bizId",
  "metaInfo": "{\"apdidToken\":\"69b74bfe-bf7f-4d3b-ac59-907ee09e7955\",\"appName\":\"com.zoloz.atomic.client\",\"appVersion\":\"1.0.9\",\"bioMetaInfo\":\"3.46.0:2916352,0\",\"deviceModel\":\"MI 6\",\"deviceType\":\"android\",\"osVersion\":\"9\",\"zimVer\":\"1.0.0\"}",
  "userId":"dummy_userid_1626180988600",
  "productConfig": {
    "livenessMode":"STANDARD",
    "actionCheckItems":["FACEBLINK","HEADLOWER"],
    "actionRandom":"Y",
    "deeperMode":"STANDARD"
  }
}

H5 接続リクエストサンプル

次のサンプルは、接続プロセスが H5 モードで開始された場合のリクエストの例を示しています。

{
  "bizId":"dummy_bizid_1626180988600",
  "metaInfo":"MOB_H5",
  "userId":"dummy_userid_1626180988600",
  "h5ModeConfig":{
      "completeCallbackUrl":"http://xxx/result.html",
      "interruptCallbackUrl":"http://xxx/result.html"
  },
  "productConfig": {
    "livenessMode":"STANDARD",
    "actionCheckItems":["FACEBLINK","HEADLOWER"],
    "actionRandom":"Y",
    "deeperMode":"STANDARD"
  }
}

レスポンスサンプル

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

{
    "result": {
        "resultStatus": "S",
        "resultCode": "SUCCESS",
        "resultMessage": "Success"
    },
    "transactionId":"G006600016CN20190114000000009572520355", 
    "clientCfg": "……"   
}

詳細情報

h5ModeConfig

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

フィールド名	データ型	最大長	説明
state	文字列	128	オプション。顧客のコンテキストを回復するために使用される識別子。このフィールドは任意の文字列値に設定できます。その後、ZOLOZ SDK が加盟店のアプリケーションにコールバックするときに、値がパラメーターとして渡されます。値が設定されていない場合は、transactionId フィールドの値が使用されます。
completeCallbackUrl	文字列	128	必須。本人確認プロセス全体が完了したときにブラウザーがリダイレクトされるコールバック URL を指定します。
interruptCallbackUrl	文字列	128	必須。プロセスが中断されたときにブラウザーがリダイレクトされるコールバック URL を指定します。
locale	文字列	16	オプション。Web ページの言語。現時点では en / id / zh-CN のみがサポートされています。デフォルトの言語は en です。
isIframe	文字列	1	オプション。Web ページを Iframe で開く必要がある場合は、このパラメーターを Y に設定する必要があります。デフォルト値は N です。サポートされている値：Y / N
uiCfg	文字列	256	オプション。JSON 文字列形式のカスタム UI 構成。サポートされているフィールドの例：titlebarbgcolor、titlebartextcolor、buttoncolor など。例：:"{\"titleBackgroudColor\": \"#0064FF\",\"titleTextColor\": \"#FFFFFF\",\"topTipColor\": \"#0064FF\"}". ポータルで関連する JSON ファイルの構成をサポートします。

productConfig

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

フィールド名	データ型	最大長	説明
livenessMode	文字列	10	オプション。顔のライブネス検出チェックのライブネスレベルを指定します。次の値がサポートされています。 `CLOSED`：すべてのアルゴリズムは適用されません。テストフェーズでは、アルゴリズムとリスク管理ルールがテストプロセスに影響を与えないように、このライブネス検出モードを使用できます。 `STANDARD`：デフォルト値。標準の推奨レベルが適用されます。 `LOOSE`：比較的緩いレベルが適用されます。低リスクのシナリオでは、このライブネス検出モードを使用できます。 `STRICT`：比較的厳格なレベルが適用されます。高リスクのシナリオでは、このライブネス検出モードを使用できます。
antiInjectionMode	文字列	10	廃止予定のフィールドであり、今後メンテナンスされません。API の互換性を確保するために、このフィールドは保持されます。オプション。インジェクション攻撃検出のインジェクション対策レベルを指定します。インジェクション攻撃検出は、ディープフェイク（顔交換画像や動画）を使用したインジェクション攻撃を効果的に阻止できます。次の値がサポートされています。 `CLOSED`：デフォルト値。すべてのインジェクション対策アルゴリズムは適用されません。ビジネスシナリオでインジェクション攻撃検出が必要ない場合は、有効にする必要はありません。 `STANDARD`：標準の推奨レベルが適用されます。 `LOOSE`：予約値。現在、使用はサポートされていません。 `STRICT`：予約値。現在、使用はサポートされていません。注：インジェクション攻撃検出を有効にすると、誤拒否率と実行時間がわずかに増加します。この機能を有効にする前に、ZOLOZ テクニカルサポートチームにお問い合わせください。
actionCheckItems	リスト<文字列>		オプション。検出されるユーザーアクション。ユーザーエクスペリエンスを向上させるために、2 つ以上のアクションを使用することはお勧めしません。次の値がサポートされています。 `FACEBLINK`：デフォルト値。ユーザーに目をまばたきするように要求します。 `MOUTHOPEN`：ユーザーに 1 回口を開けるように要求します。 `HEADSHAKE`：ユーザーに頭を振るように要求します。ユーザーが実行する左右のヘッドシェイクが指定されます。 `HEADLOWER`：ユーザーに 1 回頭を下げるように要求します。 `HEADRAISE`：ユーザーに 1 回頭を上げるように要求します。
actionRandom	文字列	1	オプション。`actionCheckItems` で指定されたユーザーアクションがランダムな順序で検出されるかどうかを指定します。有効な値は次のとおりです。 `Y`：ランダム `N`：デフォルト値。ランダムではありません。アクション検出は actionCheckItems の順序に従って実行されます。
deeperMode	文字列	10	オプション。AIGC 攻撃検出の Deeper レベルを指定します。Deeper 検出機能の詳細については、「Deeper とはを参照してください。次の値がサポートされています。 `CLOSED`：Deeper に関するすべての機能は適用されません（例：AIGC 検出アルゴリズム、端末リスク検出など）。ビジネスシナリオで AIGC 攻撃検出が必要ない場合は、有効にする必要はありません。 `STANDARD`：標準の推奨レベルが適用されます。 `LOOSE`：比較的緩いレベルが適用されます。低リスクのシナリオでは、この検出モードを使用できます。 `STRICT`：比較的厳格なレベルが適用されます。高リスクのシナリオでは、この検出モードを使用できます。注：この機能を有効にする前に、必ず Deeper プロダクトを購入してください。