/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

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 file or image_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"
}

5.Sample

results matching ""

    No results matching ""