【人脸识别认证】个人核身

接口描述

获取刷脸地址进行人脸识别认证。该接口可结合电子签名场景使用。

【注】：

（1）核身认证无需提前为用户创建账号；

（2）在 微信小程序、支付宝小程序和抖音小程序 中使用可以参考小程序接入文档对接。【请点击查看对接说明】

接口

/v2/identity/auth/api/individual/face

请求方式

POST

请求头

提供两种安全接入方式，对应参数如何获取，参考文档【请点击】。

方式一：请求签名鉴权（优先推荐）

参数名称	类型	必选	参数说明
X-Tsign-Open-App-Id	string	是	应用ID
Content-Type	string	是	application/json;charset=UTF-8
X-Tsign-Open-Ca-Timestamp	string	是	API 调用者传递时间戳，值为当前时间的毫秒数，也就是从1970年1月1日起至今的时间转换为毫秒，时间戳有效时间为15分钟，为了防重放攻击
Accept	string	是	建议统一填写 /
X-Tsign-Open-Ca-Signature	string	是	签名字符串
Content-MD5	string	否	当请求 Body 非 Form 表单时，可以计算 Body 的 MD5 值传递给云网关进行 Body MD5 校验。建议当请求 Body 非 Form 表单时，加上此请求头。
X-Tsign-Open-Auth-Mode	string	是	选择请求方式进行鉴权，固定值：Signature

方式二：OAuth2.0鉴权（不推荐使用）

当安全接入选择OAuth2.0鉴权方式，请点击查阅详情。

请求参数

展开全部参数参数名称		参数类型	必选	参数位置	参数说明
name		string	是	body	姓名
certType		string	否	body	个人证件类型 INDIVIDUAL_CH_IDCARD - 中国大陆身份证（默认值） INDIVIDUAL_CH_TWCARD - 台湾来往大陆通行证（台胞证） INDIVIDUAL_CH_HONGKONG_MACAO - 港澳来往大陆通行证（回乡证） INDIVIDUAL_CH_RESIDENCE_PERMIT_HK_MO_TW - 港澳台居民居住证（18位810开头） INDIVIDUAL_CH_GREEN_CARD - 外国人永久居留身份证（18位9开头）
idNo		string	是	body	个人证件号
faceauthMode		string	是	body	指定刷脸认证方式 ZHIMACREDIT - 支付宝刷脸认证（【请点击查看示例效果】） TENCENT - 腾讯云刷脸认证（【请点击查看示例效果】） ESIGN - 快捷刷脸认证（【请点击查看示例效果】） WE_CHAT_FACE - 微信小程序刷脸（【请点击查看对接说明】） PSN_AUDIO_VIDEO_ESIGN - 智能视频认证（【请点击查看示例效果】）以下方式需联系交付顾问开通后方可使用： FACE_TIKTOK_MINI - 抖音小程序刷脸（【请点击查看对接说明】）
faceInterfaceType		string	否	body	刷脸对接方式 H5 - 纯H5刷脸（默认值） SDK - APP内集成SDK刷脸（仅限faceauthMode为TENCENT- 腾讯云刷脸方式，且是APP内刷脸场景使用）（点击跳转移动端SDK对接说明）
callbackUrl		string	是	body	认证完成后重定向地址（可以在用户刷脸完跳转到贵司重定向地址后，调用【查询个人刷脸状态】接口主动查询用户刷脸结果：成功/失败）【注】：刷脸结果需要开发者主动查询，除支付宝刷脸外的其他刷脸方式均不会在刷脸页面直接告知用户结果。
contextId		string	否	body	自定义业务标识（用于关联开发者的业务系统，将在异步通知时发送回开发者，标识自身业务）
notifyUrl		string	否	body	认证结束后异步通知地址（详见"异步通知"章节说明）
config（点击“+”展开详情）		object	否	body	认证配置项
	audioVideoTemplateId	string	否	body	智能视频认证模板ID（可以指定录制视频页面的朗读文案）【注】：仅在faceauthMode：PSN_AUDIO_VIDEO_ESIGN - 智能视频认证场景使用请联系e签宝交付顾问配置后提供
	audioVideoActiveField	object	否	body	智能视频认证文案中的动态朗读内容，动态内容 Key:Value值（支持自定义key和Value），格式如下： "audioVideoActiveField": {"appName": "开发者平台名","userName": "认证人姓名","bizScene":"签署的文件名"} 【注】：与 audioVideoTemplateId（智能视频认证模板ID）配套使用请联系e签宝交付顾问进行配置

响应参数

展开全部参数参数名称（点击左侧“+”一键展开）		类型	必选	参数说明
code		int32	是	业务码，0表示成功，非0表示异常。
message		string	是	错误信息请根据 code 来判断错误情况，不应该依赖message匹配，因为 message 可能会调整。
data		object	否	业务信息
	flowId	string	否	实名认证流程ID
	authUrl	string	否	刷脸认证短链接指定TENCENT（腾讯云刷脸认证）时，链接有效时长为2分钟；指定ZHIMACREDIT（支付宝刷脸认证）时，链接有效时长为23小时；指定ESIGN（快捷刷脸认证）时，链接有效时长为60分钟；（如果用户超过链接有效期未操作，需要重新发起新的流程获取新的链接给用户操作）
	originalUrl	string	否	刷脸认证长链接指定TENCENT（腾讯云刷脸认证）时，链接有效时长为2分钟；指定ZHIMACREDIT（支付宝刷脸认证）时，链接有效时长为23小时；指定ESIGN（快捷刷脸认证）时，链接有效时长为60分钟；（如果用户超过链接有效期未操作，需要重新发起新的流程获取新的链接给用户操作）
	expire	int64	否	链接失效时间（Unix时间戳格式，单位：毫秒）
	faceToken	string	否	刷脸令牌（仅限腾讯云-SDK刷脸和微信小程序刷脸方式使用，其他情况不返回内容）

请求示例

{
    "name":"张三",
    "idNo":"320926xxxxxxxx5276",
    "faceauthMode": "TENCENT",
    "callbackUrl":"https://www.xx.cn/",
    "contextId": "f0a7927dxxxxd86c8fa8",
    "notifyUrl": "http://172.xx.xx.10:8080/notify/msgRecive"
}

响应示例

{
    "code": 0,
    "message": "成功",
    "data": {
        "flowId": "3534961111058332475",
        "authUrl": "https://smlt.esign.cn/UmaaDJS",
        "originalUrl": "https://kyc.qcloud.com/api/web/login?nonce=9750922fe04111117844a17a2e0bce&h5faceId=wb00884c85dde679bf3b0cd816beb17b&url=https%3A%2F%2Fjilin1208.smlh5.esign.cn%2Fwebserver-identity%2Fesign%2Fface%2Freturn%2FtencentCloud%2F05b83ccd72c341439edf2042afd8d13c&resultType=1&userId=05b83ccd72c341439edf2042afd8d13c&from=browser&redirectType=1&webankAppId=IDAZC8GK&orderNo=05b83ccd72c341439edf2042afd8d13c&version=1.0.0&sign=29D2EC56D18E0B6A9A0A77F58EF92AE01E3E826D",
        "faceToken": null,
        "expire": 1725436676088
    }
}

错误码

错误码	错误描述	解决方案
30500000	操作出错,请联系服务人员处理, ID:XXXX	请核实入参格式是否正确
30500101	参数错误：人脸认证方式传参错误	请核实faceauthMode入参是否正确
30500101	参数错误：姓名格式不正确	请输入真实有效的姓名（与证件类型保持一致）
30500101	参数错误：请输入正确的身份证号码	请输入真实有效的证件号（与证件类型保持一致）
30500101	参数错误：证件类型不支持	请输入正确的证件类型枚举值（certType）
30500101	参数错误：faceInterfaceType 不支持	请输入正确的刷脸对接方式
30500101	参数错误：faceauthMode不能为空	请传入正确的刷脸认证方式
30500101	参数错误：name字段不能为空	请输入真实有效的姓名
30500101	参数错误：idNo字段不能为空	请输入真实有效的证件号
30500101	参数错误：callbackUrl字段不能为空	请传入正确的重定向地址
30500101	参数错误：请输入正确的身份证号码	请核实传入的身份证号是否正确
30503107	很抱歉，订单余额不足	请核实是否有购买认证服务套餐，认证套餐是否生效，以及对应子服务是否开通。
30500116	格式校验不通过，请检查填入信息是否有多余空格	请核实入参是否存在空格
30503059	创建刷脸任务失败：未满14周岁的用户无法使用本产品	请核实认证人是否满14周岁