two-factor verify
重要说明:
- 所有请求及返回参数均以官网API文档为准。
- API返回结果中可能包含未在文档中定义的字段。这些字段仅供内部调试使用,不保证稳定性及兼容性,请勿在生产环境中依赖这些字段,ZOLOZ保留随时修改或删除这些字段的权利,且无需另行通知。
概览
- API URL:
/api/v1/zoloz/cnauthority/twofactor/verify - API 描述:该接口用于调用中国大陆官方权威数据源进行二要素(姓名 + 身份证号)身份核验。本接口仅校验姓名与身份证号的一致性,不采集、不传输人脸照片。该接口为同步请求-响应模型,不支持幂等调用,每次调用均会生成新的 transactionId。
说明:命中计费口径(resultCode=SUCCESS 或 AUTHORITY_NOT_SAME_PERSON)时将计入产品用量。
请求参数
字段名称 | 数据类型 | 最大长度 | 是否必填 | 默认值 | 描述 | 示例值 |
bizId | String | 32 | 是 | - | 业务ID,业务的唯一标识,用于追踪业务。例如,商户业务相关数据库中的序列号。 | "verify2-bizid-001" |
idName | String | 32 | 是 | - | 待核验的用户真实姓名。
| "张三" |
idNo | String | 32 | 是 | - | 待核验的身份证号码。
| "42050219881229801X" |
返回参数
字段名称 | 数据类型 | 必须返回 | 描述 | 示例值 |
result | 是 | API 请求结果对象,包含 resultCode、resultStatus、resultMessage。 | {"resultCode":"SUCCESS","resultStatus":"S","resultMessage":"Success"} | |
transactionId | String | 否 | 平台生成的唯一流水号,格式为
| "G000000000FCTF20261106000000205019269449" |
处理结果
根据请求结果执行下一步的响应动作,具体如下:
- 当 result.resultStatus 的值为
S时,表示核验成功,姓名与身份证号一致。 - 当 result.resultStatus 的值为
F时,表示核验失败。请检查错误码获取有关该错误的更多信息,并分析导致该错误的原因。
API通用结果码
有关通用结果码的完整列表,请参见API通用结果码。
API特有结果码
CN Authority Two-Factor Verify API 的结果码见下表。命中计费口径(SUCCESS / AUTHORITY_NOT_SAME_PERSON)时将计入产品用量。
结果码 | 结果状态 | 描述 | 是否计费 |
SUCCESS | S | 核验成功,姓名与身份证号一致。 | 是 |
AUTHORITY_NOT_SAME_PERSON | F | 姓名与身份证号不一致。 | 是 |
AUTHORITY_PROCESSING | F | 核验仍在处理中,建议稍后重试。 | 否 |
AUTHORITY_INACTIVE | F | 当前商户未开通(或已停用)大陆官方库核验服务。 | 否 |
AUTHORITY_PRODUCT_NOT_OPEN | F | 未开通 CTF 产品。请联系 ZOLOZ 运营团队开通本产品。 | 否 |
AUTHORITY_INVALID_CERT_NAME | F | 姓名无效(如包含无法识别的字符或格式不满足官方库要求)。 | 否 |
AUTHORITY_INVALID_CERT_NO | F | 身份证号码无效(如长度不正确、格式不合法或校验位错误)。 | 否 |
AUTHORITY_HIGH_RISK | F | 当前请求被判定为高风险,建议人工审核。 | 否 |
代码示例
请求示例
{
"bizId": "verify2-bizid-001",
"idName": "张三",
"idNo": "42050219881229801X"
}
返回示例
核验一致
{
"result": {
"resultCode": "SUCCESS",
"resultStatus": "S",
"resultMessage": "Success"
},
"transactionId": "G000000000FCTF20261106000000205019269449"
}核验不一致
{
"result": {
"resultCode": "AUTHORITY_NOT_SAME_PERSON",
"resultStatus": "F",
"resultMessage": "not same person"
},
"transactionId": "G000000000FCTF20261106000000205019269449"
}