Xác minh Face Authen

Xác thực một người dùng dựa trên hồ sơ (profile) khuôn mặt đã đăng ký của họ và trả về matched, unmatched hoặc unsure cùng một điểm số. Khi một ref_id giao dịch được cung cấp, nó cũng cấp một authentication_key mà backend của bạn redeem để đóng giao dịch.

Endpoint

http

POST /v1/face_auth
Content-Type: application/json

json

{
  "user_id": "user_00000001",
  "ref_id": "ref_00000001",
  "faces": [
    { "id": "a4facba3-334b-41fb-97e3-4766cb70ae29" }
  ],
  "device_id": "device_00000001",
  "app_id": "app_00000001",
  "lat": "10.7769",
  "lng": "106.7009",
  "face_type": "selfie",
  "metadata": { "key2": "value2" }
}

Tham số:

Tham số	Kiểu	Bắt buộc	Mặc định	Mô tả
`user_id`	string	Có	—	User ID của khách hàng.
`ref_id`	string	Không	—	ID tham chiếu của một giao dịch được tạo trước khi xác minh. Hãy cung cấp nó để giao dịch có thể được tra cứu sau đó theo trạng thái.
`faces`	ImageData[]	Có	—	Ảnh selfie của người dùng. Cần ít nhất một ảnh.
`device_id`	string	Không	—	Device ID của người dùng, hiển thị trong lịch sử face auth trên admin portal.
`app_id`	string	Không	—	App mà khách hàng đã dùng, hiển thị trong lịch sử face auth.
`lat`	string	Không	—	Vĩ độ của thiết bị được dùng.
`lng`	string	Không	—	Kinh độ của thiết bị được dùng.
`face_type`	string	Không	`selfie`	Loại ảnh khuôn mặt đầu vào: `selfie` hoặc `id_card`.
`metadata`	json_object	Không	—	Bất kỳ metadata key-value nào để lưu cùng lần đăng nhập này.

ImageData

Tham số	Kiểu	Bắt buộc	Mặc định	Mô tả
`id`	string	Không	—	ID của ảnh được trả về bởi Tải ảnh lên.
`base64`	string	Không	—	Văn bản dữ liệu ảnh mã hóa Base64.
`label`	string	Không	—	Nhãn của ảnh, như mô tả trong Khuyến nghị sử dụng.
`metadata`	string_json	Không	—	Chuỗi JSON key/value. Ví dụ: `{"gesture":"left","type":1}`

Trả về: VerifyFaceAuthResponse

Ví dụ request

bash

curl -X POST \
  '<BASE_URL>/v1/face_auth' \
  -H 'Authorization: ATV <ACCESS_ID>:<SIGNATURE>' \
  -H 'X-TV-Timestamp: <TIMESTAMP>' \
  -H 'Content-Type: application/json' \
  -d '{
    "user_id": "user_00000001",
    "faces": [
      { "id": "a4facba3-334b-41fb-97e3-4766cb70ae29" },
      { "id": "c5a2a405-f152-4248-b746-3af76b241ef7" },
      { "id": "5d0345f7-da7c-44e8-bd6c-a8c08c806227" }
    ]
  }'

Signature của thiết bị (request từ SDK)

Khi Mobile SDK gọi endpoint này bằng token giao dịch (Authorization: Bearer …), trên tenant đã bật kiểm tra signature của thiết bị, SDK còn gửi Device-Id, X-Device-Key-Id và X-Device-Signature. Khóa ký (signing credential) mà X-Device-Key-Id chỉ tới phải ở trạng thái ACTIVE và được đăng ký cho cùng Device-Id; nếu không, request bị từ chối với access_denied_exception. Xem Ký request để biết khi nào các header này là bắt buộc.

Response

json

{
  "data": {
    "status": "success",
    "auth_check": {
      "score": 0.98,
      "result": "matched"
    },
    "request_id": "cfc7b8d5-f2e2-437b-80e5-d600dfad26e2",
    "authentication_key": "<AUTHENTICATION_KEY>"
  },
  "errors": [],
  "success": true,
  "code": 0,
  "message": "Success"
}

Trường	Kiểu	Mô tả
`data.status`	string	`success` hoặc `failure`.
`data.auth_check`	object	Kết quả xác thực. Có mặt khi `success` là `true`.
`data.auth_check.result`	string	`matched`, `unmatched` hoặc `unsure`.
`data.auth_check.score`	float	Xác suất khuôn mặt được cung cấp khớp với hồ sơ, khoảng 0–1.
`data.request_id`	string	Request ID; cung cấp cho CAKE Support khi cần kiểm tra log.
`data.authentication_key`	string	Key mà backend của bạn redeem tại Xác minh khóa xác thực giao dịch.

WARNING

Không phê duyệt hành động dựa trên auth_check.result do ứng dụng báo cáo. Hãy redeem authentication_key từ backend của bạn và quyết định dựa trên kết quả đó — một client có thể tự khai bất kỳ verdict nào nó muốn. Coi unsure là một kết quả riêng biệt cần xem xét thủ công, không phải một dạng matched mềm.

Lỗi

Mã	Thông báo
`2001003`	Ảnh gửi lên server không có khuôn mặt nào.
`2001006`	Các khuôn mặt phát hiện được từ ảnh gửi lên server không khớp nhau.
`2001008`	Khuôn mặt đã được đăng ký trong hệ thống.
`2001009`	Ảnh gửi lên server có nhiều khuôn mặt.
`2001010`	Không tìm thấy Access ID.
`2001011`	Kiểm tra liveness của selfie / id_card thất bại.
`2001012`	Kiểm tra sanity của selfie / id_card thất bại.
`2001016`	Vượt giới hạn tốc độ face auth.
`2001017`	Vượt giới hạn brute-force của face auth.
`2001025`	Ảnh selfie gửi lên server có độ dài không khớp với cấu hình.
`2001026`	Các ảnh gửi lên server bị trùng lặp.
`2002201`	Xác thực khuôn mặt không khớp (verdict `unsure`).
`2002205`	Xác thực khuôn mặt không khớp (verdict `unmatched`).
`2002206`	Hồ sơ người dùng đã bị khóa.
`2009005`	Phiên bản SDK không còn được hỗ trợ. Vui lòng cập nhật ứng dụng.
`401100`	Bạn không được phép thực hiện hành động này.
`4001000`	Tham số đầu vào vi phạm một ràng buộc.
`4001001`	Header `X-TV-Timestamp` đã hết hạn, cần một cái mới hơn.
`4001002`	Ảnh selfie hoặc ảnh gốc có nhiều hơn 1 khuôn mặt.
`4041000`	Không tìm thấy image ID trong DB.
`4041001`	Không tìm thấy người dùng.
`4091000`	`user_id` đã được đăng ký.
`4131000`	Kích thước ảnh đầu vào vượt quá giới hạn cho phép (15MB).
`4151000`	Định dạng ảnh được cung cấp không được hỗ trợ (JPG/PNG).
`4291000`	Số lượng request vượt quá giới hạn throughput của bạn.
`5001000`	Xảy ra lỗi không mong đợi trong quá trình xử lý request.

Mã	Mô tả
`access_denied_exception`	Bạn không được phép thực hiện hành động này.
`invalid_parameter_exception`	Tham số đầu vào vi phạm một ràng buộc.
`request_time_too_skewed`	Header `X-TV-Timestamp` đã hết hạn, cần một cái mới hơn.
`incorrect_number_of_faces`	Ảnh selfie hoặc ảnh gốc có nhiều hơn 1 khuôn mặt.
`image_not_found_exception`	Không tìm thấy image ID trong DB.
`user_profile_not_found_exception`	Không tìm thấy hồ sơ của người dùng.
`user_profile_locked`	Hồ sơ người dùng đã bị khóa.
`face_auth_rate_limit_exceeded`	Vượt giới hạn tốc độ face auth.
`face_auth_brute_force_limit_exceeded`	Vượt giới hạn brute-force của face auth.
`sdk_version_unsupported`	SDK cũ hơn phiên bản tối thiểu mà tenant của bạn chấp nhận cho các request có signature của thiết bị.
`image_too_large_exception`	Kích thước ảnh đầu vào vượt quá giới hạn cho phép (15MB).
`invalid_image_format_exception`	Định dạng ảnh được cung cấp không được hỗ trợ (JPG/PNG).
`rate_limit_exception`	Số lượng request vượt quá giới hạn throughput của bạn.
`duplicated_image`	Các ảnh gửi lên server bị trùng lặp.
`selfie_image_invalid`	Ảnh selfie gửi lên server có độ dài không khớp với cấu hình.
`sanity_check_failed`	Kiểm tra sanity của selfie / id_card thất bại.
`liveness_check_failed`	Kiểm tra liveness của selfie / id_card thất bại.
`image_has_no_faces`	Ảnh gửi lên server không có khuôn mặt nào.
`image_has_multiple_faces`	Ảnh gửi lên server có nhiều khuôn mặt.
`face_already_registered`	Khuôn mặt đã được đăng ký trong hệ thống.
`compare_faces_not_matched`	Các khuôn mặt phát hiện được từ ảnh gửi lên server không khớp nhau.
`internal_server_error`	Xảy ra lỗi không mong đợi trong quá trình xử lý request.

Một lần không khớp là một lỗi, không phải một success: true với verdict tiêu cực: 2002205 cho unmatched và 2002201 cho unsure. Các lần thất bại liên tiếp sẽ gây ra face_auth_brute_force_limit_exceeded rồi khóa hồ sơ với 2002206.

Bước tiếp theo

Xác minh khóa xác thực giao dịch — redeem key được trả về ở đây
Mở khóa hồ sơ — gỡ một lần khóa sau các lần thất bại liên tiếp

Xác minh Face Authen ​

Endpoint ​

ImageData ​

Ví dụ request ​

Signature của thiết bị (request từ SDK) ​

Response ​

Lỗi ​

Bước tiếp theo ​