接入文档
FaceID高级版
APP接入
API接口
实证查询
实证查询

# 版本

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 “默认为空”。客户业务流水号,建议设置为您的业务相关的流水串号并且唯一,会在return时原封不动的返回给您的服务器,以帮助您确认对应业务的归属。此字段不超过128字节
必选 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开启加密,但未配置加密公钥和解密私钥
    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客服或商务
    该文档未解决您的疑问?查看常见问题