人臉核身 - API文檔

1、接口概要

1.1 文檔說(shuō)明

本文檔主要提供給互億平臺(tái)的用戶對(duì)接接口的使用說(shuō)明，開發(fā)者可以利用互億無(wú)線提供的 HTTP 接口，調(diào)用互億無(wú)線的人臉核身服務(wù)。

1.2 提交方式

GET / POST

1.3 加密方式

1、采用HTTPS協(xié)議提交請(qǐng)求
2、通過MD5動(dòng)態(tài)簽名方式加密

1.4 API ID / API KEY

登錄用戶中心，進(jìn)入“產(chǎn)品與服務(wù) -》 認(rèn)證核驗(yàn) -》身份信息核驗(yàn)”，在【產(chǎn)品總覽】頁(yè)面右側(cè)，如下圖所示：

2、提交認(rèn)證

2.1 接口描述

通過POST、GET方式進(jìn)行提交，數(shù)據(jù)編碼采用utf-8格式，支持24小時(shí)全天提交。
內(nèi)容格式為：Content-Type: application/x-www-form-urlencoded

2.2 請(qǐng)求地址

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

2.3 請(qǐng)求參數(shù)

參數(shù)名稱	參數(shù)值描述	必填
account	APIID（用戶中心【身份信息核驗(yàn)】-【產(chǎn)品總覽】查看）	是
password	1、APIKEY（用戶中心【身份信息核驗(yàn)】-【產(chǎn)品總覽】查看） 2、動(dòng)態(tài)密碼（生成動(dòng)態(tài)密碼方式請(qǐng)看該文檔末尾的說(shuō)明）	是
name	身份證姓名	是
id_card_no	身份證號(hào)碼	是
faceType	對(duì)接方式（固定值 H5或SDK）	是
callbackUrl	H5方式認(rèn)證完成后的回調(diào)地址	二選一
notifyUrl	SDK認(rèn)證完后的異步通知地址	二選一
time	Unix時(shí)間戳（10位整型數(shù)字，當(dāng)使用動(dòng)態(tài)密碼方式時(shí)為必填）	否

2.4 響應(yīng)示例

示例（成功）

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

示例（失?。?/p>

{"code":405,"msg":"用戶名或密碼不正確","idcardid":"0","result":{"status":"","url":"", "faceToken":""}}

2.5 響應(yīng)參數(shù)

code	msg
0	未知錯(cuò)誤
1	提交失敗
2	提交成功
400	非法ip訪問
401	帳號(hào)不能為空
402	密碼不能為空
403	應(yīng)用不存在
404	姓名不能為空
4041	姓名格式不正確（2-10個(gè)中文漢字）
406	身份證號(hào)碼不能為空
4061	身份證號(hào)碼格式不正確
4070	異步通知URL不能為空
4071	對(duì)接方式不能為空
4072	對(duì)接方式只能為H5或SDK
4073	認(rèn)證完成后重定向地址不能為空
405	API ID或API KEY不正確
4050	賬號(hào)被凍結(jié)
40501	動(dòng)態(tài)密碼已過期
40502	動(dòng)態(tài)密碼校驗(yàn)失敗
40505	沒有簽定合同
4051	剩余條數(shù)不足
4052	訪問ip與備案ip不符
4086	通道無(wú)效
4010	通道配置錯(cuò)誤

2.6 GET請(qǐng)求示例

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 接口描述

通過接口可以方便的查詢你的賬戶剩余條數(shù)。
內(nèi)容格式為：Content-Type: application/x-www-form-urlencoded

3.2 請(qǐng)求地址

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

3.3 請(qǐng)求參數(shù)

參數(shù)名稱	參數(shù)值描述	必填
account	APIID（用戶中心【身份信息核驗(yàn)】-【產(chǎn)品總覽】查看）	是
password	1、APIKEY（用戶中心【身份信息核驗(yàn)】-【產(chǎn)品總覽】查看） 2、動(dòng)態(tài)密碼（生成動(dòng)態(tài)密碼方式請(qǐng)看該文檔末尾的說(shuō)明）	是
time	Unix時(shí)間戳（10位整型數(shù)字，當(dāng)使用動(dòng)態(tài)密碼方式時(shí)為必填）	否

用戶通過http 或 https提交請(qǐng)求到服務(wù)器后，服務(wù)器會(huì)返回一串json格式的字符串，GetNumResult結(jié)構(gòu)說(shuō)明如下：

參數(shù)名稱	類型	描述
code	int	狀態(tài)返回值
msg	string	查詢結(jié)果描述
num	string	剩余數(shù)量

3.4 響應(yīng)示例

示例（成功）

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

示例（失?。?/p>

{"code":405,"msg":"用戶名或密碼不正確","num":0}

3.5 響應(yīng)參數(shù)

code	msg
2	查詢成功
400	非法ip訪問
401	帳號(hào)不能為空
402	密碼不能為空
403	應(yīng)用不存在
405	API ID或API KEY不正確
4050	賬號(hào)被凍結(jié)
40501	動(dòng)態(tài)密碼已過期
40502	動(dòng)態(tài)密碼校驗(yàn)失敗
4052	訪問ip與備案ip不符

3.6 GET請(qǐng)求示例

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

4、認(rèn)證結(jié)果查詢

4.1 接口描述

通過接口可以方便的查詢認(rèn)證的結(jié)果。

內(nèi)容格式為：Content-Type: application/x-www-form-urlencoded

4.2 請(qǐng)求地址

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

4.3 請(qǐng)求參數(shù)

參數(shù)名稱	參數(shù)值描述	必填
account	APIID（用戶中心【身份信息核驗(yàn)】-【產(chǎn)品總覽】查看）	是
password	1、APIKEY（用戶中心【身份信息核驗(yàn)】-【產(chǎn)品總覽】查看） 2、動(dòng)態(tài)密碼（生成動(dòng)態(tài)密碼方式請(qǐng)看該文檔末尾的說(shuō)明）	是
idcardid	流水號(hào)	是
time	Unix時(shí)間戳（10位整型數(shù)字，當(dāng)使用動(dòng)態(tài)密碼方式時(shí)為必填）	否

用戶通過http 或 https提交請(qǐng)求到服務(wù)器后，服務(wù)器會(huì)返回一串json格式的字符串，GetResultResult結(jié)構(gòu)說(shuō)明如下：

參數(shù)名稱	類型	描述
code	int	狀態(tài)返回值
msg	string	查詢結(jié)果描述
result	object	結(jié)果信息
result.status	string	刷臉結(jié)果狀態(tài) ING - 刷臉地址已申請(qǐng) SUCCESS - 刷臉認(rèn)證通過 FAIL - 刷臉認(rèn)證失敗
result.message	string	刷臉結(jié)果描述
result.livingScore	string	刷臉活體檢測(cè)得分
result.similarity	string	刷臉照片相似度得分

4.4 響應(yīng)示例

示例（成功）

{"code":2,"msg":"查詢成功","reslut":{"status":"ING","message":"認(rèn)證成功","livingScore":"100","similarity":"100"}}

示例（失?。?/p>

{"code":405,"msg":"用戶名或密碼不正確"}

4.5 響應(yīng)參數(shù)

code	msg
2	查詢成功
400	非法ip訪問
401	帳號(hào)不能為空
402	密碼不能為空
403	應(yīng)用不存在
405	API ID或API KEY不正確
4050	賬號(hào)被凍結(jié)
40501	動(dòng)態(tài)密碼已過期
40502	動(dòng)態(tài)密碼校驗(yàn)失敗
4052	訪問ip與備案ip不符
4060	流水號(hào)不能為空
4061	數(shù)據(jù)不存在

4.6 GET請(qǐng)求示例

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

5、認(rèn)證結(jié)果推送

5.1 接口描述

用戶先提供數(shù)據(jù)接收地址，然后綁定到互億無(wú)線系統(tǒng)后臺(tái)，平臺(tái)會(huì)以POST方式實(shí)時(shí)的將回執(zhí)信息推送到此地址，內(nèi)容格式為：Content-Type: application/x-www-form-urlencoded。

5.2 推送參數(shù)

參數(shù)名稱	類型	描述
status	string	刷臉結(jié)果狀態(tài) ING - 刷臉地址已申請(qǐng) SUCCESS - 刷臉認(rèn)證通過 FAIL - 刷臉認(rèn)證失敗
message	string	刷臉結(jié)果描述
livingScore	string	刷臉活體檢測(cè)得分
similarity	string	刷臉照片相似度得分
idcardid	string	流水號(hào)

注意：
成功接收請(qǐng)輸出字符 “success”（不包含引號(hào)）結(jié)束推送，否則以接收失敗處理。每個(gè)回執(zhí)最多推送 3 次。每次間隔疊加 60 秒。

6、生成動(dòng)態(tài)密碼方式

以PHP為例，提交認(rèn)證的生成方式：

$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
結(jié)果：$password = md5("test1q784322ba1******idface張三40122111******1651544941");

注意：所以字符編碼統(tǒng)一為UTF-8

查詢剩余條數(shù)的生成方式：

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

示例：

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

認(rèn)證結(jié)果查詢的生成方式：

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

示例：

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

Unix時(shí)間戳參考地址：http://tool.chinaz.com/Tools/unixtime.aspx

7、如何實(shí)現(xiàn)UNIX時(shí)間戳

語(yǔ)言	代碼
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 的時(shí)間戳;
VBScript / ASP	DateAdd("s", Unix timestamp, "01/01/1970 00:00:00")
VB6	DateDiff("s", "1970-1-1 0:0:0", ToUnixTime)
易語(yǔ)言	時(shí)間_到時(shí)間戳()

8、SDK對(duì)接

人臉核驗(yàn)SDK接入指南：http://www.skoolfish.com/demo/idface/idface-guide.html

SDK資源下載