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,业务的唯一标识,用于追踪业务。例如,商户业务相关数据库中的序列号。
说明:ZOLOZ 服务器不检查该字段的值是否唯一。为了更便捷地追踪业务,建议启用商户服务器,并确保业务ID的唯一性。

"verify2-bizid-001"

idName

String

32

是

-

待核验的用户真实姓名。
说明:

  • 请传入与有效身份证件上完全一致的姓名,包括生僻字、多音字等。
  • 姓名中若含空格,由官方库侧判定有效性,本接口不做预校验。

"张三"

idNo

String

32

是

-

待核验的身份证号码。
说明:

  • 字母必须大写,例如 42050219881229801X。
  • 本接口不校验身份证号码的格式合法性(如校验位、长度),格式校验由官方库侧完成。传入小写 x 将被官方库判定为无效证件号。

"42050219881229801X"

返回参数

字段名称

数据类型

必须返回

描述

示例值

result

Result

是

API 请求结果对象,包含 resultCode、resultStatus、resultMessage。

{"resultCode":"SUCCESS","resultStatus":"S","resultMessage":"Success"}

transactionId

String

否

平台生成的唯一流水号,格式为 G+18位数字。可用于 zmng/portal 查询核验记录。
说明:

  • 核验成功或进入处理中状态时返回。
  • 接口调用失败(如入参不合法、系统错误)时可能不返回该字段。

"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

当前请求被判定为高风险,建议人工审核。

否

代码示例

请求示例

copy
{
  "bizId": "verify2-bizid-001",
  "idName": "张三",
  "idNo": "42050219881229801X"
}

返回示例

核验一致

copy
{  
    "result": {  
        "resultCode": "SUCCESS",  
        "resultStatus": "S",  
        "resultMessage": "Success"  
    },  
    "transactionId": "G000000000FCTF20261106000000205019269449"  
}

核验不一致

copy
{
  "result": {
    "resultCode": "AUTHORITY_NOT_SAME_PERSON",
    "resultStatus": "F",
    "resultMessage": "not same person"
  },
  "transactionId": "G000000000FCTF20261106000000205019269449"
}