# 1 功能描述

该产品主要解决身份冒用、他人代操作、虚假实名等风控问题，适用于实名认证、在线开户、权限开通、高风险业务办理等场景，实现“人、证、本人”三位一体的真实身份核验。
支持墨西哥选民卡“G”“H”类。

# 2 使用说明

# 2.1 调用URL

新加坡地址：https://api-sgp.yljz.com/finauth/v5/ine/personmatch
墨西哥地址：https://api-mx.yljz.com/finauth/v5/ine/personmatch

注意：生产环境必须使用 HTTPS 通信方式；HTTP 属于不安全链路，存在安全风险，禁止在生产环境使用，且不提供服务可靠性保障。

# 2.2 调用方法

请求方式：POST
请求格式：form-data
说明：客户端通过 apikey 和 secret 生成加密签名 sign，同时传入证件反面图片、人像图片及业务流水号，接口返回人证比对核验结果及置信分数。

# 3 请求参数

参数	参数名	是否必填	类型	说明
sign	签名	是	String	签名生成规则参考鉴权说明
sign_version	签名算法版本号	是	String	固定传值：hmac_sha1 或 hmac_sha256
image_reverse	ine反面图片	是	File	与人像图片一致，客户方自行拍摄的照片图片限制： 1. 图片大小 ≤ 5MB 2. 分辨率≤ 5000×5000 px 3. 格式：JPG/JPEG/PNG
image_ref	人像图片	是	File
ocr	ocr	是	String	证件上的ocr号码
cic	cic	是	String	证件上的cic号码
curp	curp	否	String	证件上的curp号码
biz_no	业务流水号	否	String	自定义本次业务唯一流水号

# 4 返回参数

字段	字段名	类型	参数说明
code	返回码	String	比对成功返回“0000”，详见返回码描述对照表
request_id	请求号	String	用于区分每一次请求的唯一的字符串。除非发生404（API_NOT_FOUND）或 403 （AUTHORIZATION_ERROR）错误，剩余情况此字段必定返回。
time_used	请求耗时	Int	整个请求所花费的时间，单位为毫秒。此字段必定返回。
biz_no	业务流水号	String	传入的业务流水号，原封不动地返回。
verification	验证结果	JSON	验证结果详情
confidence	比对分数	Float	示例值：88.038055判定规则：高于74.39926为可信分值，分数越高人脸比对可信度越高
pat_name	父姓	String	父姓（Paternal Surname）
mat_name	母姓	String	母姓（Maternal Surname）
given_name	名字	String	名字（Given Name(s)）
gender	性别	String	M（男，选民卡上对应：Hombre） F（女，选民卡上对应：Mujer）
curp	CURP	String	curp号码
section	选区编号	String	选区编号（SECCIÓN）
fecha	注册年份	String	签发日期fecha,年月日
vigencia	有效期	String	有效期 2024-2034
gov_image	官方人像	String	官方人像图像，base64 格式，仅支持 jpg 格式
cic	选民证号	String	选民证号
ocr	OCR 码	String	OCR 识别编码
entidad_codigo	州代码	String	州代码示例：15
municipio_codigo	市镇代码	String	市镇代码示例：121
entidad	州名称	String	州名示例：墨西哥州
municipio	市镇名称	String	市镇名示例：松潘戈
tipo	证件类型	String	证件类型示例：G

# 5 ERROR 错误信息对照表

HTTP状态代码	返回码描述	是否计费	说明
200	0000	是	比对一致
200	0002	是	人证比对不一致
400	ERROR:CIC_OCR_CURP	否	cic或ocr或curp号码错误
400	ID_CARD_NOT_FOUND	否	未检测到卡证
400	LOW_QUALITY	否	卡证质量异常
400	ID_CARD_UNRECOGNIZABLE	否	卡证无法识别
400	NO_FACE_FOUND	否	未检测到人脸
400	MULTIPLE_FACES	否	检测到多张人脸
400	MISSING_ARGUMENTS:<key>	否	缺少某个必选参数
400	BAD_ARGUMENTS:<key>	否	某个参数解析出错（比如必须是数字，但是输入的是非数字字符串; 或者长度过长）
400	IMAGE_ERROR_UNSUPPORTED_FORMAT:<param>	否	对应的图像无法解析，有可能不是图像文件、或有数据破损。
400	INVALID_IMAGE_SIZE:<param>	否	客户上传的图像太大，具体是指像素尺寸的长或宽超过接口限制像素。
403	AUTHENTICATION_ERROR	否	无效签名
403	AUTHORIZATION_ERROR:<reason>	否	api_key被停用、调用次数超限、没有调用此API的权限，或者没有以当前方式调用此API的权限
403	CONCURRENCY_LIMIT_EXCEEDED	否	并发数超过限制
404	API_NOT_FOUND	否	所调用的API不存在
413	Request Entity Too Large	否	客户发送的请求大小超过了限制。该错误的返回格式为纯文本，不是json格式
500	INTERNAL_ERROR	否	服务器内部错误，当此类错误发生时请再次请求，如果持续出现此类错误，请及时联系FaceID客服或商务

# 6 响应示例

# 6.1 正确请求返回示例（人证比对一致）

text

12345678910111213141516171819202122232425

{
  "code": "0000",
  "request_id": "e3f6b9c2-4d8a-4e1f-9c7b-2a4d6f8c3e5a",
  "time_used": 1823,
  "biz_no": "202608070008",
  "verification": {
    "confidence": 88.038055,
    "pat_name": "GOMEZ",
    "mat_name": "VELAQUEZ",
    "given_name": "MARGARITA",
    "gender": "M",
    "curp": "GOVM800705MCLMLR01",
    "section": "747",
    "fecha": "2008-02-01",
    "vigencia": "2024-2034",
    "gov_image": "/9j/4AAQSkZJRgABAQA...（Base64，jpg 格式官方人像）",
    "cic": "074711637",
    "ocr": "0747116375842",
    "entidad_codigo": "15",
    "municipio_codigo": "121",
    "entidad": "墨西哥州",
    "municipio": "松潘戈",
    "tipo": "G"
  }
}

# 6.2 错误响应示例

text

{
  "code": "400",
  "request_id": "a5b8d2e4-6f1c-4a3e-9e7d-4c6f8b1e5a7c",
  "time_used": 320,
  "error": "ERROR:CIC_OCR_CURP"
}