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

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

请求方法: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的大小限制,请计算好请求中所有图片和其他信息的大小,不要超限。

调试

您可以在OpenAPI Explorer中直接运行该接口,免去您计算签名的困扰。运行成功后,OpenAPI Explorer可以自动生成SDK代码示例。

请求参数

名称 类型 是否必选 示例值 描述
Action String VerifyMaterial

要执行的操作。取值:VerifyMaterial

BizId String 39ecf51e-2f81-4dc5-90ee-ff86125be683

标识一次认证任务的唯一ID,不超过64字符。针对一次认证任务,系统支持无限次发起提交,直到最终认证通过,该任务完结。

说明 发起不同的认证任务时需要更换不同的BizId。
BizType String RPMinTest

使用实人认证服务的业务场景标识。请先参见 业务设置 在控制台完成创建。

FaceImageUrl String http://image-demo.img-cn-hangzhou.aliyuncs.com/example.jpg

人像正面照图片的HTTP/HTTPS链接。

IdCardNumber String 023432189011233490

身份证号。

Name String 张三

姓名。

IdCardBackImageUrl String http://image-demo.img-cn-hangzhou.aliyuncs.com/example3.jpg

身份证国徽面图片的HTTP/HTTPS链接。

IdCardFrontImageUrl String http://image-demo.img-cn-hangzhou.aliyuncs.com/example2.jpg

身份证人像面图片的HTTP/HTTPS链接。

UserId String 54sdj

终端用户的ID,如终端用户的账号ID。

返回数据

名称 类型 示例值 描述
AuthorityComparisionScore Float 97

认证过程中所提交的人脸照片和权威数据的比对分,取值范围为[0,100]。

置信度阈值请参考:

  • 误识率0.001%时,对应阈值95。
  • 误识率0.01%时,对应阈值90。
  • 误识率为0.1%时,对应阈值80。
  • 误识率为1%时,对应阈值为60。
说明 该字段只表示人脸与权威数据的比对结果,是个参考分,通常不建议业务上仅以该分数作为是否通过的标准。认证的综合结果请参考VerifyStatus字段。VerifyStatus的结果综合了人脸与权威数据的比对和其他多种策略,可以提高安全水位。
FaceComparisonScore Float 97

认证过程中所提交的人脸照片和人像留底图片上人脸的比对分,取值范围为[0,100]。

置信度阈值请参考:

  • 误识率0.001%时,对应阈值95。
  • 误识率0.01%时,对应阈值90。
  • 误识率为0.1%时,对应阈值80。
  • 误识率为1%时,对应阈值为60。
IdCardFaceComparisonScore Float 97

认证过程中所提交的人脸照片和身份证人像面图片上人脸的比对分,取值范围为[0,100]。

置信度阈值请参考:

  • 误识率0.001%时,对应阈值95。
  • 误识率0.01%时,对应阈值90。
  • 误识率为0.1%时,对应阈值80。
  • 误识率为1%时,对应阈值为60。
Material Struct

认证材料。

FaceImageUrl String http://image-demo.img-cn-hangzhou.aliyuncs.com/example.jpg

人像正面照图片的HTTP/HTTPS链接,对应于入参的FaceImageUrl。链接地址5分钟内有效,建议业务上进行转存以免影响使用。

IdCardInfo Struct

身份证信息的OCR结果。

说明 认证过程中如果没有身份证正面和身份证反面,则不会返回身份证信息的OCR结果。认证过程中如果有身份证正面和身份证反面,也不保证一定会返回身份证上所有的信息,因身份证拍摄问题等引起的OCR无法识别时,OCR信息就会不全,建议接入方业务上不强依赖身份证OCR信息。
Address String 浙江省杭州市余杭区文一西路969号

地址。

Authority String 杭州市公安局

签发机构。

BackImageUrl String http://image-demo.img-cn-hangzhou.aliyuncs.com/example3.jpg

身份证国徽面图片的HTTP/HTTPS链接。链接地址5分钟内有效,建议业务上进行转存以免影响使用。

Birth String 1990-01-01

出生日期。

EndDate String 2020-11-01

证件有效期结束时间。格式为:yyyy-MM-dd。

FrontImageUrl String http://image-demo.img-cn-hangzhou.aliyuncs.com/example2.jpg

身份证人像面图片的HTTP/HTTPS链接。链接地址5分钟内有效,建议业务上进行转存以免影响使用。

Name String 张三

姓名。

Nationality String

民族。

Number String 023432189011233490

身份证号。

Sex String

性别。取值:

StartDate String 2010-11-01

证件有效期开始时间。格式为:yyyy-MM-dd。

IdCardName String 张三

姓名,对应于入参的Name。

IdCardNumber String 023432189011233490

身份证号,对应于入参的IdCardNumber。

RequestId String 04F0F334-1335-436C-A1D7-6C044FE73368

本次请求的ID。

VerifyStatus Integer 1

认证状态,取值:

  • 1:认证通过
  • 2~n:各种不同原因导致的认证不通过

详细描述请参见认证状态说明。

VerifyToken String c302c0797679457685410ee51a5ba375

该次认证的Token,用来串联认证请求中的各个接口,在30分钟内有效。

认证状态说明

VerifyStatus

原因说明

1

认证通过。

2

认证不通过,原因:实名校验不通过。

3

认证不通过,可能原因:身份证照片模糊、光线问题造成字体无法识别。身份证照片信息与需认证的身份证姓名不一致。提交的照片为非身份证照片。

4

认证不通过,可能原因:身份证照片模糊、光线问题造成字体无法识别。身份证照片信息与需认证的身份证号码不一致。提交的照片为非身份证照片。

5

认证不通过,可能原因:身份证照片有效期已过期(或即将过期)等可能。

6

认证不通过,可能原因:人脸与身份证头像不一致等可能。

7

认证不通过,可能原因:人脸与公安网照片不一致等可能。

8

认证不通过,可能原因:提交的身份证照片非身份证原照片未提交有效身份证照片

9

认证不通过,可能原因:非账户本人操作等可能。

11

认证不通过,可能原因:公安网照片缺失公安网照片格式错误公安网照片未找到人脸

12

认证不通过,可能原因:公安网系统异常,无法比对等可能。

示例

请求示例

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 格式

<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>
                        <Birth>1990-01-01</Birth>
                        <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": "汉",
          "Birth": "1990-01-01",
          "Address": "浙江省杭州市余杭区文一西路969号",
          "StartDate": "2010-11-01",
          "EndDate": "2020-11-01",
          "Authority": "杭州市公安局"
        }
      },
      "AuthorityComparisonScore": "97"
}

错误码

访问错误中心查看更多错误码。