# 1 功能描述

支持海外卡证的OCR 识别服务
支持四点检测、质量检测、翻拍结果、PS 检测、AIGC检测、水印检测
支持证件范围：

证件类型	支持国家
身份证	印尼、菲律宾、墨西哥

# 2 使用说明

# 2.1 调用URL

新加坡地址：https://api-sgp.yljz.com/finauth/v5/oversea_ocr
印尼地址：https://api-idn.yljz.com/finauth/v5/oversea_ocr

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

# 2.2 调用方法

请求方式：POST
请求格式：form-data
说明：客户传入通过apikey和secret生成的加密签名sign，同时提供含有证件的照片。我方返回证件的识别结果。

# 3 请求参数

参数	参数名	必填	类型	说明
sign	签名	是	String	签名生成规则参考鉴权说明
sign_version	签名算法版本号	是	String	请传递：hmac_sha1
certificate_id	证件类型id	是	String	墨西哥选民证：MX_ID 印尼身份证：ID_ID 菲律宾身份证：PH_ID
image	图片	是	File	客户方自行拍摄的含卡证的照片（客户需要自行保证照片质量，我方不进行质量检测）图片限制： 1. 图片大小 ≤ 5MB 2. 分辨率≤ 5000× 5000 px 3. 格式：JPG/JPEG/PNG
biz_token	token	否	String	sdk采集时的唯一标识，sdk采集后得到的token，可直接用于ocr识别，无需上传采集图片，图片与token同时传入时，以图片为准，无降级逻辑，该toekn24小时内有效
biz_no	业务流水号	否	String	本次业务的业务流水号
quad_detection	四点检测	否	String	默认0 0：仅开启四点检测，不返回四点裁图。 1：开启四点检测，并返回四点裁图。
screen	翻拍检测	否	String	默认0不开启。 0: 不开启翻拍检测 1: 开启翻拍检测
extract	识别开启	否	String	默认1开启 0：不开启识别 1：开启识别
quality	质量检测	否	String	默认0不开启 0：不开启质量检测 1：开启质量检测
ps	ps检测	否	String	默认0不开启 0：不开启 1：开启
aigc	aigc检测	否	String	默认0不开启 0：不开启 1：开启
watermark	水印检测	否	String	默认0不开启 0：不开启 1：开启
photocopy	复印检测	否	String	支持复印和彩印的检测，默认0不开启 0：不开启 1：开启
sticker	贴图检测	否	String	默认0不开启 0：不开启 1：开启
face_detect	是否传回证件头像照	否	String	默认0不开启 0：不开启 1：开启

# 4 返回参数

备注：不同卡证类型下返回部分适用的字段，非全部字段。

字段	字段名	类型	参数说明
request_id	请求号	String	用于区分每一次请求的唯一的字符串。除非发生404（API_NOT_FOUND）或 403 （AUTHORIZATION_ERROR）错误，剩余情况此字段必定返回
time_used	请求耗时	Int	整个请求所花费的时间，单位为毫秒。此字段必定返回
biz_no	业务流水号	String	传入的业务流水号，原封不动地返回
extract_result	识别结果	JSON	json 格式（如图片中有多张证件，只返回证件号confidence值最高的一张证件信息）不同证件类型ID返回内容会不同
quad_detection	四点检测结果	String	当quad_detection=0/1 时生效0: 四点检测无问题，通过1: 四点检测不通过服务不可用时返回null
quad_detection_image	四点剪裁证件照	String	当quad_detection=1 时，返回Base64编码
quality	质量结果	String	当quality=1 时生效 0: 质量正常 1: 有质量问题服务不可用时返回null
screen	翻拍结果	String	当screen=1 时生效 0: 无翻拍 1: 证件存在翻拍服务不可用时返回null
ps	PS检测结果	String	ps=1 时生效 0: 无ps 1: 证件存在ps 服务不可用时返回null
aigc	AIGC检测结果	String	aigc=1 时生效 0: 非AIGC 证件 1: AIGC证件服务不可用时返回null
watermark	水印检测结果	String	当watermark=1 时生效 0: 无水印 1: 图片存在水印服务不可用时返回null
photocopy	复印检测结果	String	photocopy=1 时生效 0: 无复印 1: 图片存在复印服务不可用时返回null
sticker	贴图检测结果	String	sticker=1 时生效 0: 无贴图 1: 图片存在贴图服务不可用时返回null
face	人脸信息	JSON	在照片中检测到的所有人脸信息。1. 若未检测到人脸，则返回 null（注：此条描述待研发设计确认后修改）；2. 若检测到多张人脸，则返回质量分最高的那张
face_detect_image	证件头像	String	人脸框的裁图，非大头照。证件上的头像以 Base64 编码格式返回。若未检测到人脸或人脸质量不合格，则返回 null；若卡证上有多个头像，则返回质量分最高的
quality	人脸质量分	Float	每张人脸都会有一个质量判断的分数
quality_threshold	人脸阈值	Float	人脸质量基本合格的判定阈值，超过该阈值的人脸适合用于人脸比对
rect	人脸框位置	JSON	图片中人脸框的位置，用一个 Json 表示，基于quad_detection_image裁剪后图片的人脸框位置
left	人脸框的左上角	Float	人脸框的左上角（以图片宽度的比例给出）的 x 坐标
top	人脸框的左上角	Float	人脸框的左上角（以图片高度的比例给出）的 y 坐标
width	人脸框的宽度	Float	人脸框的宽度（以图片宽度的比例给出）
height	人脸框的高度	Float	人脸框的高度（以图片高度的比例给出）
ocr_warninfos	警告信息	Json	返回值与“extract_result识别结果”字段一致，但内容会返回如下告警信息，无告警时不返回遮挡读不出: occluded 模糊读不出: blurred 阴影读不出: shadow 强光斑过曝读不出: glared
error	错误信息	String	发生错误后，会返回对应的错误码

# 5 ERROR错误信息对照表

HTTP 状态代码	返回码	是否计费	说明
200	SUCCESS	是	调用成功
400	INVALID_IMAGE_SIZE: image	否	客户发送的请求单张照片大小超过了5MB限制。该错误的返回格式为纯文本，不是json格式
400	MISSING_ARGUMENTS:	否	缺少某个必要参数
400	COLLECT_SERIAL_NO_NOT_EXIST	否	token不存在或已过期
400	BAD_ARGUMENTS:	否	某个参数解析出错（比如：必须是数字，但是输入的是字符串; 或者长度过长，或者照片无法解析）
400	ID_CARD_NOT_FOUND	否	图片中没有找到卡证，或因质量过差而无法识别
404	API_NOT_FOUND	否	所调用的API不存在
403	AUTHORIZATION_ERROR	否	无效签名
403	AUTHORIZATION_ERROR:	否	api_key被停用、调用次数超限、没有调用此API的权限或者没有以当前方式调用此API的权限取值：5001:api_key无权限或被停用5002:未经授权的IP。（预留设计）5007:这个api_key对当前API的调用量达到上限。仅当api_key为测试key
403	CONCURRENCY_LIMIT_EXCEEDED	否	并发数超过限制
500	INTERNAL_ERROR	否	服务器内部错误，当此类错误发生时请再次请求，如果一直出现此类错误，请及时联系企业客服

# 6 证件类型识别返回对照（extract_result）

# 6.1 墨西哥选民证（MX_ID）

字段名	类型	中文说明	示例
name	string	完整姓名，按 Given Name(s) + Paternal Surname + Maternal Surname 顺序拼接	MARGARITA GOMEZ VELAQUEZ
patName	string	父姓（Paternal Surname）	GOMEZ
matName	string	母姓（Maternal Surname）	VELAQUEZ
givenName	string	名字（Given Name(s)）	MARGARITA
gender	"M"\|"F"	性别	M（男） F（女）
dob	string	出生日期，格式：YYYY-MM-DD	1980-07-05
address	string	地址	C PITAGORAS 1253 INT.4 COL.MORELOS
electorKey	string	选民键（CLAVE DE ELECTOR）	GMVLMR80070501M100
no	string	CURP 号码	GOVM800705MCLMLR01
stateCode	string	州代码（ESTADO）	9
municipality	string	市/区代码（MUNICIPIO）	4
locality	string	地区代码（LOCALIDAD）	1
section	string	选区编号（SECCIÓN）	747
registrationYear	string	注册年份（AÑO DE REGISTRO）	2008-02-01
validThru	string	有效期	2014-2024
cic	string	选民证凭证识别码，常见于新版 INE 证件，一般为 9 位数字，仅背面时返回	074711637
ocr	string	选民证 OCR 编号，仅背面时返回	0747116375842
isCard	string	是否为卡证 "true"/"false"	true
type	string	选民证版本类型，可选值有A-D/E/F/G/H/I/J/back/other,其中A-D为已失效版本。当传入选民证正面时返回版本信息，传入选民证背面时返回back，传入其他卡证类型/非卡证图片时返回other	G

# 6.2 印尼身份证（ID_ID）

字段名	类型	中文说明	示例
name	string	姓名	HERMAWAN
no	string	身份证号码	3216082311830005
pob	string	出生地	JAKARTA
dob	string	出生日期，格式：YYYY-MM-DD	1983-11-23
gender	string	性别	M
blood	string	血型	null
address	string	地址	JL POLONG 12 CS
rt_rw	string	社区编码	008/007
kel_desa	string	村/街道	RATU JAYA
kecamatan	string	区	CIPAYUNG
city_regency	string	市/县	KOTA DEPOK
province	string	省	JAWA BARAT
religion	string	宗教	ISLAM
marital	string	婚姻状态	KAWIN
occup	string	职业	KARYAWAN SWASTA
nationality	string	国籍	WNI
validThru	string	有效期至	SEUMUR HIDUP
isCard	string	是否为卡证 "true"/"false"	true

# 6.3 菲律宾身份证（PH_ID）

字段名	类型	中文说明	示例
givenName	string	名字	MARIBEL
middleName	string	中间名	BARONIA
surname	string	姓氏	TUBO
gender	string	性别	null
dob	string	出生日期，格式：YYYY-MM-DD	1979-11-25
pob	string	出生地
blood	string	血型
marital	string	婚姻状况
no	string	证件号	6041730912782534
address	string	地址	# 160, MUNLAWIN NORTE, ALITAGTAG, BATANGAS, PHILIPPINES, 4205
issDate	string	签发日期
isCard	string	是否为卡证 "true"/"false"	true

# 7. 响应示例

# 7.1 墨西哥证件正确请求返回示例

text

1234567891011121314151617181920212223242526272829303132333435363738

{
"request_id": "b4f2c8e1-9a3d-4f6b-8c2e-1d5a7b9c0e3f",
"time_used": 863,
"biz_no": "202608070001",
"extract_result": {
  "name": "MARGARITA GOMEZ VELAQUEZ",
  "patName": "GOMEZ",
  "matName": "VELAQUEZ",
  "givenName": "MARGARITA",
  "gender": "M",
  "dob": "1980-07-05",
  "address": "C PITAGORAS 1253 INT.4 COL.MORELOS",
  "electorKey": "GMVLMR80070501M100",
  "no": "GOVM800705MCLMLR01",
  "stateCode": "9",
  "municipality": "4",
  "locality": "1",
  "section": "747",
  "registrationYear": "2008-02-01",
  "validThru": "2014-2024",
  "cic": "074711637",
  "ocr": "0747116375842",
  "isCard": "true",
  "type": "G"
},
"quad_detection": "0",
"quad_detection_image": "/9j/4AAQSkZJRgABAQA...（Base64，quad_detection=1 时返回）",
"quality": "0",
"screen": "0",
"ps": "0",
"aigc": "0",
"watermark": "0"
 "photocopy": "0"
 "sticker": "0"
"ocr_warninfos": {
"name": ["<blurred>","<glared>"]
},
}

# 7.2 印尼证件正确请求返回示例

text

123456789101112131415161718192021222324252627282930313233

{
"request_id": "c7e5d2a1-8b4f-4a3c-9e6d-2f8b1c4d5e6f",
"time_used": 572,
"biz_no": "202608070002",
"extract_result": {
 "name": "HERMAWAN",
 "no": "3216082311830005",
 "pob": "JAKARTA",
 "dob": "1983-11-23",
 "gender": "M",
 "blood": null,
 "address": "JL POLONG 12 CS",
 "rt_rw": "008/007",
 "kel_desa": "RATU JAYA",
 "kecamatan": "CIPAYUNG",
 "city_regency": "KOTA DEPOK",
 "province": "JAWA BARAT",
 "religion": "ISLAM",
 "marital": "KAWIN",
 "occup": "KARYAWAN SWASTA",
 "nationality": "WNI",
 "validThru": "SEUMUR HIDUP",
 "isCard": "true"
},
"quad_detection": "0",
"quality": "0",
"photocopy": "0"
"sticker": "0"
"screen": "0"
"ocr_warninfos": {
"name": ["<blurred>","<glared>"]
},
}

# 7.3 菲律宾证件正确请求返回示例

text

12345678910111213141516171819202122232425262728

{
"request_id": "d9f6e3b2-9c5a-4b7d-8f1e-3a9c2d5e6f7a",
"time_used": 641,
"biz_no": "202608070003",
"extract_result": {
  "givenName": "MARIBEL",
  "middleName": "BARONIA",
  "surname": "TUBO",
  "gender": null,
  "dob": "1979-11-25",
  "pob": "",
  "blood": "",
  "marital": "",
  "no": "6041730912782534",
  "address": "# 160, MUNLAWIN NORTE, ALITAGTAG, BATANGAS, PHILIPPINES, 4205",
  "issDate": "",
  "isCard": "true"
},
"quad_detection": "1",
"quad_detection_image": "/9j/4AAQSkZJRgABAQA...（Base64 编码）",
"quality": "0",
"photocopy": "0"
"sticker": "0"
"screen": "0"
"ocr_warninfos": {
"name": ["<blurred>","<glared>"]
},
}

# 7.4 错误响应返回示例

text

{
"request_id": "e1f7a4c3-0d6b-4c8e-9a2f-4b1d3e6f7a8b",
"time_used": 120,
"error": "ID_CARD_NOT_FOUND"
}