/ocr/idcard - 身份证识别接口
1.API 说明
2.请求参数
3.响应参数
4.错误码
5.示例
1.API 说明
该 API 用于识别巴西身份证(RG / CIN,Registro de Identidade Civil)并提取关键信息,支持卡片正面与背面。
图片规格
1. 格式:JPG(JPEG)、PNG
2. 像素范围:128*128 到 6000*6000,推荐分辨率为 1280*1280
3. 文件大小不得超过 5MB
请求方法
POST
请求地址
https://cloudapi.brazil.accuauth.com/ocr/idcard
Debugging Tool
2.请求参数
2.1 请求头
| 参数 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
| X-DF-API-ID | string | Yes | API 认证信息请参见 API 请求 |
| X-DF-API-SECRET | string | Yes | API 认证信息请参见 API 请求 |
2.2 请求体
| Fields | 类型 | 描述 | |
|---|---|---|---|
| optional | file | file | 图像的二进制数据 |
| optional | image_base64 | string | 图像的 Base64 编码数据 |
| optional | detect_face | integer | 1: 启用人脸检测,返回 face_region 字段; 0: 默认值,关闭人脸检测. |
Either parameter
fileorimage_base64必须提供作为请求参数.使用
file参数时,必须将图像流添加到 POST 请求的 multipart/form-data 部分。
3.响应参数
| Fields | 类型 | 描述 |
|---|---|---|
| request_id | string | 每个请求的唯一 ID |
| status | string | 响应状态:OK 表示成功,失败请参考错误码 |
| results | array | 身份证识别结果数组,详见下方 results 字段 |
results中的字段:
| Fields | 类型 | 描述 |
|---|---|---|
| card_side | string | 卡片正反面:front 表示正面(个人信息页)/ back 表示背面(含 MRZ 机读区) |
| card_info | object | 卡片的关键信息 |
| face_region | array | 人脸区域四个点坐标,格式为: [(x1, y1), (x2, y2), (x3, y3), (x4, y4)]; 坐标基于原始图像, 坐标顺序为旋转后人脸的:左上、右上、右下、左下. 仅在 detect_face=1 时返回 |
说明:巴西身份证不返回
card_type字段,正反面仅通过card_side区分。
card_info中的字段
说明:
card_info中所有字段均为 string 类型,识别失败时返回""。字段名以_s结尾的为标准化后的值,其余为卡面(或 MRZ)原始识别值;日期类字段的_s版本统一格式化为DD-MM-YYYY。
- 正面(
card_side=front)
| Fields | 类型 | 描述 |
|---|---|---|
| id_number | string | 证件号码(NÚMERO RIC),仅保留数字,如 1234567890 |
| id_number_raw | string | 卡面原始证件号码(保留点、空格、短横线),如 12345678-90;卡面值中出现数字、点、空格、短横线以外的字符时,本字段与 id_number 均返回 "" |
| name | string | 姓名(NOME),如 MARIA RIBEIRO DA SILVA |
| gender | string | 性别(SEXO),M:男,F:女;非 M/F 时返回 "" |
| nationality | string | 国籍(NACIONALIDADE),卡面原始值,如 BRASILEIRA |
| birthday | string | 出生日期(DATA DE NASCIMENTO),卡面原始值,如 01.01.2000 |
| birthday_s | string | 格式化后的出生日期,格式为 DD-MM-YYYY |
| expiry_date | string | 有效期至(DATA DE VALIDADE),卡面原始值,如 01.01.2030 |
| expiry_date_s | string | 格式化后的有效期,格式为 DD-MM-YYYY |
| issuing_state | string | 签发州名称(ESTADO),已去除 ESTADO DE/DA/DO 前缀,如 MATO GROSSO |
| issuing_state_code | string | 签发州代码(UF),两位字母,如 MT |
- 背面(
card_side=back)
| Fields | 类型 | 描述 |
|---|---|---|
| id_number | string | 证件号码,取自背面 MRZ 的 9 位文档号,与 document_number 相同 |
| document_number | string | 背面 MRZ 第一行解析出的 9 位文档号,如 123456789 |
| name | string | 姓名,取自背面 MRZ 第三行,< 填充符替换为空格 |
| gender | string | 性别,取自背面 MRZ 第二行,M:男,F:女;无法判定时返回 "" |
| nationality | string | 国籍代码,取自背面 MRZ 第二行,如 BRA |
| birthday | string | 出生日期,MRZ 原始值,格式为 YYMMDD,如 000101 |
| birthday_s | string | 格式化后的出生日期,格式为 DD-MM-YYYY(按 MRZ 规则推断世纪) |
| expiry_date | string | 有效期至,MRZ 原始值,格式为 YYMMDD,如 300101 |
| expiry_date_s | string | 格式化后的有效期,格式为 DD-MM-YYYY(按 MRZ 规则推断世纪) |
| doc_origin | string | 证件来源/登记信息(DOC. ORIGEM),如 BRASIL - BR CN.LV A1871 FLS. 12 / N.01245 |
| rg_number | string | RG 号码(RG / UF),仅保留数字 |
| rg_uf | string | RG 签发州代码(UF),两位字母,如 SP;无该信息时返回 "" |
| cpf | string | CPF 税号,仅保留数字;位数不为 11 位或含非法字符时返回 "" |
| voter_id | string | 选民证号(TÍTULO DE ELEITOR),仅保留数字 |
| nis | string | NIS / PIS 号,仅保留数字;位数不为 11 位或含非法字符时返回 "" |
| parentage | string | 父母姓名(FILIAÇÃO),父亲与母亲姓名以空格连接 |
| birth_place | string | 出生地/籍贯(NATURALIDADE),如 MUNICIPIO DO BRASIL/BR |
| issue_authority | string | 签发机关(ÓRGÃO EMISSOR) |
| issue_place | string | 签发地点(LOCAL),如 BRASIL/BR |
| issue_date | string | 签发日期(DATA DA EXPEDIÇÃO),卡面原始值,如 01/01/2020 |
| issue_date_s | string | 格式化后的签发日期,格式为 DD-MM-YYYY |
| line1_all | string | MRZ 第一行原始内容(已去除空格与 \,统一大写),如 IDBRA123456789<<<<<<<<<<<<< |
| line2_all | string | MRZ 第二行原始内容(已去除空格与 \,统一大写),如 0001010F3001010BRA<<<<<<<<<<0 |
| line3_all | string | MRZ 第三行原始内容(已去除空格与 \,统一大写),如 MARIA<<RIBEIRO<<DA<SILVA<< |
说明:背面的
id_number、document_number、name、gender、nationality、birthday、expiry_date均从背面 MRZ 机读区解析,其中O/I/L与0/1的 OCR 混淆字符已自动纠正。
返回示例
- 正面
{
"request_id": "TID8bf47ab6eda64476973cc5f5b6ebf57e",
"status": "OK",
"results": [{
"card_side": "front",
"card_info": {
"id_number": "1234567890",
"id_number_raw": "12345678-90",
"name": "MARIA RIBEIRO DA SILVA",
"gender": "F",
"nationality": "BRASILEIRA",
"birthday": "01.01.2000",
"birthday_s": "01-01-2000",
"expiry_date": "01.01.2030",
"expiry_date_s": "01-01-2030",
"issuing_state": "MATO GROSSO",
"issuing_state_code": "MT"
},
"face_region": [
[
494,
137
],
[
637,
137
],
[
637,
353
],
[
494,
353
]
]
}]
}
- 背面
{
"request_id": "TIDcfa616942c0e4c4cb3870cfb9b1a94be",
"status": "OK",
"results": [{
"card_side": "back",
"card_info": {
"id_number": "123456789",
"document_number": "123456789",
"name": "MARIA RIBEIRO DA SILVA",
"gender": "F",
"nationality": "BRA",
"birthday": "000101",
"birthday_s": "01-01-2000",
"expiry_date": "300101",
"expiry_date_s": "01-01-2030",
"doc_origin": "BRASIL - BR CN.LV A1871 FLS. 12 / N.01245",
"rg_number": "123456789",
"rg_uf": "SP",
"cpf": "00000000000",
"voter_id": "123456789012",
"nis": "12345678901",
"parentage": "JOSE CARVALHO DA SILVA ANA MARIA DE OLIVEIRA DA SILVA",
"birth_place": "MUNICIPIO DO BRASIL/BR",
"issue_authority": "ORGAO ESTADO DO BRASIL",
"issue_place": "BRASIL/BR",
"issue_date": "01/01/2020",
"issue_date_s": "01-01-2020",
"line1_all": "IDBRA123456789<<<<<<<<<<<<<",
"line2_all": "0001010F3001010BRA<<<<<<<<<<0",
"line3_all": "MARIA<<RIBEIRO<<DA<SILVA<<"
}
}]
}
4.错误码
常见错误码如下:
| HTTP 状态码 | Status field |
描述 |
|---|---|---|
400 |
INVALID_ARGUMENT | 请求参数无效 |
400 |
DETECTION_FAILED | 图像检测失败 |
401 |
UNAUTHORIZED | 未授权或无访问权限 |
401 |
KEY_EXPIRED | API ID 已过期 |
403 |
NO_PERMISSION | 您无权限使用该接口 |
403 |
OUT_OF_QUOTA | API 调用次数超限 |
403 |
RATE_LIMIT_EXCEEDED | 请求频率超限 |
404 |
NOT_FOUND | 接口不存在 |
500 |
INTERNAL_ERROR | 服务器内部错误 |
说明: 当出现 40X 错误时,请查看响应中的 reason 字段以获取详细信息。
错误返回示例:
{
"status": "INVALID_ARGUMENT",
"reason": "must specify 'file' or 'image_base64' argument",
"request_id": "TID8bf47ab6eda64476973cc5f5b6ebf57e"
}