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.

Xem Markdown

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

MethodEndpointMô tả
POST/api/tcdn/{service-code}/v2/api/get-transactionLấ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ểuBắt buộcMô tả
transactionIdStringCóMã giao dịch nhận khi khởi tạo thành công
faceImageBase64Có*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
statusCode1 thành công, 0 thất bại, 2 CCCD sai định dạng
resultKết quả tổng: 1 xác thực, 0 không xác thực
liveness.result / scoreChống giả mạo: 1/0 + trọng số
faceMatch.result / scoreSo 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.isHighRisktrue nếu thiết bị không an toàn
deviceRisk.flagsMã 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ỗ

POSThttps://ekyc-c06.hitechcloud.vn/api/tcdn/biometric-share-info/v2/api/get-transaction

biometricResult và userInfo là JWS — xác minh bằng public key C06. Token không được lưu lại.

Headers
Body