# 描述

检测和识别银行卡的卡号信息。

# 调用URL

https://api.megvii.com/faceid/v3/ocrbankcard

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

# 调用方法

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

# 参数

必选/可选	参数名	类型	参数说明
必选	api_key	String	用于验证客户身份的API Key
必选	api_secret	String	用于验证客户身份的API Secret
必选	image	File	二进制图片文件，需要用post multipart/form-data的方式上传图片要求：尺寸：最小边长大于256像素，最大边长小于4096像素体积：5MB以内支持横版、竖版银行卡识别卡片在图像中占比要求：大于1/20，平面旋转360度均可识别，非平面：20度内
可选	return_cardnum_crop	String	是否返回cardnum_crop 0：默认值，不开启 1：开启返回

# 返回值说明

字段	类型	说明
request_id	String	用于区分每一次请求的唯一的字符串
time_used	Int	整个请求所花费的时间，单位为毫秒
result	Int	表示图片的上传结果 1000系列表示照片上传成功： 1001：图片上传成功，说明上传的图片中检测到了银行卡，图中若包含多张银行卡将随机返回其中一张的信息 2000系列表示照片上传失败: 2001：图片格式不支持 2002：图片中未检测到银行卡 2003：图片大小不符合要求其他错误码，请预留处理方案
number	String	识别出来的卡号信息。仅当“result=1001”时返回例如："6214 5633 7623 5364" (返回值中包含空格) 注：当中间某些字符出现遮挡，模糊等无法识别的情况出现时，该字段的返回值中可能包含“”，例如：6214 5633 76* 5364
bank	String	表示银行卡所属的银行，内容为银行的名字。仅当“result=1001”时返回；如果没有识别到，则返回“null”
organization	String	表示银行卡上面的金融组织。仅当“result=1001”时返回；如果没有识别到列表内的组织，则返回“null” 目前会返回的组织内容如下：UnionPay、MasterCard、JCB、VISA （注：如有多个卡组织，以“,”分隔）
valid_date	String	预留设计，该功能尚未启用，默认返回“null” 银行卡片上的有效期。一般的信用卡均会有该数据，但是储蓄卡会不存在。仅当“result=1001”时返回，未识别到会返回“null” 该字段的返回格式通常为"09/23"，一些卡片可能会有具体日期，所以会有两个"/"
name	String	预留设计，该功能尚未启用，默认返回“null” 表示银行卡上的姓名，通常信用卡才会返回。仅当“result=1001”时返回；如果未识别到，则返回“null”
position	Object	仅当“result=1001”时返回银行卡四个角的像素点坐标，包含以下属性： left_top：银行卡左上角的像素点坐标 right_top：银行卡右上角的像素点坐标 left_bottom：银行卡左下角的像素点坐标 right_bottom：银行卡右下角的像素点坐标每个属性都包含以下字段，每个字段的值都是整数 x：像素点横坐标位置 y：像素点纵坐标位置
cardnum_crop	Object	仅当“result=1001”时返回 image（base64编码）：银行卡号图片 rect（Dict）：银行卡号四点的坐标，"right_top"{ "y":43, "x":927 } //右上角坐标 "left_top"{ "y":33, "x":58 } //左上角坐标 "left_bottom"{ "y":586, "x":59 } //左下角坐标 "right_bottom"{ "y":580, "x":920 } //右下角坐标
error	String	当请求失败时才会返回此字符串，具体返回内容见后续错误信息章节，成功识别则此字段不存在

# 返回值示例

正确示例

{
    "time_used": 593,
    "request_id": "1505886713,236eb3a1-55fe-4e55-ae69-780dd1b2f2d1",
    "number": "1234 5678 9012 3456",
    "result": 1001,
    "position": {
        "left_bottom": {
            "y": 914,
            "x": 453
        },
        "right_top": {
            "y": 138,
            "x": 1598
        },
        "right_bottom": {
            "y": 879,
            "x": 1621
        },
        "left_top": {
            "y": 173,
            "x": 431
        }
    },
    "name": "null",
    "organization": "null",
    "valid_date": "null",
    "bank": "null"
}

失败示例

{
    "time_used": 1,
    "request_id": "1505982688,33503f95-c001-478a-8525-a04dec1b2b28",
    "error": "MISSING_ARGUMENTS: image"
}

# 错误码列表

HTTP状态代码	错误信息	说明
403	AUTHENTICATION_ERROR	api_key 和 api_secret 不匹配
403	AUTHORIZATION_ERROR: <reason>	api_key被停用、调用次数超限、没有调用此API的权限，或者没有以当前方式调用此API的权限 <reason>取值： "DENIED." : api_key无权限或被停用 "Limit reached." : 这个api_key对当前API的调用量达到上限。仅当api_key为测试key时返回其他可能的错误码，请预留处理方案
403	CONCURRENCY_LIMIT_EXCEEDED	并发数超过限制
400	MISSING_ARGUMENTS: <key>	缺少某个必选参数
400	BAD_ARGUMENTS: <key>	某个参数解析出错（比如必须是数字，但是输入的是非数字字符串; 或者长度过长）
404	API_NOT_FOUND	所调用的API不存在
413	Request Entity Too Large	客户发送的请求大小超过了5MB限制。该错误的返回格式为纯文本，不是json格式
500	INTERNAL_ERROR	服务器内部错误，当此类错误发生时请再次请求，如果持续出现此类错误，请及时联系 FaceID 客服或商务

# 调用示例

curl "https://api.megvii.com/faceid/v3/ocrbankcard" -F api_key=<api_key> -F api_secret=<api_secret> –F [image=@id.jpg]