人脸核身 - API文档

1、接口概要

1.1 文档说明

本文档主要提供给互亿平台的用户对接接口的使用说明，开发者可以利用互亿无线提供的 HTTP 接口，调用互亿无线的人脸核身服务。

1.2 提交方式

GET / POST

1.3 加密方式

1、采用HTTPS协议提交请求
2、通过MD5动态签名方式加密

1.4 API ID / API KEY

登录用户中心，进入“产品与服务 -》 认证核验 -》身份信息核验”，在【产品总览】页面右侧，如下图所示：

2、提交认证

2.1 接口描述

通过POST、GET方式进行提交，数据编码采用utf-8格式，支持24小时全天提交。
内容格式为：Content-Type: application/x-www-form-urlencoded

2.2 请求地址

https://api.ihuyi.com/idcard/idface/Submit.json

2.3 请求参数

参数名称	参数值描述	必填
account	APIID（用户中心【身份信息核验】-【产品总览】查看）	是
password	1、APIKEY（用户中心【身份信息核验】-【产品总览】查看） 2、动态密码（生成动态密码方式请看该文档末尾的说明）	是
name	身份证姓名	是
id_card_no	身份证号码	是
faceType	对接方式（固定值 H5或SDK）	是
callbackUrl	H5方式认证完成后的回调地址	二选一
notifyUrl	SDK认证完后的异步通知地址	二选一

用户通过http 或 https提交请求到服务器后，服务器会返回一串json格式的字符串，SubmitResult结构说明如下：

参数名称	类型	描述
code	int	返回值为2时，表示提交成功
idcardid	string	当提交成功后，此字段为流水号，否则为0
msg	string	提交结果描述
id_card_no	身份证号码	是
result	object	认证结果
result.expire	string	url或faceToken的过期时间
result.originalUrl	string	H5的刷脸认证地址
result.faceToken	string	SDK的刷脸认证Token

2.4 响应示例

示例（成功）

{"code":2,"msg":"提交成功","idcardid":"16236437872836","result":{"expire": "1750918770965","url":"", "faceToken":"c02008be0a764c7e8f36d9c78773c6f5"}}

示例（失败）

{"code":405,"msg":"用户名或密码不正确","idcardid":"0","result":{"status":"","url":"", "faceToken":""}}

2.5 响应参数

code	msg
0	未知错误
1	提交失败
2	提交成功
400	非法ip访问
401	帐号不能为空
402	密码不能为空
403	应用不存在
404	姓名不能为空
4041	姓名格式不正确（2-10个中文汉字）
406	身份证号码不能为空
4061	身份证号码格式不正确
4070	异步通知URL不能为空
4071	对接方式不能为空
4072	对接方式只能为H5或SDK
4073	认证完成后重定向地址不能为空
405	API ID或API KEY不正确
4050	账号被冻结
40501	动态密码已过期
40502	动态密码校验失败
40505	没有签定合同
4051	剩余条数不足
4052	访问ip与备案ip不符
4086	通道无效
4010	通道配置错误

2.6 GET请求示例

https://api.ihuyi.com/idcard/idface/Submit.json?account=APIID&password=APIKEY&name=姓名&id_card_no=401123343333xxxxxxxxxxxxxx&faceType=H5&callbackUrl=http://xxx.com/xxx

3、余额查询

3.1 接口描述

通过接口可以方便的查询你的账户剩余条数。
内容格式为：Content-Type: application/x-www-form-urlencoded

3.2 请求地址

https://api.ihuyi.com/idcard/idface/GetNum.json

3.3 请求参数

参数名称	参数值描述	必填
account	APIID（用户中心【身份信息核验】-【产品总览】查看）	是
password	1、APIKEY（用户中心【身份信息核验】-【产品总览】查看） 2、动态密码（生成动态密码方式请看该文档末尾的说明）	是
time	Unix时间戳（10位整型数字，当使用动态密码方式时为必填）	否

用户通过http 或 https提交请求到服务器后，服务器会返回一串json格式的字符串，GetNumResult结构说明如下：

参数名称	类型	描述
code	int	状态返回值
msg	string	查询结果描述
num	string	剩余数量

3.4 响应示例

示例（成功）

{"code":2,"msg":"查询成功","num":123}

示例（失败）

{"code":405,"msg":"用户名或密码不正确","num":0}

3.5 响应参数

code	msg
2	查询成功
400	非法ip访问
401	帐号不能为空
402	密码不能为空
403	应用不存在
405	API ID或API KEY不正确
4050	账号被冻结
40501	动态密码已过期
40502	动态密码校验失败
4052	访问ip与备案ip不符

3.6 GET请求示例

https://api.ihuyi.com/idcard/idface/GetNum.json?account=APIID&password=APIKEY

4、认证结果查询

4.1 接口描述

通过接口可以方便的查询认证的结果。

内容格式为：Content-Type: application/x-www-form-urlencoded

4.2 请求地址

https://api.ihuyi.com/idcard/idface/GetResult.json

4.3 请求参数

参数名称	参数值描述	必填
account	APIID（用户中心【身份信息核验】-【产品总览】查看）	是
password	1、APIKEY（用户中心【身份信息核验】-【产品总览】查看） 2、动态密码（生成动态密码方式请看该文档末尾的说明）	是
idcardid	流水号	是
time	Unix时间戳（10位整型数字，当使用动态密码方式时为必填）	否

用户通过http 或 https提交请求到服务器后，服务器会返回一串json格式的字符串，GetResultResult结构说明如下：

参数名称	类型	描述
code	int	状态返回值
msg	string	查询结果描述
result	object	结果信息
result.status	string	刷脸结果状态 ING - 刷脸地址已申请 SUCCESS - 刷脸认证通过 FAIL - 刷脸认证失败
result.message	string	刷脸结果描述
result.livingScore	string	刷脸活体检测得分
result.similarity	string	刷脸照片相似度得分

4.4 响应示例

示例（成功）

{"code":2,"msg":"查询成功","reslut":{"status":"ING","message":"认证成功","livingScore":"100","similarity":"100"}}

示例（失败）

{"code":405,"msg":"用户名或密码不正确"}

4.5 响应参数

code	msg
2	查询成功
400	非法ip访问
401	帐号不能为空
402	密码不能为空
403	应用不存在
405	API ID或API KEY不正确
4050	账号被冻结
40501	动态密码已过期
40502	动态密码校验失败
4052	访问ip与备案ip不符
4060	流水号不能为空
4061	数据不存在

4.6 GET请求示例

https://api.ihuyi.com/idcard/idface/GetResult.json?account=APIID&password=APIKEY&idcardid=25062613492951372

5、认证结果推送

5.1 接口描述

用户先提供数据接收地址，然后绑定到互亿无线系统后台，平台会以POST方式实时的将回执信息推送到此地址，内容格式为：Content-Type: application/x-www-form-urlencoded。

5.2 推送参数

参数名称	类型	描述
status	string	刷脸结果状态 ING - 刷脸地址已申请 SUCCESS - 刷脸认证通过 FAIL - 刷脸认证失败
message	string	刷脸结果描述
livingScore	string	刷脸活体检测得分
similarity	string	刷脸照片相似度得分
idcardid	string	流水号

注意：
成功接收请输出字符 “success”（不包含引号）结束推送，否则以接收失败处理。每个回执最多推送 3 次。每次间隔叠加 60 秒。

6、生成动态密码方式

以PHP为例，提交认证的生成方式：

$time = time();
$password = md5($account.$apikey.$app.$name.$id_card_no.$time);

示例：

APIID： test
APIKEY：1q784322ba1******
app：idface
name：张三
id_card_no：40122111******
time：1651544941
结果：$password = md5("test1q784322ba1******idface张三40122111******1651544941");

注意：所以字符编码统一为UTF-8

查询剩余条数的生成方式：

$time = time();
$password = md5($account.$apikey.$app.$time);

示例：

APIID： test
APIKEY：1q784322ba1******
app：idface
time：1651544941
结果：$password = md5("test1q784322ba1******idface1651544941");

认证结果查询的生成方式：

$time = time();
$password = md5($account.$apikey.$app.$time);

示例：

APIID： test
APIKEY：1q784322ba1******
app：idface
time：1651544941
结果：$password = md5("test1q784322ba1******idface1651544941");

Unix时间戳参考地址：http://tool.chinaz.com/Tools/unixtime.aspx

7、如何实现UNIX时间戳

语言	代码
JAVA	String date = new java.text.SimpleDateFormat("dd/MM/yyyy HH:mm:ss").format(new java.util.Date(Unix timestamp *1000))
Linux	date -d @Unix timestamp
C	strptime(datetime, "%Y-%m-%d %H:%M:%S", &tm_time); unixtime = mktime(&tm_time);
C++	std::time_t t = std::time(0);
DELPHI	uses DateUtils; DateTimeToUnix(Now)
GO	import "time" cur := time.Now() timestamp := cur.UnixNano() / 1000000
Perl	先 my $time = Unix timestamp 然后 my ($sec, $min, $hour, $day, $month, $year) = (localtime($time))[0,1,2,3,4,5,6]
PHP	date("r", Unix timestamp)
Node.js	var date = new Date( time * 1000 ); var time = date.getTime()/1000;
Python	先 import time 然后 time.gmtime(Unix timestamp)
Ruby	Time.at(Unix timestamp)
SHELL	date +%s //UNIX 的时间戳;
VBScript / ASP	DateAdd("s", Unix timestamp, "01/01/1970 00:00:00")
VB6	DateDiff("s", "1970-1-1 0:0:0", ToUnixTime)
易语言	时间_到时间戳()

8、SDK对接

人脸核验SDK接入指南：https://www.ihuyi.com/demo/idface/idface-guide.html

SDK资源下载