verify initialize

2026-08-11 08:14

重要说明：

所有请求及返回参数均严格以官网API文档为准。
API返回结果中可能包含未在文档中定义的字段。这些字段仅供内部调试使用，不保证稳定性及兼容性，请勿在生产环境中依赖这些字段，ZOLOZ保留随时修改或删除这些字段的权利，且无需另行通知。

概览

API URL：/api/v1/zoloz/smile/verify/initialize
API 描述：该接口用于初始化用户生物特征的验证流程。

请求参数

字段名称	数据类型	最大长度	是否必填	默认值	描述	示例值
bizId	String	32	是	-	业务ID，业务的唯一标识，用于追踪业务。例如，商户业务相关数据库中的序列号。说明：ZOLOZ不校验该值的唯一性，商户侧需自行保证该业务ID的唯一性。	"2017839040588699"
metaInfo	String	512	是	-	SDK和用户设备的元信息。该字段的值由ZOLOZ SDK以JSON字符串格式返回。	{ \"deviceType\": \"android\", \"appVersion\": \"1.0.9\", \"osVersion\": \"9\", \"appName\": \"com.zoloz.atomic.client\", \"bioMetaInfo\": \"3.46.0:2916352,0\", \"apdidToken\": \"69b74bfe-bf7f-4d3b-ac59-907ee09e7955\", \"deviceModel\": \"MI 6\", \"zimVer\": \"1.0.0\" }
verificationType	String	32	否	face	生物特征验证类型。取值： `palm`：掌纹识别 `face`：人脸识别	"palm"
multiMatchControl	String	32	否	SECONDARY_VERIFY	多人脸匹配控制策略。仅当`verificationType`设置为`face`时生效。取值： `SECONDARY_VERIFY`：检测到多人脸时，系统触发二次验证。 `AUTO_PASS`：检测到多人脸时，系统自动通过验证，并选取匹配分数最高的用户。 `AUTO_FAIL`：检测到多人脸时，系统自动判定验证失败，并返回相似人脸列表。	"SECONDARY_VERIFY"

返回参数

字段名称	数据类型	必须返回	描述	示例值
result	Result	是	API请求结果，包含结果状态、结果码和结果消息。	{ "resultStatus": "S", "resultCode": "SUCCESS", "resultMessage": "Success" }
clientCfg	String	否	客户端配置信息，包括SDK连接和行为参数。说明：仅当`result.resultStatus`为`S`时返回。	"{\"clientStartIndex\":1, \"factorContext\":{...}}"
transactionId	String	否	本次验证生成的唯一交易ID。说明：仅当交易进入处理阶段后系统才会返回`transactionId`。如果在开始处理交易之前发生错误，系统不会返回`transactionId`。包括但不限于以下情况：请求参数非法，例如入参格式错误或缺失必传参数。请求未能成功到达服务器，例如网络问题或网关故障。系统限流导致请求被拒绝。	"G000000001FSE2025052300000001218988****"

处理结果

API通用结果码

有关通用结果码的完整列表，请参见API通用结果码。

API特有结果码

Smile verify initialize API的结果码见下表。

结果码	结果状态	描述
SUCCESS	S	API调用成功。
INVALID_ARGUMENT	F	请求参数无效。关于无效参数的详细信息，请查看返回的`resultMessage`。
DEVICE_NOT_SUPPORT	F	当前设备类型不支持。
OS_NOT_SUPPORT	F	当前操作系统不支持。
SDKVERSION_NOT_SUPPORT	F	当前SDK版本不支持。
SYSTEM_ERROR	F	系统内部错误。有关错误详情，请查看返回的`resultMessage`。

代码示例

请求示例

copy
{
    "bizId": "2017839040588699", 
    "verificationType": "palm", 
    "metaInfo": "{
         \"deviceType\": \"android\",
         \"appVersion\": \"1.0.9\",
         \"osVersion\": \"9\",
          \"appName\": \"com.zoloz.atomic.client\",
         \"bioMetaInfo\": \"3.46.0:2916352,0\",
         \"apdidToken\": \"69b74bfe-bf7f-4d3b-ac59-907ee09e7955\",
         \"deviceModel\": \"MI 6\",
         \"zimVer\": \"1.0.0\"
   }"
}

返回示例

copy
{
    "result": {
        "resultStatus": "S", 
        "resultCode": "SUCCESS", 
        "resultMessage": "Success"
    }, 
    "clientCfg": "{\"clientStartIndex\":1, \"factorContext\":{...}}", 
    "transactionId": "G000000001FSE2025052300000001218988****"
}