# 1 功能描述

该产品主要解决身份冒用、虚假实名、伪造芯片身份证等风控问题，适用于实名认证、在线开户、权限开通、高风险业务办理等场景，实现越南芯片公民身份证（CCCD）芯片信息的真实性核验。
客户传入 CCCD 身份证号码及芯片原始分区数据，我方对接越南渠道完成芯片信息解码并与国安库（C06）核验，返回证件有效性及卡面信息。

# 2 使用说明

# 2.1 调用URL

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

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

# 2.2 调用方法

请求方式：POST
请求格式：json
说明：客户端通过 apikey 和 secret 生成加密签名 sign，同时传入 CCCD 身份证号码及芯片原始分区数据，接口返回证件有效性及卡面信息。

# 3 请求参数

参数	参数名	是否必填	类型	说明
sign	签名	是	String	签名生成规则参考鉴权说明
sign_version	签名算法版本号	是	String	固定传值：hmac_sha1 或 hmac_sha256
biz_no	业务流水号	否	String	自定义本次业务唯一流水号，原样返回
cccd	身份证号码	是	String	越南 CCCD 公民身份证号码
device_type	设备类型	是	String	发起请求的设备类型。App 填 iOS / Android；网站填 Mobile / Desktop；应用程序填 Windows / Mac / Linux；CCCD 读卡器填 Đầu đọc thẻ CCCD；摄像头填 Camera
device_name	设备名称	是	String	发起请求的设备名称
device_version	设备版本	是	String	发起请求的设备版本号
latitude	纬度	否	String	GPS 终端设备纬度
longitude	经度	否	String	GPS 终端设备经度
collect_type	采集类型	是	String	sdk：代表使用我方 SDK 采集 other：代表其他采集方式采集
sdk_data	SDK 采集信息	条件必选	File	collect_type 为 sdk 时必填
raw	卡片原始分区数据	条件必选	Object	collect_type 为 other 时必填从 CCCD 读卡器读取的原始分区数据
com	COM 分区	是	String	Base64 编码
sod	SOD 分区	是	String	Base64 编码（安全认证）
dg1	DG1 分区	是	String	Base64 编码（MRZ 文本）
dg2	DG2 分区	是	String	Base64 编码（芯片人像照片）
dg3	DG3分区	否	String	Base64 编码
dg4	DG4分区	否	String	Base64 编码
dg5	DG5分区	否	String	Base64 编码
dg6	DG6分区	否	String	Base64 编码
dg7	DG7分区	否	String	Base64 编码
dg8	DG8分区	否	String	Base64 编码
dg9	DG9分区	否	String	Base64 编码
dg10	DG10分区	否	String	Base64 编码
dg11	DG11分区	否	String	Base64 编码
dg12	DG12分区	否	String	Base64 编码
dg13	DG13 分区	是	String	Base64 编码
dg14	DG14 分区	是	String	Base64 编码
dg15	DG15 分区	是	String	Base64 编码
dg16	DG16 分区	否	String	Base64 编码

# 4 返回参数

字段	字段名	类型	参数说明
code	返回码	String	比对成功返回“0000”，详见返回码描述对照表
error	错误码	String	HTTP 状态非 200 时返回
request_id	请求号	String	用于区分每一次请求的唯一的字符串。除非发生404（API_NOT_FOUND）或 403（AUTHORIZATION_ERROR）错误，剩余情况此字段必定返回。
time_used	请求耗时	Int	整个请求所花费的时间，单位为毫秒。此字段必定返回。
biz_no	业务流水号	String	传入的业务流水号，原封不动地返回。
data	业务结果	Object	原样透传渠道解密后的 data 对象
expired_time_response	结果失效时间	String	验证结果的失效时间
card_data	卡信息数据	Object	已解码的 CCCD 卡信息
card_number	CCCD 号码	String	公民身份证号码
name	姓名	String	持卡人姓名
sex	性别	String	持卡人性别，如 Male / Female
date_of_birth	出生日期	String	格式 dd/MM/yyyy
issue_date	签发日期	String	格式 dd/MM/yyyy
expired_date	有效期	String	CCCD 有效期
nationality	国籍	String	持卡人国籍，如 Vietnam
nation	民族	String	持卡人民族，如 Kinh
religion	宗教	String	持卡人宗教信仰，如 None
hometown	常住地址	String	持卡人籍贯 / 常住地址
address	居住地址	String	持卡人居住地址
character	识别特征	String	持卡人身份识别特征描述
father_name	父亲姓名	String	持卡人父亲姓名
mother_name	母亲姓名	String	持卡人母亲姓名
partner_name	配偶姓名	String	持卡人配偶姓名
previous_number	旧版身份证号	String	9 位旧版身份证号码
mrz	MRZ 字符串	String	机读区字符串
face_image	芯片人像	String	芯片人像图像，Base64 编码 JPG
responds	C06 核验结果	Object	国安库返回的核验结果
result	核验结果	Boolean	证件是否通过核验，true / false
time	服务端时间戳	Long	服务端返回时间戳，单位毫秒

# 5 ERROR 错误信息对照表

HTTP状态代码	返回码描述	是否计费	说明
200	0000	是	证件有效（核验一致）
200	0001	是	证件无效（核验不一致）
200	0002	是	芯片数据不完整，已有字段仍正常返回
400	400	否	参数错误：缺少必填字段或 Base64 格式错误
400	BAD_ARGUMENTS:<key>	否	某个参数解析出错（比如必须是数字，但是输入的是非数字字符串；或者长度过长）
401	AUTHENTICATION_ERROR	否	无效签名
403	AUTHORIZATION_ERROR:<reason>	否	api_key被停用、调用次数超限、没有调用此API的权限，或者没有以当前方式调用此API的权限
403	CONCURRENCY_LIMIT_EXCEEDED	否	并发数超过限制
405	METHOD_NOT_ALLOWED	否	请求方法不正确
500	INTERNAL_ERROR	否	服务器内部错误，当此类错误发生时请再次请求，如果持续出现此类错误，请及时联系FaceID客服或商务

# 6 响应示例

# 6.1 正确请求返回示例（核验成功）

text

123456789101112131415161718192021222324252627282930313233

{
  "code": "0000",
  "request_id": "e3f6b9c2-4d8a-4e1f-9c7b-2a4d6f8c3e5a",
  "time_used": 1823,
  "biz_no": "202609010001",
  "data": {
    "expiredTimeResponse": "10/01/2041 00:00:00",
    "cardData": {
      "cardNumber": "037096012345",
      "name": "NGUYEN VAN A",
      "sex": "Male",
      "dateOfBirth": "15/03/1990",
      "issueDate": "10/01/2021",
      "expiredDate": "10/01/2041",
      "nationality": "Vietnam",
      "nation": "Kinh",
      "religion": "None",
      "hometown": "Xom 2, Xa Van Thinh, Huyen Me Linh, Tinh Vinh Phuc",
      "address": "123 Le Loi, Phuong Tran Hung Dao, Quan Hoan Kiem, Ha Noi",
      "character": "",
      "fatherName": "NGUYEN VAN B",
      "motherName": "TRAN THI C",
      "partnerName": "",
      "previousNumber": "037096123",
      "mrz": "I<VNM0370960123456<8FGHJKL...",
      "faceImage": "/9j/4AAQSkZJRgABAQEAYABgAAD..."
    },
    "responds": {
      "result": true,
      "time": 1717147769384
    }
  }
}

# 6.2 错误响应示例（参数解析出错）

text

{
  "code": "400",
  "request_id": "a5b8d2e4-6f1c-4a3e-9e7d-4c6f8b1e5a7c",
  "time_used": 120,
  "biz_no": "202609010001",
  "error": "BAD_ARGUMENTS:cccd"
}