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

接口描述

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

【注】：

（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	指定刷脸认证方式 TENCENT - 腾讯云刷脸认证 ZHIMACREDIT - 支付宝刷脸认证 ESIGN - 快捷刷脸认证（只支持中国大陆身份证） WE_CHAT_FACE - 微信小程序刷脸（【请点击查看对接说明】）以下方式需联系交付顾问开通后方可使用： FACE_TIKTOK_MINI - 抖音小程序刷脸（【请点击查看对接说明】）
faceInterfaceType	string	否	body	刷脸对接方式 H5 - 纯H5刷脸（默认值） SDK - APP内集成SDK刷脸（仅限faceauthMode为TENCENT- 腾讯云刷脸方式，且是APP内刷脸场景使用）（点击跳转移动端SDK对接说明）
callbackUrl	string	是	body	认证完成后重定向地址（可以在用户刷脸完跳转到贵司重定向地址后，调用【查询个人刷脸状态】接口主动查询用户刷脸结果）
contextId	string	否	body	自定义业务标识（用于关联开发者的业务系统，将在异步通知时发送回开发者，标识自身业务）
notifyUrl	string	否	body	认证结束后异步通知地址（详见"异步通知"章节说明）

响应参数

展开全部参数参数名称（点击左侧“+”一键展开）		类型	必选	参数说明
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	参数错误：faceauthMode不能为空	请传入正确的刷脸认证方式
30500101	参数错误：name字段不能为空	请传入正确的姓名
30500101	参数错误：idNo字段不能为空	请输入正确的身份证号
30500101	参数错误：callbackUrl字段不能为空	请传入正确的callbackUrl
30500101	参数错误：请输入正确的身份证号码	请核实传入的身份证号是否正确
30503107	很抱歉，订单余额不足	请核实是否有购买认证服务套餐，或登录e签宝官网核实账单记录
30500116	格式校验不通过，请检查填入信息是否有多余空格	请核实入参是否存在空格
30503059	创建刷脸任务失败：未满14周岁的用户无法使用本产品	请核实认证人是否满14周岁