POST/api/v1/zoloz/facecapture/initialize

ZOLOZ 顔認証の 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\"}"`。注: 返された値は直接渡すだけでよいので、変更しないでください。H5 モードの場合は「MOB_H5」に設定します。
userId	文字列	64	-	必須。加盟店ユーザー ID、または特定のユーザーを識別するために使用できるその他の識別子。たとえば、携帯電話番号、メールアドレスなど。 userId フィールドの値を事前に非センシティブ化することを強くお勧めします。たとえば、値をハッシュ化します。
h5ModeConfig	H5ModeConfig		null	オプション。H5 モードの構成設定を指定します。詳細については、以下の初期化セクションを参照してください。
serviceLevel	文字列	32	FACECAPTURE0002	オプション。顔の活性チェックとユーザー操作検出のサービスレベルを指定します。次の値がサポートされています。 `FACECAPTURE0001`: この値が設定されている場合、ZOLOZ サーバーは、まばたき/ユーザー操作なしで顔の活性チェックを実行します。 `FACECAPTURE0002`: この値が設定されている場合、ZOLOZ サーバーは、まばたき検出メソッドを使用して活性チェックを実行します。 `FACECAPTURE0003`: この値が設定されている場合、ZOLOZ サーバーは、ランダムに使用されるつのユーザー操作で活性チェックを実行します。2 ランダムに使用されるユーザー操作。複数のアクション検出メソッドには、まばたき、口を開ける、頭を上げる、頭を下げる、頭を振る（左）、頭を振る（右）が含まれます。 `FACECAPTURE0005`: この値が設定されている場合、ZOLOZ サーバーは、まばたき検出メソッドを使用して活性チェックを実行します。このサービスレベルは、ネイティブ SDK の閉じた目の画像をキャプチャする機能を提供します。 `FACECAPTURE0010`: この値が設定されている場合、ZOLOZ サーバーは、まばたき検出メソッドを使用して活性チェックを実行します。このサービスレベルは、Web SDK の閉じた目の画像をキャプチャする機能を提供します。
operationMode	文字列	32	STANDARD	オプション。ID 証明プロセスが実行される操作モードを指定します。次の値がサポートされています。 `CLOSED`: すべてのアルゴリズムとリスク管理ルールは適用されません。テストフェーズでは、アルゴリズムとリスク管理ルールがテストプロセスに影響を与えないように、この操作モードを使用できます。 `STANDARD`: 標準の推奨レベルが適用されます。 `LOOSE`: 比較的緩いレベルが適用されます。低リスクのシナリオでは、この操作モードを使用できます。 `STRICT`: 比較的厳格なレベルが適用されます。高リスクのシナリオでは、この操作モードを使用できます。
productConfig	ProductConfig		null	オプション。Face Capture プロダクトの詳細な制御を指定します。詳細については、「初期化」をご参照ください。注記: productConfig、serviceLevel、および operationMode を同時に設定した場合、serviceLevel と operationMode のどちらも有効になりません。これは、これらのパラメーターが競合しているためです。代わりに、ZOLOZ は productConfig のみを読み取ります。

レスポンスパラメーター

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

結果

結果処理ロジック

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

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

一般的なエラーコード

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

API 固有のエラーコード

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

resultCode	resultStatus	説明
SUCCESS	S	API 呼び出しは成功しました。
HIGH_RISK	F	高リスクが検出されました。ユーザーアカウントはリスクエンジンによって戦略的にクールダウンされています。
DEVICE_NOT_SUPPORT	F	デバイスタイプはサポートされていません。
OS_NOT_SUPPORT	F	デバイスのオペレーティングシステムはサポートされていません。
SDKVERSION_NOT_SUPPORT	F	ZOLOZ SDK のバージョンはサポートされていません。
INVALID_ARGUMENT	F	入力パラメーターが無効です。どのパラメーターが無効かの詳細については、結果メッセージまたは関連ログを確認してください。
SYSTEM_ERROR	F	その他の内部エラー。エラーの詳細については、返された結果メッセージと関連ログを確認してください。

サンプル

リクエストサンプル

統合モードが異なると、リクエスト構造も少し異なります。顔認証プロセスが H5 モードで開始された場合は、というオブジェクトを指定する必要があります。H5最終的に、呼び出されるオブジェクトh5ModeConfig を指定する必要があります。詳細については、次の 2 つのリクエストサンプルを参照してください。

ネイティブ顔認証リクエストサンプル

次のサンプルは、加盟店サーバーから送信されたリクエストがどのように見えるかを示しています。

{
  "bizId":"test-bizId", // ビジネスID
  "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": "test-userId", // ユーザーID
  "productConfig": { // プロダクト設定
    "livenessMode":"STANDARD", // 活性モード
    "deeperMode":"CLOSED", // より深いモード
    "actionCheckItems":["FACEBLINK","HEADLOWER"], // アクションチェック項目
    "actionRandom":"Y", // アクションランダム
    "actionFrame:":["EYECLOSE"] // アクションフレーム
  }
}

H5 顔認証リクエストサンプル

次のサンプルは、顔認証プロセスが H5 モードで開始された場合のリクエストがどのように見えるかを示しています。

{
  "bizId":"dummy_bizid_1626180988600", // ビジネスID
  "metaInfo":"MOB_H5", // メタ情報
  "userId":"dummy_userid_1626180988600", // ユーザーID
  "h5ModeConfig":{ // H5モード設定
      "completeCallbackUrl":"http://xxx/result.html", // 完了コールバックURL
      "interruptCallbackUrl":"http://xxx/result.html" // 中断コールバックURL
  },
  "productConfig": { // プロダクト設定
    "livenessMode":"STANDARD", // 活性モード
    "deeperMode":"CLOSED", // より深いモード
    "actionCheckItems":["FACEBLINK","HEADLOWER"], // アクションチェック項目
    "actionRandom":"Y", // アクションランダム
    "actionFrame:":["EYECLOSE"] // アクションフレーム
  }
}

レスポンスサンプル

次のサンプルは、ZOLOZ サーバーから返されたレスポンスがどのように見えるかを示しています。

{
    "result": { // 結果
        "resultStatus": "S", // 結果ステータス
        "resultCode": "SUCCESS", // 結果コード
        "resultMessage": "Success" // 結果メッセージ
    },
    "transactionId":"G006600016CN20190114000000009572520355", // トランザクションID
    "clientCfg": "……"   // クライアント設定
}

詳細情報

h5ModeConfig

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

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

productConfig

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

フィールド名	データ型	最大長	デフォルト値	説明
livenessMode	文字列	10	STANDARD	オプション。顔の活性検出チェックの活性レベルを指定します。次の値がサポートされています。 `CLOSED`: すべてのアルゴリズムは適用されません。テストフェーズでは、アルゴリズムとリスク管理ルールがテストプロセスに影響を与えないように、この活性検出モードを使用できます。 `STANDARD`: 標準の推奨レベルが適用されます。 `LOOSE`: 比較的緩いレベルが適用されます。低リスクのシナリオでは、この活性検出モードを使用できます。 `STRICT`: 比較的厳格なレベルが適用されます。高リスクのシナリオでは、この活性検出モードを使用できます。
antiInjectionMode	文字列	10	CLOSED	非推奨のフィールドであり、今後メンテナンスされません。API の互換性を確保するために、このフィールドは保持されます。オプション。インジェクション攻撃検出のアンチインジェクションレベルを指定します。インジェクション攻撃検出は、ディープフェイク（顔交換画像やビデオ）を使用したインジェクション攻撃を効果的に阻止できます。次の値がサポートされています。 `CLOSED`: すべてのアンチインジェクションアルゴリズムは適用されません。ビジネスシナリオでインジェクション攻撃検出が必要ない場合は、有効にする必要はありません。 `STANDARD`: 標準の推奨レベルが適用されます。 `LOOSE`: 予約値。現在、使用はサポートされていません。 `STRICT`: 予約値。現在、使用はサポートされていません。注: インジェクション攻撃検出を有効にすると、誤拒否率と実行時間がわずかに増加します。この機能を有効にする前に、ZOLOZ テクニカルサポートチームにご連絡ください。
deeperMode	文字列	10	CLOSED	省略可能。指定しますより深くレベルの AIGC 攻撃検出です。より深く検出機能については、Deeper とは。サポートされている値は次のとおりです。 `CLOSED`: Deeper に関するすべての機能は適用されません。例: AIGC 検出アルゴリズム、端末リスク検出など。ビジネスシナリオで AIGC 攻撃検出が必要ない場合は、有効にする必要はありません。 `STANDARD`: 標準の推奨レベルが適用されます。 `LOOSE`: 比較的緩いレベルが適用されます。低リスクのシナリオでは、この検出モードを使用できます。 `STRICT`: 比較的厳格なレベルが適用されます。高リスクのシナリオでは、この検出モードを使用できます。注:必ずより深くこの機能を有効にする前のプロダクト。
actionCheckItems	List<String>		FACEBLINK	オプション。検出されるユーザー操作。ユーザーエクスペリエンスを向上させるために、2 つ以上のアクションを使用することはお勧めしません。次の値がサポートされています。 `FACEBLINK`: ユーザーは目をまばたきする必要があります。 `MOUTHOPEN`: ユーザーは口を 1 回開ける必要があります。 `HEADSHAKE`: ユーザーは頭を振る必要があります。ユーザーが実行するように、左または右のヘッドシェイクが指定されます。 `HEADLOWER`: ユーザーは頭を 1 回下げる必要があります。 `HEADRAISE`: ユーザーは頭を 1 回上げる必要があります。
actionRandom	文字列	1	N	オプション。で指定されたユーザー操作が、検出される順序がランダムかどうかを指定します。有効な値は次のとおりです。`アクションチェック項目` は検出されるためにランダムな順序になっています。有効な値は次のとおりです。 `Y`: ランダム `N`: ランダムではありません。アクション検出は actionCheckItems の順序に従って実行されます。
actionFrame	List<String>		null	オプション。このパラメーターは、他のフレーム画像のキャプチャを指し、次のように定義されます。 `EYECLOSE`: この値を設定すると、まばたき検出メソッド中に収集された閉じた目のフレームが返されます。
rearCamera	文字列	1	N	オプション。背面カメラを有効にするかどうかを指定します。WebSDK のみサポートされています。有効な値は次のとおりです。 `Y`: 背面カメラが有効になっています。 `N`: 背面カメラは有効になっていません。注:設定されている場合、`Y`、リアカメラで検出できるユーザー操作の範囲では、アクション/点滅はサポートされていません。
cropFaceImage	文字列	1	N	オプション。キャプチャされた顔画像の顔領域をトリミングするかどうかを指定します。有効な値は次のとおりです。 `Y`: キャプチャされた元の顔画像からトリミングされた追加の顔画像を返します。 `N`: トリミングしません。
checkDeviceRisk	文字列	1	N	オプション。このパラメーターは廃止され、に置き換えられました。`deeperMode`。注: `checkDeviceRisk` は、API の互換性を確保するために削除されません。これが `Y` に設定されている場合、checkresult API は引き続き `deviceRisk` フィールドを返します。これはビジネス上の意思決定には使用されず、最終結果には影響しません。