# 版本

5.0.0

# 描述

此接口用于获取身份证要素信息，SDK返回证件读取成功后请在5分钟内调取该接口进行查询，超时则过期失效。（该接口仅国内支持）

# 调用URL

https://api.megvii.com/faceid/v5/sdk/eid_result

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

# 调用方法

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

# 权限

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

# 参数

必选/可选	参数	类型	参数说明
必选	sign	String	调用此API客户的签名，具体的签名产生方式请查阅App-鉴权说明
必选	sign_version	String	签名算法版本号，请传递：hmac_sha1
必选	biz_token	String	get_biz_token接口获取的biz_token；用以标识本次查询数据对象
必选	encryption_type	String	是否开启传输数据加密 1: SM2（默认值） 2: RSA-AES

# 返回值说明

参数类别

参数

类型

参数说明

#基础返回信息

request_id

String

API 调用的流水号

time_used

Int

整个请求所花费的时间，单位为毫秒。此字段必定返回

error

String

当请求失败时才会返回此字符串，具体返回内容见后续错误信息章节，否则此字段不存在

#证件nfc信息

idcard_result

Json

证件类型	值
身份证	01
港澳台居民居住证	02
外国人永久居留证	03

当证件为身份证时，返回身份证nfc读取的要素信息

idtype（string类型）:证件类型，详见表格
name（string类型）：姓名
idcard_number（string类型）：身份证号
nation（string类型）：民族
gender（string类型）：性别
birth（string类型）：出生日期
address（string类型）：住址栏
issued_by（string类型）：签发机关
valid_date_start（string类型）：有效期限起始时间
valid_date_end（string类型）：有效期限结束时间
portrait: 证件头像，base64编码

当证件为港澳台居住证时，返回港澳台居住证nfc读取的要素信息

idtype（string类型）:证件类型，详见表格
name（string类型）：姓名
idcard_number（string类型）：身份证号
gender（string类型）：性别
birth（string类型）：出生日期
address（string类型）：住址栏
issued_by（string类型）：签发机关
valid_date_start（string类型）：有效期限起始时间
valid_date_end（string类型）：有效期限结束时间
other_idnum（string类型）：通行证号
signing_times（string类型）：签发次数
portrait: 证件头像，base64编码

当证件为外国人居住证时，返回外国人居住证nfc读取的要素信息

idtype:证件类型，详见表格
name（string类型）：中文姓名
enname（string类型）：英文姓名
idcard_number（string类型）：身份证号
country_code（string类型）：国籍或所在地区代码
gender（string类型）：性别
birth（string类型）：出生日期
issued_by（string类型）：签发机关
portrait: 证件头像，base64编码

# 返回值示例

正确请求返回示例

{   
    "request_id":"1655896702,9c48cf7d-d822-4ebd-8267-b80d76f771ec",
    "result_code":1000,
    "result_message":"SUCCESS",
    "time_used":293,
    "idcard_result":"xxxx"
}

失败请求返回示例

{
    "time_used": 1394,
    "idcard_result": "",
    "result_message": "EXPIRED_ERROR",
    "result_code": 2000,
    "request_id": "1655951863,b0c2d80b-fbf0-41fb-bdc1-209be2ce7c6a"
}

# result_code & result_message 对照表

result_code	result_message	含义解释	是否计费
1000	SUCCESS	查询成功，同一个token查询有效期为5分钟，有效期内重复查询不重复计费	是
2000	EXPIRED_ERROR	查询已失效，请务必在用户完成实证读取成功五分钟内完成	否
2100	EID_READ_UNDONE	该token未完成实证读取，请完成后查询	否
3000	SYSTEM_ERROR	参数错误，请联系技术支持	否
4000	NETWORK_TIME_OUT	网络不给力，请稍后重试	否

# 错误码列表

HTTP状态代码	错误信息	说明
400	MISSING_ARGUMENTS:<key>	缺少某个必选参数
400	BAD_ARGUMENTS:<key>	某个参数解析出错（比如必须是数字，但是输入的是非数字字符串; 或者长度过长），包括TOKEN失效
400	KEY_NOT_FOUND	encryption_type开启加密，但未配置加密公钥和解密私钥
400	FMP_CONTENT_TYPE_ERROR	视频错误，请重试或更换手机重试
403	AUTHENTICATION_ERROR	无效签名
403	AUTHORIZATION_ERROR:<reason>	api_key被停用、调用次数超限、没有调用此API的权限，或者没有以当前方式调用此API的权限 <reason>取值： API_KEY_BE_DISCONTINUED：api_key被停用 IP_NOT_ALLOWED：不允许访问的IP（预留设计） LIMIT_REACHED：这个api_key对当前API的调用量达到上限。仅当api_key为测试key DENIED：无权限调用当前API EXPIRED_SIGN：签名已过期 INVALID_SIGN：无效签名其他可能的错误码，请预留处理方案
403	CONCURRENCY_LIMIT_EXCEEDED	并发数超过限制
404	API_NOT_FOUND	所调用的API不存在
500	INTERNAL_ERROR	服务器内部错误，当此类错误发生时请再次请求，如果持续出现此类错误，请及时联系FaceID客服或商务