# 1 功能描述

该产品主要解决人证不一致、他人代操作、虚假实名等风控问题，适用于实名认证、在线开户、权限开通、高风险业务办理等场景，实现“人、证、本人”三位一体的真实身份核验。
支持越南 CCCD 芯片人像照片（来自芯片或卡面）与现场自拍人像的官方一致性校验。

# 2 使用说明

# 2.1 调用URL

越南地址：https://api-vn.yljz.com/finauth/v5/vn/personmatch

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

# 2.2 调用方法

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

# 3 请求参数

参数	参数名	是否必填	类型	说明
sign	签名	是	String	签名生成规则参考鉴权说明
sign_version	签名算法版本号	是	String	固定传值：hmac_sha1 或 hmac_sha256
biz_no	业务流水号	否	String	自定义本次业务唯一流水号，原样返回
client_session	SDK 采集会话标识	是	String	格式:<IOS/ANDROID><模型名称><操作系统/应用程序接口><设备/模拟器><SDK版本><设备ID><时间戳>
collect_type	采集类型	是	String	sdk：代表使用我方 SDK 采集 other：代表其他采集方式采集
sdk_data	SDK 采集信息	条件必选	File	collect_type 为 sdk 时必填
img_face1	芯片/证件人像图片	条件必选	File	collect_type 为 other 时必填客户方自行拍摄或采集的照片图片限制： 1. 图片大小 ≤ 5MB 2. 格式：JPG/JPEG/PNG
img_face2	自拍人像图片	是	File	客户方自行拍摄的照片图片限制： 1. 图片大小 ≤ 5MB 2. 格式：JPG/JPEG/PNG
three_level	人脸匹配阈值	是	String	枚举值：easy ≥85% / normal ≥90% / strict ≥97%

# 4 返回参数

字段	字段名	类型	参数说明
code	返回码	String	比对成功返回“0000”，详见返回码描述对照表
error	错误码	String	HTTP 状态非 200 时返回
request_id	请求号	String	用于区分每一次请求的唯一的字符串。除非发生404（API_NOT_FOUND）或 403（AUTHORIZATION_ERROR）错误，剩余情况此字段必定返回。
time_used	请求耗时	Int	整个请求所花费的时间，单位为毫秒。此字段必定返回。
biz_no	业务流水号	String	传入的业务流水号，原封不动地返回。
match	是否匹配	Boolean	MATCH → true / NOMATCH → false，便于客户快速判断
data	业务结果	Object	原样透传渠道解密后的 data 对象
prob	匹配比例	Float	人脸图像与证件照片的面部特征匹配比例
multiple_faces	多张人脸标识	Boolean	true 表示检测到人脸图像中含有多张人脸
match_warning	匹配告警	String	yes / no；9 位身份证 82%≤prob<85%，或其他证件 93%≤prob<97% 时为 yes
personalInformation	SDK 采集信息	JSON	collect_type 为 sdk 时返回，SDK 采集后解密得到的证件字段
idCard	公民身份证号码	String	公民身份证号码
name	姓名	String	持卡人姓名
birthday	出生日期	String	持卡人出生日期
gender	性别	String	持卡人性别
nationality	国籍	String	持卡人国籍
ethnic	民族	String	持卡人民族
religion	宗教信仰	String	持卡人宗教信仰
originLocation	出生地/籍贯	String	持卡人出生地 / 籍贯
recentLocation	居住地	String	持卡人居住地
features	体貌识别特征	String	持卡人体貌识别特征
issueDate	签发日期	String	证件签发日期
validDate	证件有效期	String	证件有效期
dadName	父亲姓名	String	持卡人父亲姓名
momName	母亲姓名	String	持卡人母亲姓名
spouseName	配偶姓名	String	持卡人配偶姓名
oldId	旧身份证号码	String	9 位旧版身份证号码
issuePlace	签发地	String	证件签发地

# 5 ERROR 错误信息对照表

HTTP状态代码	返回码描述	是否计费	说明
200	0000	是	比对一致
200	0001	是	人证比对不一致
400	MISSING_ARGUMENTS:<key>	否	缺少某个必选参数
400	BAD_ARGUMENTS:<key>	否	某个参数解析出错（比如必须是数字，但是输入的是非数字字符串；或者长度过长）
400	IMAGE_ERROR_UNSUPPORTED_FORMAT	否	对应的图像无法解析，有可能不是图像文件、或有数据破损。
400	INVALID_IMAGE_SIZE	否	客户上传的图像太大，具体是指像素尺寸的长或宽超过接口限制像素。
401	AUTHENTICATION_ERROR	否	无效签名
403	AUTHORIZATION_ERROR:<reason>	否	api_key被停用、调用次数超限、没有调用此API的权限，或者没有以当前方式调用此API的权限
403	CONCURRENCY_LIMIT_EXCEEDED	否	并发数超过限制
500	INTERNAL_ERROR	否	服务器内部错误，当此类错误发生时请再次请求，如果持续出现此类错误，请及时联系FaceID客服或商务

# 6 响应示例

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

text

12345678910111213141516171819202122232425262728293031

{
  "code": "0000",
  "request_id": "e3f6b9c2-4d8a-4e1f-9c7b-2a4d6f8c3e5a",
  "time_used": 1850,
  "biz_no": "202609010002",
  "match": true,
  "data": {
    "prob": 99.0,
    "multipleFaces": false,
    "matchWarning": "no"
  },
  "personalInformation": {
    "idCard": "079086001234",
    "name": "NGUYEN VAN A",
    "birthday": "1995-03-12",
    "gender": "男",
    "nationality": "越南",
    "ethnic": "京族",
    "religion": "无",
    "originLocation": "河内市",
    "recentLocation": "胡志明市",
    "features": "无特殊体貌特征",
    "issueDate": "2021-06-15",
    "validDate": "2031-06-15",
    "dadName": "NGUYEN VAN B",
    "momName": "TRAN THI C",
    "spouseName": "LE THI D",
    "oldId": "012345678",
    "issuePlace": "河内市公安局"
  }
}

# 6.2 错误响应示例（未检测到人脸）

text

{
  "code": "400",
  "request_id": "a5b8d2e4-6f1c-4a3e-9e7d-4c6f8b1e5a7c",
  "time_used": 180,
  "biz_no": "202609010002",
  "error": "NO_FACE_FOUND"
}