API Sinh trắc học & Ảnh mặt (v2)
Lấy dữ liệu công dân kèm kết quả xác thực sinh trắc học (liveness + faceMatch) — áp dụng cho dịch vụ có xác thực ảnh mặt.
Dùng cho các dịch vụ có xác thực ảnh mặt (biometric-share-info, face-matching). TCDN gửi faceImage (base64 do SDK trả ra) cùng transactionId, nhận về biometricResult và userInfo dạng JWS.
Endpoint
| Method | Endpoint | Mô tả |
|---|---|---|
POST | /api/tcdn/{service-code}/v2/api/get-transaction | Lấy dữ liệu + kết quả sinh trắc học |
Header
request_type: sdk-liveness-match (chống giả mạo + so khớp ảnh mặt) hoặc sdk-match (chỉ so khớp ảnh mặt). Object liveness chỉ trả về khi dùng sdk-liveness-match.Tham số thân yêu cầu (Body)
| Tham số | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
transactionId | String | Có | Mã giao dịch nhận khi khởi tạo thành công |
faceImage | Base64 | Có* | Dữ liệu khuôn mặt do SDK trả ra (bắt buộc với biometric-share-info, face-matching) |
cURL xác thực ảnh mặt
curl -X POST "https://ekyc-c06.hitechcloud.vn/api/tcdn/biometric-share-info/v2/api/get-transaction" \
-H "Content-Type: application/json; charset=utf-8" \
-H "api_key: YOUR_API_KEY" \
-H "target_code: YOUR_TARGET_CODE" \
-H "request_id: 9baf1668-a0da-4f9a-b9ac-5eef6f5da5f6" \
-H "request_time: 31102026094000" \
-H "request_type: sdk-liveness-match" \
-d '{
"transactionId": "9baf1668-a0da-4f9a-b9ac-5eef6f5da5f6",
"faceImage": "<chuoi-base64-do-SDK-tra-ra>"
}'Phản hồi (HTTP 200)
{
"responseCode": 0,
"description": "Mô tả lỗi nếu có",
"data": {
"biometric": 1,
"biometricResult": "ewogICJ0eXAiOiAiand0Ii4uLg==.<payload>.<signature>"
},
"userInfo": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpPU0UvSldTIn0=.<payload>.<signature>"
}biometricResult sau khi parse JWS (payload)
{
"transId": "22fc12e0-be90-4519-8ef6-cdeca95ae22b",
"statusCode": 1,
"data": {
"result": 1,
"liveness": { "result": 1, "score": 0.98 },
"faceMatch": { "result": 1, "score": 0.98, "confidence": 3 },
"deviceRisk": { "isHighRisk": false, "flags": [] }
}
}Giải nghĩa kết quả sinh trắc học
| Trường | Ý nghĩa |
|---|---|
statusCode | 1 thành công, 0 thất bại, 2 CCCD sai định dạng |
result | Kết quả tổng: 1 xác thực, 0 không xác thực |
liveness.result / score | Chống giả mạo: 1/0 + trọng số |
faceMatch.result / score | So khớp ảnh mặt: 1/0 + trọng số |
faceMatch.confidence | Độ tin cậy: 1 Thấp, 2 Trung bình, 3 Cao |
deviceRisk.isHighRisk | true nếu thiết bị không an toàn |
deviceRisk.flags | Mã nguyên nhân: 1 REPACK, 2 EMULATOR, 3 HOOK, 4 DEBUG, 5 ROOT, 6 UNLOCK_BOOTLOADER, 8 VIRTUAL_ENVIRONMENT, 10 ADB, 11 DEVELOPMENT_SETTING |
Kiểm thử tại chỗ
POST
https://ekyc-c06.hitechcloud.vn/api/tcdn/biometric-share-info/v2/api/get-transactionKiểm thử tại chỗbiometricResult và userInfo là JWS — xác minh bằng public key C06. Token không được lưu lại.
Headers
Body
Dùng cho các dịch vụ có xác thực ảnh mặt (biometric-share-info, face-matching). TCDN gửi faceImage (base64 do SDK trả ra) cùng transactionId, nhận về biometricResult và userInfo dạng JWS.
Endpoint
| Method | Endpoint | Mô tả |
|---|---|---|
POST | /api/tcdn/{service-code}/v2/api/get-transaction | Lấy dữ liệu + kết quả sinh trắc học |
Header
request_type: sdk-liveness-match (chống giả mạo + so khớp ảnh mặt) hoặc sdk-match (chỉ so khớp ảnh mặt). Object liveness chỉ trả về khi dùng sdk-liveness-match.Tham số thân yêu cầu (Body)
| Tham số | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
transactionId | String | Có | Mã giao dịch nhận khi khởi tạo thành công |
faceImage | Base64 | Có* | Dữ liệu khuôn mặt do SDK trả ra (bắt buộc với biometric-share-info, face-matching) |
Giải nghĩa kết quả sinh trắc học
| Trường | Ý nghĩa |
|---|---|
statusCode | 1 thành công, 0 thất bại, 2 CCCD sai định dạng |
result | Kết quả tổng: 1 xác thực, 0 không xác thực |
liveness.result / score | Chống giả mạo: 1/0 + trọng số |
faceMatch.result / score | So khớp ảnh mặt: 1/0 + trọng số |
faceMatch.confidence | Độ tin cậy: 1 Thấp, 2 Trung bình, 3 Cao |
deviceRisk.isHighRisk | true nếu thiết bị không an toàn |
deviceRisk.flags | Mã nguyên nhân: 1 REPACK, 2 EMULATOR, 3 HOOK, 4 DEBUG, 5 ROOT, 6 UNLOCK_BOOTLOADER, 8 VIRTUAL_ENVIRONMENT, 10 ADB, 11 DEVELOPMENT_SETTING |
Kiểm thử tại chỗ
POST
https://ekyc-c06.hitechcloud.vn/api/tcdn/biometric-share-info/v2/api/get-transactionKiểm thử tại chỗbiometricResult và userInfo là JWS — xác minh bằng public key C06. Token không được lưu lại.
Headers
Body
cURL xác thực ảnh mặt
curl -X POST "https://ekyc-c06.hitechcloud.vn/api/tcdn/biometric-share-info/v2/api/get-transaction" \
-H "Content-Type: application/json; charset=utf-8" \
-H "api_key: YOUR_API_KEY" \
-H "target_code: YOUR_TARGET_CODE" \
-H "request_id: 9baf1668-a0da-4f9a-b9ac-5eef6f5da5f6" \
-H "request_time: 31102026094000" \
-H "request_type: sdk-liveness-match" \
-d '{
"transactionId": "9baf1668-a0da-4f9a-b9ac-5eef6f5da5f6",
"faceImage": "<chuoi-base64-do-SDK-tra-ra>"
}'Phản hồi (HTTP 200)
{
"responseCode": 0,
"description": "Mô tả lỗi nếu có",
"data": {
"biometric": 1,
"biometricResult": "ewogICJ0eXAiOiAiand0Ii4uLg==.<payload>.<signature>"
},
"userInfo": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpPU0UvSldTIn0=.<payload>.<signature>"
}biometricResult sau khi parse JWS (payload)
{
"transId": "22fc12e0-be90-4519-8ef6-cdeca95ae22b",
"statusCode": 1,
"data": {
"result": 1,
"liveness": { "result": 1, "score": 0.98 },
"faceMatch": { "result": 1, "score": 0.98, "confidence": 3 },
"deviceRisk": { "isHighRisk": false, "flags": [] }
}
}