enroll initialize

2026-08-11 08:14

重要说明：

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

概览

API URL：/api/v1/zoloz/smile/enroll/initialize
API 描述：该接口用于初始化基于SDK的人脸或掌纹采集流程，以进行用户注册。

请求参数

字段名称	数据类型	最大长度	是否必填	默认值	描述	示例值
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\" }
twoFaInfo	String	32	是	-	两步验证信息，支持设置手机号码或通用信息。手机号码：需符合策略规定的长度，且必须为纯数字。通用信息：可由商户自定义配置，配置后不可更改。	"11111111"
userId	String	64	是	-	商户的用户ID或其他可用于识别某一用户的标识，例如手机号码、电子邮件地址等。建议对`userId`字段的值进行预脱敏，例如进行哈希处理。	"123456abcd"
verificationType	String	32	否	face	生物特征验证类型。取值： `palm`：掌纹识别 `face`：人脸识别	"palm"

返回参数

字段名称	数据类型	必须返回	描述	示例值
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 enroll initialize API的结果码见下表。

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

代码示例

请求示例

copy
{
    "bizId": "2017839040588699", 
    "twoFaInfo": "11111111", 
    "userId": "123456abcd", 
    "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****"
}