使用纯服务端接入的认证方案时,您可以调用该接口,传入姓名、身份证号、人像照、身份证正反面照片(可选)进行实人认证,并同步返回认证结果。

单击查看老版本接入文档说明。

接入准备

接入该API时,请确保已经完成相应的准备工作,具体请参见服务端接入准备

描述

接口名:VerifyMaterial

请求方法:HTTPS POST 和 GET

接口说明:接入方服务端提交认证材料到实人认证服务进行核实比对,结果同步返回。

适用范围:该接口仅适用于纯服务端接入的认证方案。

关于图片地址
  • HTTP/HTTPS地址:支持公网可访问的HTTP/HTTPS地址。例如,http://image-demo.img-cn-hangzhou.aliyuncs.com/example.jpg
  • OSS地址:接入方的图片如果是本地文件,我们也提供相应的上传SDK,支持业务方将图片上传到实人认证服务指定的OSS bucket中,并获取相应的OSS地址后,作为接口的图片地址入参。如果您的业务需要使用上传SDK,请提交工单联系我们获取。
说明
  • 不支持本地图片的相对路径或绝对路径。
  • 单张图片大小请控制在2M内,避免算法拉取超时。
  • 图片中人脸区域的大小至少64*64像素。
  • 单个请求的Body有8M的大小限制,请计算好请求中所有图片和其他信息的大小,不要超限。

请求参数

名称 类型 参数位置 是否必需 描述
Action String query 要执行的操作。取值:VerifyMaterial
RegionId String query 服务所在地域。取值:cn-hangzhou
BizType String query 使用实人认证服务的业务场景标识。请先参见业务设置在控制台完成创建。
BizId String query 标识一次认证任务的唯一ID,不超过64字符。针对一次认证任务,系统支持无限次发起提交,直到最终认证通过,该任务完结。
说明 发起不同的认证任务时需要更换不同的BizId。
UserId String query C用户的ID,如C用户账号ID。
FaceImageUrl String query 人像正面照图片的HTTP/HTTPS链接。
Name String query 姓名。
IdCardNumber String query 身份证号。
IdCardFrontImageUrl String query 身份证人像面图片的HTTP/HTTPS链接。
IdCardBackImageUrl String query 身份证国徽面图片的HTTP/HTTPS链接。

返回参数

名称 类型 是否必需 描述
VerifyToken String 认证token。
VerifyStatus Integer 认证状态,取值:
  • 1:认证通过
  • 3~n:各种不同原因导致的认证不通过
详细描述请参见认证表 3
Material Map 认证材料。具体结构描述请参见表 1
AuthorityComparisonScore Float 认证过程中所提交的人脸照片和权威数据的比对分,取值范围为[0,100]。置信度阈值请参考:
  • 误识率0.001%时,对应阈值95。
  • 误识率0.01%时,对应阈值90。
  • 误识率为0.1%时,对应阈值80。
  • 误识率为1%时,对应阈值为60。
说明 该字段只表示人脸与权威数据的比对结果,是个参考分,通常不建议业务上仅以该分数作为是否通过的标准。认证的综合结果请参考VerifyStatus字段。VerifyStatus的结果综合了人脸与权威数据的比对和其他多种策略,可以提高安全水位。
表 1. Material
名称 类型 是否必需 描述
FaceImageUrl String 人像正面照图片的HTTP/HTTPS链接,对应于入参的FaceImageUrl。链接地址5分钟内有效,建议业务上进行转存以免影响使用。
IdCardName String 姓名,对应于入参的Name
IdCardNumber String 身份证号,对应于入参的IdCardNumber
IdCardInfo Map 身份证信息的OCR结果。具体结构描述参见表 2
说明 认证过程中如果没有身份证正面和身份证反面,则不会返回身份证信息的OCR结果。认证过程中如果有身份证正面和身份证反面,也不保证一定会返回身份证上所有的信息,因身份证拍摄问题等引起的OCR无法识别时,OCR信息就会不全,建议接入方业务上不强依赖身份证OCR信息。
表 2. IdCardInfo
名称 类型 是否必需 描述
FrontImageUrl String 身份证人像面图片的HTTP/HTTPS链接。链接地址5分钟内有效,建议业务上进行转存以免影响使用。
BackImageUrl String 身份证国徽面图片的HTTP/HTTPS链接。链接地址5分钟内有效,建议业务上进行转存以免影响使用。
Name String 姓名。
Number String 身份证号。
Sex String 性别。取值:
Nationality String 民族。
Address String 地址。
StartDate String 证件有效期开始时间。格式为:yyyy-MM-dd。
EndDate String 证件有效期结束时间。格式为:yyyy-MM-dd。
Authority String 签发机构。
表 3. 认证状态说明
VerifyStatus 原因说明
1 认证通过。
3 认证不通过,可能原因:1、身份证照片模糊、光线问题造成字体无法识别;2、身份证照片信息与需认证的身份证姓名不一致;3、提交的照片为非身份证照片等可能。
4 认证不通过,可能原因:1、身份证照片模糊、光线问题造成字体无法识别;2、身份证照片信息与需认证的身份证号码不一致;3、提交的照片为非身份证照片等可能。
5 认证不通过,可能原因:身份证照片有效期已过期(或即将过期)等可能。
6 认证不通过,可能原因:人脸与身份证头像不一致等可能。
7 认证不通过,可能原因:人脸与公安网照片不一致等可能。
8 认证不通过,可能原因:1、提交的身份证照片非身份证原照片;2、未提交有效身份证照片等可能。
9 认证不通过,可能原因:非账户本人操作等可能。
11 认证不通过,可能原因:1、公安网照片缺失;2、公安网照片格式错误;3、公安网照片找不到人脸等可能。
12 认证不通过,可能原因:公安网系统异常,无法比对等可能。

错误码

错误码 英文描述 中文描述
3101 name not match with identity number. 姓名与身份证号码不匹配。
3102 identity number not exist. 姓名与身份证号码不存在,即权威库中无此人。
3103 identity number invalid. 身份证号码不合法。

示例

关于使用服务端SDK开发包的示例,请参见以下具体SDK 开发包,使用文档中的认证方案说明:Java SDKPHP SDKPython SDK.NET SDKNode.js SDKGo SDK

请求示例
https://cloudauth.aliyuncs.com/?Action= VerifyMaterial
&RegionId=cn-hangzhou
&BizType=RPMinTest
&BizId=39ecf51e-2f81-4dc5-90ee-ff86125be683
&UserId=54sdj
&FaceImageUrl= http://image-demo.img-cn-hangzhou.aliyuncs.com/example.jpg
&Name=张三
&IdCardNumber=023432189011233490
&IdCardFrontImageUrl=http://image-demo.img-cn-hangzhou.aliyuncs.com/example2.jpg
& IdCardBackImageUrl=http://image-demo.img-cn-hangzhou.aliyuncs.com/example3.jpg
&<[公共请求参数]>
返回示例
  • XML格式
    <?xml version='1.0' encoding='UTF-8'?>
    <VerifyMaterialResponse>
        <Data>
            <VerifyToken>c302c0797679457685410ee51a5ba375</VerifyToken>
            <VerifyStatus>1</VerifyStatus>
            <Material>
            <FaceImageUrl>http://image-demo.img-cn-hangzhou.aliyuncs.com/example.jpg
                </FaceImageUrl>
                <IdCardName>张三</IdCardName>
                <IdCardNumber>023432189011233490</IdCardNumber>
                <IdCardInfo>
                    <FrontImageUrl>http://image-demo.img-cn-hangzhou.aliyuncs.com/example2.jpg
                    </FrontImageUrl>
                    <BackImageUrl>http://image-demo.img-cn-hangzhou.aliyuncs.com/example3.jpg
                    </BackImageUrl>
                    <Name>张三</Name>
                    <Number>023432189011233490</Number>
                    <Sex>男</Sex>
                    <Nationality>汉</Nationality>
                    <Address>浙江省杭州市余杭区文一西路969号</Address>
                    <StartDate>2010-11-01</StartDate>
                    <EndDate>2020-11-01</EndDate>
                    <Authority>杭州市公安局</Authority>
                </IdCardInfo>
            </Material>
            <AuthorityComparisonScore>97</AuthorityComparisonScore>
        </Data>
    </VerifyMaterialResponse>
  • JSON格式
    {
          "VerifyToken": "c302c0797679457685410ee51a5ba375",
          "VerifyStatus": "1",
          "Material": {
            "FaceImageUrl": "http://image-demo.img-cn-hangzhou.aliyuncs.com/example.jpg",
            "IdCardName": "张三",
            "IdCardNumber": "023432189011233490",
            "IdCardInfo": {
              "FrontImageUrl": "http://image-demo.img-cn-hangzhou.aliyuncs.com/example2.jpg",
              "BackImageUrl": "http://image-demo.img-cn-hangzhou.aliyuncs.com/example3.jpg",
              "Name": "张三",
              "Number": "023432189011233490",
              "Sex": "男",
              "Nationality": "汉",
              "Address": "浙江省杭州市余杭区文一西路969号",
              "StartDate": "2010-11-01",
              "EndDate": "2020-11-01",
              "Authority": "杭州市公安局"
            }
          },
          "AuthorityComparisonScore": "97"
    }