# 版本

1.0

# 描述

此接口基于用户验证行为，输出姓名与身份证号核验结果以及攻击等衍生风险信息。

# 调用URL

https://api.megvii.com/faceid/faceguard

注意：在生产环境中，请使用HTTPS的通信方式。HTTP方式的通信属于不安全链路，存在安全风险，请勿在生产环境中使用。在生产环境中使用HTTP方式的，将无法得到服务可靠性保障。

# 调用方法

POST 注意：用 form-data 格式请求

# 权限

仅当用户接入FaceID产品后，才能调用FaceID各Web API。接入FaceID的流程请咨询FaceID商务人员。

# 参数

参数英文名	必选/可选	参数中文名	类型	参数说明
sign	必选	签名	String	调用此API客户的签名，具体的签名产生方式请查阅鉴权说明
sign_version	必选	签名算法版本	String	签名算法版本号，目前仅支持:"hmac_sha1"。
end_date	可选	回溯日期	String	格式:2017-11-01 1、若上传日期缺失，追溯日期取当前日期的前一天（T-1）； 2、若上传日期大于等于当前日期，追溯日期取当前日期的前一天（T-1）； 3、若上传日期小于当前日期，以上传日期（包含23:59:59）为准去追溯。
idcard_number	必选	证件号	String	二代身份证号对应加密方式的字符串；加密公式如下： SM2加密：Base64(SM2(18位身份证)) RSA加密：Base64(RSA(18位身份证))
idcard_name	必选	姓名	String	上文身份证号对应姓名的对应加密方式的字符串；加密公式如下： SM2加密：Base64(SM2(对应姓名)) RSA加密：Base64(RSA(对应姓名))
encryption_type	必选	加密类型	String	是否开启传输数据加密，详见加密说明： 0: 不开启 1: SM2 2: RSA

# 返回值说明

参数英文名	参数中文名	类型	参数说明
request_id	请求ID	String	用于区分每一次请求的唯一的字符串。除了发生错误404(API_NOT_FOUND)外，此字段必定返回
time_used	请求耗时	Int	整个请求所花费的时间，单位为毫秒
result_code	本次验证的结果状态码	Int	仅当http状态码为200时返回,本次验证的结果状态码，详见下方映射值
result_message	本次验证的结果状态值	String	可通过此字段信息知晓具体的原因。具体见：result_code & result_message 对照表
result	返回查询信息的加密结果包	String	仅result_code=1000时返回，此结果中包含查询结果详情。加密方法: SM2加密：Base64(查询结果信息的SM2加密结果) RSA加密：Base64(查询结果信息的RSA加密结果)
error	错误信息	String	当http状态码非200时返回，详见下方状态码

result 内容如下：

参数英文名	参数中文名	类型	参数说明
fagd_flag	查得标识	String	取值范围：0和1； 0：查无； 1：查得；
fagd_lasttime	历史最晚发生非真人验证的攻击距今时间（天）	Int	大于等于0的整数，未查得则输出-1。
fagd_recent1d_atckcnt	近1天发生非真人验证的攻击次数	Int	大于等于0的整数，未查得则输出-1。
fagd_recent3d_atckcnt	近3天发生非真人验证的攻击次数	Int	大于等于0的整数，未查得则输出-1。
fagd_recent7d_atckcnt	近7天发生非真人验证的攻击次数	Int	大于等于0的整数，未查得则输出-1。
fagd_recent14d_atckcnt	近14天发生非真人验证的攻击次数	Int	大于等于0的整数，未查得则输出-1。
fagd_recent30d_atckcnt	近30天发生非真人验证的攻击次数	Int	大于等于0的整数，未查得则输出-1。
fagd_recent60d_atckcnt	近60天发生非真人验证的攻击次数	Int	大于等于0的整数，未查得则输出-1。
fagd_recent120d_atckcnt	近120天发生非真人验证的攻击次数	Int	大于等于0的整数，未查得则输出-1。
fagd_recent180d_atckcnt	近180天发生非真人验证的攻击次数	Int	大于等于0的整数，未查得则输出-1。
fagd_recent1d_night_atckcntratio	近1天发生非真人验证的攻击中夜间【0点-6点】攻击比例	double	取值范围【0,1】未查得则输出-1
fagd_recent3d_night_atckcntratio	近3天发生非真人验证的攻击中夜间【0点-6点】攻击比例	double	取值范围【0,1】未查得则输出-1
fagd_recent7d_night_atckcntratio	近7天发生非真人验证的攻击中夜间【0点-6点】攻击比例	double	取值范围【0,1】未查得则输出-1
fagd_recent14d_night_atckcntratio	近14天发生非真人验证的攻击中夜间【0点-6点】攻击比例	double	取值范围【0,1】未查得则输出-1
fagd_recent30d_night_atckcntratio	近30天发生非真人验证的攻击中夜间【0点-6点】攻击比例	double	取值范围【0,1】未查得则输出-1
fagd_recent60d_night_atckcntratio	近60天发生非真人验证的攻击中夜间【0点-6点】攻击比例	double	取值范围【0,1】未查得则输出-1
fagd_recent120d_night_atckcntratio	近120天发生非真人验证的攻击中夜间【0点-6点】攻击比例	double	取值范围【0,1】未查得则输出-1
fagd_recent180d_night_atckcntratio	近180天发生非真人验证的攻击中夜间【0点-6点】攻击比例	double	取值范围【0,1】未查得则输出-1

# result_code & result_message 对照表

result_code	result_message	意义说明	是否计费
1000	SUCCESS	姓名与身份证号核验通过	是
3000	ID_NUMBER_NAME_NOT_MATCH	身份信息无效（1. 身份信息不匹配；2. 身份信息不存在）	是
3000	INVALID_NAME_FORMAT	idcard_name编码错误或不符合规则，如长度不在1~32长度范围或不是中文格式	否
3000	INVALID_IDCARD_NUMBER	idcard_number编码错误或身份证号不符合规则，如长度不是18，或者身份证号内部不符合规则	否
3000	END_DATE_ERROR	查询日期错误	否
3000	DATA_SOURCE_ERROR	第三方错误	否

# HTTP状态码

http 状态码	错误信息	说明
200		正常值，服务器成功返回用户请求的数据
400	KEY_NOT_FOUND	encryption_type开启加密，但未配置加密公钥和解密私钥
400	MISSING_ARGUMENTS:<key>	缺少某个必选参数
400	BAD_ARGUMENTS:<key>	某个参数解析出错（如格式错误，必须是数字，但是输入的是非数字字符串）
403	AUTHENTICATION_ERROR	无效签名
403	AUTHENTICATION_ERROR:<reason>	api_key被停用、调用次数超限、没有调用此API的权限，或者没有以当前方式调用此API的权限 <reason>取值: API_KEY_BE_DISCONTINUED:api_key被停用 IP_NOT_ALLOWED:不允许访问的IP Limit_reached:测试api_key调用量已达到上限 DENIED:无权限调用当前API EXPIRED_SIGN:签名已过期 INVALID_SIGN:无效签名其他可能的错误码
403	CONCURRENCY_LIMIT_EXCEEDED	并发数超过限制
404	API_NOT_FOUND	所调用的API不存在
500	INTERNAL_ERROR	如果持续出现此类错误，请及时联系旷视客服或商务