全部产品
存储与CDN 数据库 域名与网站(万网) 应用服务 数加·人工智能 数加·大数据基础服务 互联网中间件 视频服务 开发者工具 解决方案 物联网 钉钉智能硬件

提交认证资料

更新时间:2018-01-10 20:16:24

描述

接口名称SubmitMaterials

功能描述: 服务端提交认证材料到实人认证服务进行审核,结果同步返回。

功能限制: 通常SubmitMaterials接口会同步返回认证结果,但是如果出现内部服务超时等现象,可能导致无法实时获取到认证的最终状态,此时接口会返回认证中状态。业务方在开发接入设计中需要考虑到这种情况,可以使用 查询认证状态(GetStatus) 接口轮询到最新的状态。

名词解释

  • 认证状态: 表示一个认证任务所处的认证状态,主要有以下四种状态:
    • -1: 未认证,表示没有提交记录。
    • 0: 认证中,表示已提交认证,系统正在审核认证资料。
    • 1: 认证通过,表示最近一次提交的认证资料通过审核,当前认证任务完结。
    • 2: 认证不通过,表示最近一次提交的认证资料未通过审核,当前认证任务还可以继续发起提交。
  • 图片地址格式: 用来告诉实人认证服务如何获取到图片,图片地址描述有以下两种模式:
    • http: 一个可访问的公网 HTTP 地址,例如 http://image-demo.img-cn-hangzhou.aliyuncs.com/example.jpg
    • oss: 一个可公开访问的 OSS 文件地址,格式为 oss://<bucket>:<path_to_file>
    • base64: 一个 base64 编码的图片,格式为 base64://<图片 base64 字符串>注意
      • 图片 base64 字符串需要去掉头部描述,如data:image/png;base64,
      • 使用 base64 传递图片的时候SubmitMaterials的请求方法需要改成 POST。
      • 由于单个请求的 Body 有大小限制(8M),因此请计算好图片大小,不要超过请求的大小限制。
  • 认证材料类型: 表示提交给认证服务进行审核的认证材料的类型,主要有以下几种类型(具体传入的字段请按照 认证方案 中的说明对应到您接入时确定的认证方案):
    • Name: 姓名,取值为字符串,例如 李三
    • IdentificationNumber: 身份证号,取值为字符串,例如 630546198009090099
    • FacePic: 人像照,取值为字符串,格式请参考图片地址格式
    • IdCardFrontPic: 身份证人像面照片,取值为字符串,格式请参考图片地址格式
    • IdCardBackPic: 身份证国徽面照片,取值为字符串,格式请参考图片地址格式
    • IDPic: 二代身份证芯片中存储的头像照片,取值为字符串,格式请参考图片地址格式
    • Mobile: 手机号,取值为字符串,例如 13983822930。(注意:这里的手机号用于辅助风险判断,而非与手机运营商实名信息进行核验。)
  • 实人可信分: 表示根据认证过程中所提交的材料所判断出的“这个是真实自然人”的可信程度分值,取值范围为 [0,100],分数越大可信程度越高。
  • 人脸相似度分: 表示认证过程中所提交的人脸照片和身份证上的头像的相似程度分值,取值范围为 [0,100],分数越大相似度越高。

请求参数

名称 类型 是否必须 描述
Action String 系统规定参数。取值: SubmitMaterials
RegionId String 系统规定参数。取值: cn-hangzhou
VerifyToken String 认证会话标识,通过 发起认证请求(GetVerifyToken) 接口获取。
Material.n.MaterialType 材料类型 认证材料类型,n 最大为 10。其中 n 需要和 Material.n.Value 参数匹配,具体取值请参考名词认证材料类型
Material.n.Value 材料值 认证材料对应的数值,n 最大为 10。其中 n 需要和 Material.n.MaterialType 参数匹配,具体取值请参考名词认证材料类型

返回参数

名称 类型 是否必须 描述
VerifyStatus Map 提交后的认证状态。

VerifyStatus 参数结构

名称 类型 是否必须 描述
StatusCode Integer 参看名词认证状态
TrustedScore Float 参看名词实人可信分
注意: 需要在实人认证管理控制台中启用才会返回该参数。
SimilarityScore Float 参看名词人脸相似度分

错误码说明

错误代码 英文描述 中文描述 HTTP状态码
Error.InternalError The request processing has failed due to some unknown error. 服务内部出现未知错误,请联系技术支持排查。 500
InvalidParam.ParamMissing Please check if there is param empty in your imput. 参数错误,请检查参数是否为空。 403
Error.NoPermissionAccess No permission to access our service. 没有权限访问服务,请确认是否服务已开通。 403
InvalidParam.VerifyTokenExpired The verify token was expired. VerifyToken 过期。VerifyToken 是有时效性的,请确保在 token 失效前进行提交。 400
InvalidParam.MaterialsEmpty The materials list is empty. Materials 列表为空。 400
InvalidParam.MaterialsNotValid The param materials is not valid. 请确保提交的材料类型正确性。 403
Error.DuplicatedTicketId A record associated with your ticketId has existed. 重复提交。通常一个TicketId参数已经提交后,再次提交时会出现此错误。 403
Error.SubmitMaterialsError SubmitMaterials action failed due to internal error. 提交处理失败。通常是实人认证服务内部处理异常,请联系技术支持排查。 500
Error.MaterialsUploadError The materials upload failed. SubmitMaterials 在上传认证资料中出现错误,请联系技术支持排查。 500
Error.MaterialsInsufficient The number of materials does not meet the requirements for verification. 提交认证的材料种类不满足要求,请检查上传的材料种类是否符合业务场景要求。 403

示例

拼接 HTTPS 请求示例

请求示例

  1. https://cloudauth.aliyuncs.com/?Action=SubmitMaterials
  2. &RegionId=cn-hangzhou
  3. &VerifyToken=8eb57ce35d584cbb9724198cb0ac6b60
  4. &Material.1.MaterialType=FacePic
  5. &Material.1.Value=http%3A%2F%2Fjiangsu.china.com.cn%2Fuploadfile%2F2015%2F0114%2F1421221304095989.jpg
  6. &Material.2.MaterialType=IDPic&SignatureNonce=c71f14e8-f2e7-45fd-9c5a-721cf6b38c4a
  7. &Material.2.Value=oss%3A%2F%2Fverify-img%3A715559d79b8d49c4aabfdad3f6a40774OSS.JPG
  8. &Material.3.MaterialType=IdCardFrontPic&Signature=azM4ZgJ7auesjlWQuMBF9X2Tnc8%3D
  9. &Material.3.Value=oss%3A%2F%2Fverify-img%3A715559d79b8d49c4aabfdad3f6a40774OSS.JPG
  10. &Material.4.MaterialType=IdCardBackPic
  11. &Material.4.Value=oss%3A%2F%2Fverify-img%3A715559d79b8d49c4aabfdad3f6a40774OSS.JPG
  12. &Material.5.MaterialType=IdentificationNumber
  13. &Material.5.Value=630546198009090099
  14. &Material.6.MaterialType=Name
  15. &Material.6.Value=%E6%9D%8E%E4%B8%89
  16. &<[公共请求参数]>

返回示例

XML 格式:

  1. <?xml version='1.0' encoding='UTF-8'?>
  2. <SubmitMaterialsResponse>
  3. <Data>
  4. <VerifyStatus>
  5. <StatusCode>1</StatusCode>
  6. <TrustedScore>87.15</TrustedScore>
  7. <SimilarityScore>93.12</SimilarityScore>
  8. </VerifyStatus>
  9. </Data>
  10. <Success>true</Success>
  11. <Code>1</Code>
  12. </SubmitMaterialsResponse>

JSON 格式:

  1. {
  2. "Code": "1",
  3. "Data": {
  4. "VerifyStatus": {
  5. "MaterialScore": 95.22905,
  6. "TrustedScore": 87.12,
  7. "StatusCode": 1
  8. }
  9. },
  10. "Success": true
  11. }

使用 SDK 开发包示例

参看 SDK 开发包使用文档中的认证方案示例:JavaPHPPython.NETNode.jsGo

本文导读目录