Các API của luồng Xác thực khuôn mặt

Xác thực khuôn mặt (Face Authentication), sau đây gọi là Face Authen, là luồng xác thực lại người dùng hiện tại bằng khuôn mặt, dùng cho các giao dịch hoặc thao tác cần chắc chắn người đang thực hiện là một người thật (thực thể sống) và đúng là chủ của hồ sơ đã được định danh trước đó.

Luồng này khác với luồng eKYC định danh lần đầu: Face Authen không đọc giấy tờ (OCR/NFC), mà so khớp khuôn mặt của người dùng tại thời điểm giao dịch với ảnh hoặc vector khuôn mặt (dữ liệu số hóa đặc trưng khuôn mặt) đã được xác thực và lưu sẵn trong hệ thống của khách hàng.

Mỗi lần xác thực, hệ thống FPT AI eKYC thực hiện 2 bước kiểm tra trên cùng một yêu cầu:

Kiểm tra thực thể sống (liveness): xác định khuôn mặt trong ảnh hoặc video chân dung là của người thật đang đứng trước camera, không phải ảnh in, ảnh hoặc video phát lại trên màn hình, mặt nạ hay khuôn mặt giả mạo bằng công nghệ.
So khớp khuôn mặt (face match): so khớp khuôn mặt vừa chụp với ảnh hoặc vector khuôn mặt đã lưu của người dùng, trả về kết quả khớp hoặc không khớp cùng độ tương đồng (similarity).

Một số tình huống sử dụng điển hình

Giao dịch chuyển tiền, thanh toán có giá trị lớn: yêu cầu người dùng xác thực khuôn mặt trước khi giao dịch được thực hiện.
Xác nhận đúng chủ hồ sơ ở các bước quan trọng sau khi đã định danh, ví dụ sau khi nộp hồ sơ, khi giao nhận hợp đồng hoặc khi hoàn tất các bước thẩm định bổ sung.
Xác thực định kỳ đối với người dùng đã được định danh trước đó (ví dụ cộng tác viên, đại lý) để đảm bảo tài khoản vẫn do đúng người sử dụng.
Các thao tác nhạy cảm khác mà khách hàng muốn bổ sung một lớp xác minh sinh trắc học bên cạnh các biện pháp sẵn có như mật khẩu hoặc SMS OTP.

Điều kiện áp dụng

Người dùng đã có ảnh hoặc vector khuôn mặt đã xác thực, được lưu trong hệ thống của khách hàng (thường thu thập ở lần eKYC đầu tiên, ví dụ ảnh trên chip của giấy tờ).
Thời điểm kích hoạt Face Authen (ví dụ giao dịch vượt một ngưỡng số tiền nhất định) do hệ thống của khách hàng quyết định. Hệ thống FPT AI eKYC chỉ xử lý khi nhận được yêu cầu xác thực.

Ví dụ luồng nghiệp vụ trong một giao dịch

Người dùng nhập giao dịch trên ứng dụng của khách hàng.
Ứng dụng kiểm tra giao dịch có thuộc diện cần Face Authen hay không và người dùng đã có khuôn mặt lưu sẵn hay chưa.
Nếu cần, ứng dụng gọi SDK hoặc API để người dùng chụp ảnh chân dung hoặc quay video; FPT AI eKYC kiểm tra thực thể sống và so khớp khuôn mặt.
Nếu xác thực thành công, ứng dụng chuyển sang bước tiếp theo theo quy trình của khách hàng (ví dụ xác nhận bằng SMS OTP) và hoàn tất giao dịch.
Nếu thất bại, người dùng được thử lại trong cùng phiên cho đến khi hết số lần cho phép; quá số lần này, ứng dụng kết thúc luồng và đưa người dùng quay lại màn hình trước đó.

Các API của luồng này bao gồm:

API khởi tạo phiên
API kiểm tra liveness và so khớp khuôn mặt

Base URL:

Môi trường Staging: https://api.fpt.ai/vision/ekyc/biometrics-be-stag
Môi trường Production: https://api.fpt.ai/vision/ekyc/biometrics-be

Sơ đồ tuần tự gọi các API trong luồng Xác thực khuôn mặt

1. API khởi tạo phiên

1.1. Request Url

POST base_url/biometric/init

1.2. Request Headers

Tham số	Yêu cầu	Giá trị mặc định	Mô tả
api-key	Có		API key để sử dụng hệ thống FPT AI eKYC
client_uuid	Không		UUID sinh ra từ hệ thống của khách hàng để tự quản lý phiên eKYC
device-type	Có		Thiết bị đang sử dụng, các giá trị cho phép bao gồm: `android`, `ios`, `web-sdk`
lang	Không	vi	Ngôn ngữ sử dụng, các giá trị cho phép bao gồm: `en`, `vi`
sdk-version	Không		Phiên bản của FPT AI eKYC SDK. Nên sử dụng tham số này để đảm bảo hiệu quả khi sử dụng SDK

1.3. Mẫu request

curl --location --request POST 'base_url/biometric/init' \
--header 'api-key: your-api-key' \
--header 'device-type: android' \
--header 'client_uuid: your-uuid' \
--header 'lang: vi'

1.4. Response

1.4.1. Mẫu response

Thành công: http_code = 200

{
    "code": "200",
    "message": "success",
    "session-id": "tsan_ekyc__ef1e2944-91b0-4506-8a1a-8f39a80b309c",
    "sdk_config": {
        "is_show_ekyc_result": true,
        "liveness_type": 1,
        "show_guide": 3,
        "disable_liveness": false,
        "show_switch_button": 1,
        "limit": 5,
        "font_path": {
            "regular": "",
            "medium": "",
            "bold": ""
        }
    }
}

Thất bại: http_code != 200

1.4.2. Mô tả response

Tham số	Loại dữ liệu	Mô tả	Ghi chú
code	String	Mã trạng thái trả về của yêu cầu	`200`: Thành công
message	String	Thông báo lỗi trả về (nếu có)	`200`: Thành công; `401`: Lỗi xác thực; `403`: Lỗi dùng sai session-id; `504`: Lỗi kết nối hệ thống; `500`: Lỗi server hệ thống
session-id	String	Mã ID duy nhất của phiên eKYC được sinh ra bởi eKYC Backend. session-id sau đó phải được gửi kèm trong headers của tất cả các request trong cùng phiên
sdk_config	String	Cấu hình hiện tại của luồng eKYC

2. API kiểm tra liveness và so khớp khuôn mặt

2.1. Request Url

POST base_url/biometric/verify

2.2. Request Headers

Tham số	Yêu cầu	Loại dữ liệu	Mô tả	Chú ý
session-id	Có	String	ID duy nhất của phiên eKYC nhận được từ bước khởi tạo phiên
api-key	Có	String	API key để sử dụng hệ thống FPT AI eKYC
auto	Có	String	Đặt giá trị là True khi gửi từ FPT SDK. Nếu không phải đặt False
device-type	Có	String	Thiết bị đang sử dụng, các giá trị cho phép bao gồm: `android`, `ios`, `web-sdk`
lang	Không	String	Ngôn ngữ sử dụng, các giá trị cho phép bao gồm: `en`, `vi`	default: en
sdk-version	Không	String	Phiên bản của FPT AI eKYC SDK. Nên sử dụng tham số này để đảm bảo hiệu quả khi sử dụng SDK

2.3. Request Body

FormData chứa ảnh hoặc video selfie sử dụng để kiểm tra.

Tham số	Yêu cầu	Giá trị mặc định	Mô tả
selfies	Không. Sử dụng selfies hoặc video	Array	Ảnh selfie được thu thập để kiểm tra liveness và thực hiện face matching
video	Không. Sử dụng selfies hoặc video	File	Video selfie được thu thập để kiểm tra liveness và thực hiện face matching
cmnd	Không. Sử dụng cmnd hoặc vector	File	File ảnh khuôn mặt của người dùng đã được xác thực lưu trong hệ thống của khách hàng. Ảnh này sẽ được dùng để thực hiện face matching
vector	Không. Sử dụng cmnd hoặc vector	File	Vector khuôn mặt của người dùng đã được xác thực lưu trong hệ thống của khách hàng. Vector này sẽ được dùng để thực hiện face matching

2.4. Mẫu request

curl --location --request POST 'base_url/biometric/verify' \
--header 'api-key: your-api-key' \
--header 'session-id: 7760a743-884b-4195-b781-892e72c7b0b6' \
--header 'device-type: android' \
--header 'lang: vi' \
--form 'selfies=@"path-to-selfie-image"' \
--form 'vector="..."'

2.5. Response

2.5.1. Mẫu response thành công

{
    "code": "200",
    "message": "Kiểm tra thực thể sống thành công",
    "liveness": {
        "code": "200",
        "message": "liveness check successful",
        "is_live": "true",
        "spoof_prob": "N/A",
        "need_to_review": "N/A",
        "is_deepfake": "N/A",
        "deepfake_prob": "N/A",
        "warning": "N/A"
    },
    "face_match": {
        "code": "200",
        "message": "face matching successful",
        "isMatch": "true",
        "similarity": "95.84",
        "warning": "N/A"
    },
    "is_complete_session": false
}

2.5.2. Mô tả response

Tham số	Loại dữ liệu	Mô tả
code	String	Mã trạng thái trả về của yêu cầu. Mã `200` nghĩa là yêu cầu thành công. Chi tiết các mã khác xem tại trang Mã lỗi
message	String	Thông báo lỗi trả về của yêu cầu (nếu có). Ngôn ngữ của thông báo được quy định bởi tham số `lang` trong header
liveness	Object	Kết quả kiểm tra thực thể sống
face_match	Object	Kết quả so khớp khuôn mặt
is_complete_session	Boolean	Cho biết phiên đã kết thúc hay chưa. Nếu là `false`, người dùng có thể thử xác thực lại trong cùng phiên; nếu là `true`, người dùng phải thực hiện lại bằng một phiên khác

2.5.3. Mẫu response lỗi

{
    "code": "303",
    "message": "Khuôn mặt không khớp với giấy tờ",
    "liveness": {
        "code": "200",
        "message": "liveness check successful",
        "is_live": "true",
        "spoof_prob": "N/A",
        "need_to_review": "N/A",
        "is_deepfake": "N/A",
        "deepfake_prob": "N/A",
        "warning": "N/A"
    },
    "face_match": {
        "code": "303",
        "message": "face is not matching with document",
        "isMatch": "false",
        "similarity": "5.84",
        "warning": "N/A"
    },
    "is_complete_session": false
}

{
    "code": "407",
    "message": "2 faces exist",
    "liveness": {
        "code": "200",
        "message": "liveness check successful",
        "is_live": "true",
        "spoof_prob": "N/A",
        "need_to_review": "N/A",
        "is_deepfake": "N/A",
        "deepfake_prob": "N/A",
        "warning": "N/A"
    },
    "face_match": {
        "code": "407",
        "message": "2 faces exist",
        "isMatch": "N/A",
        "similarity": "N/A",
        "warning": "N/A"
    },
    "is_complete_session": false
}

1. API khởi tạo phiên​

1.1. Request Url​

1.2. Request Headers​

1.3. Mẫu request​

1.4. Response​

1.4.1. Mẫu response​

1.4.2. Mô tả response​

2. API kiểm tra liveness và so khớp khuôn mặt​

2.1. Request Url​

2.2. Request Headers​

2.3. Request Body​

2.4. Mẫu request​

2.5. Response​

2.5.1. Mẫu response thành công​

2.5.2. Mô tả response​

2.5.3. Mẫu response lỗi​