# 1 功能描述

该产品主要解决证件伪造、证件拼接、信息篡改、正反证件不匹配等风险问题，适用于客户高合规、高风控要求的证件备案、资料审核、入网核验场景，为客户提供证件本身的真实性、完整性校验能力。
支持证件类型 - “E”“F”“G”“H”类。

# 2 使用说明

# 2.1 调用URL

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

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

# 2.2 调用方法

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

# 3 请求参数

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

# 4 返回参数

字段	字段名	类型	参数说明
code	返回码	String	比对成功返回“0000”，详见返回码描述对照表
request_id	请求号	String	用于区分每一次请求的唯一的字符串。除非发生404（API_NOT_FOUND）或 403 （AUTHORIZATION_ERROR）错误，剩余情况此字段必定返回。
time_used	请求耗时	Int	整个请求所花费的时间，单位为毫秒。此字段必定返回。
biz_no	业务流水号	String	传入的业务流水号，原封不动地返回。
positive_appraisal	正面鉴伪	json	对证件正面进行防伪检测
screen	翻拍结果	String	无权限时返回null 0: 无翻拍 1: 证件存在翻拍
ps	PS检测结果	String	无权限时返回null 0: 无ps 1: 证件存在ps
aigc	AIGC检测结果	String	无权限时返回null 0: 非AIGC证件 1: AIGC证件
watermark	水印检测结果	String	无权限时返回null 0: 无水印 1: 图片存在水印
photocopy	复印检测结果	String	0: 无复印 1: 图片存在复印服务不可用时返回null
sticker	贴图检测结果	String	0: 无贴图 1: 图片存在贴图服务不可用时返回null
quad_detection	四点检测结果	String	0: 四点检测通过 1: 四点检测不通过服务不可用时返回null
quality	质量检测结果	String	0: 无质量问题 1: 有质量问题服务不可用时返回null
reverse_appraisal	反面鉴伪	json	对证件反面进行防伪检测
screen	翻拍结果	String	无权限时返回null 0: 无翻拍 1: 证件存在翻拍
ps	PS检测结果	String	无权限时返回null 0: 无ps 1: 证件存在ps
aigc	AIGC检测结果	String	无权限时返回null 0: 非AIGC证件 1: AIGC证件
watermark	水印检测结果	String	无权限时返回null 0: 无水印 1: 图片存在水印
photocopy	复印检测结果	String	0: 无复印 1: 图片存在复印服务不可用时返回null
sticker	贴图检测结果	String	0: 无贴图 1: 图片存在贴图服务不可用时返回null
quad_detection	四点检测结果	String	0: 四点检测通过 1: 四点检测不通过服务不可用时返回null
quality	质量检测结果	String	0: 无质量问题 1: 有质量问题服务不可用时返回null

# 5 ERROR 错误信息对照表

HTTP 状态代码	返回码	是否计费	说明
200	0000	是	验证通过
200	0001	是	文本疑似信息伪造
400	ID_CARD_NOT_FOUND	否	未检测到卡证
400	LOW_QUALITY	否	卡证质量异常
400	ID_CARD_UNRECOGNIZABLE	否	卡证无法识别
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

123456789101112131415161718

{
  "code": "0000",
  "request_id": "b9c3f6d8-1a5e-4b7d-9f4c-6e8a3c7f9b1d",
  "time_used": 1567,
  "biz_no": "202608070006",
  "positive_appraisal": {
    "screen": "0",
    "ps": "0",
    "aigc": "0",
    "watermark": "0"
  },
  "reverse_appraisal": {
    "screen": "0",
    "ps": "0",
    "aigc": "0",
    "watermark": "0"
  }
}

# 6.2 正确请求返回示例（文本疑似信息伪造）

text

123456789101112131415161718

{
  "code": "0001",
  "request_id": "c1d4f7e9-2b6f-4c8e-8a5d-7f9b4d8a1c2e",
  "time_used": 1498,
  "biz_no": "202608070007",
  "positive_appraisal": {
    "screen": "0",
    "ps": "1",
    "aigc": "0",
    "watermark": "0"
  },
  "reverse_appraisal": {
    "screen": "0",
    "ps": "0",
    "aigc": "0",
    "watermark": "0"
  }
}

# 6.3 错误响应示例

text

{
  "code": "400",
  "request_id": "d2e5a8f1-3c7a-4d9f-9b6e-8a1c5e9b2d3f",
  "time_used": 210,
  "error": "ID_CARD_NOT_FOUND"
}