接入文档
OCR识别（海外版）
海外卡证识别
海外卡证识别
# 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_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 |
| error | 错误信息 | String | 发生错误后，会返回对应的错误码 |
# 5 ERROR错误信息对照表
| HTTP 状态代码 | 返回码 | 是否计费 | 说明 |
|---|---|---|---|
| 200 | SUCCESS | 是 | 调用成功 |
| 400 | INVALID_IMAGE_SIZE: image | 否 | 客户发送的请求单张照片大小超过了5MB限制。该错误的返回格式为纯文本，不是json格式 |
| 400 | MISSING_ARGUMENTS: |
否 | 缺少某个必要参数 |
| 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
{
"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"
}
# 7.2 印尼证件正确请求返回示例
text
{
"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"
}
# 7.3 菲律宾证件正确请求返回示例
text
{
"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"
}
# 7.4 错误响应返回示例
text
{
"request_id": "e1f7a4c3-0d6b-4c8e-9a2f-4b1d3e6f7a8b",
"time_used": 120,
"error": "ID_CARD_NOT_FOUND"
}