Cập nhật Face Authen

Thay thế các ảnh đã đăng ký trong một hồ sơ (profile) khuôn mặt hiện có. Dùng nó khi ngoại hình của người dùng đã thay đổi đủ nhiều để ảnh hưởng đến tỷ lệ khớp, hoặc để đăng ký lại sau một lần chụp ban đầu kém chất lượng.

Endpoint

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

{
  "user_id": "user_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.
faces	ImageData[]	Có	—	Ảnh selfie của người dùng, hoặc một document chứa một ảnh selfie. 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ị dùng cho lần cập nhật này.
lng	string	Không	—	Kinh độ của thiết bị dùng cho lần cập nhật này.
face_type	string	Không	selfie	Loại ảnh khuôn mặt đầu vào: selfie hoặc id_card. Dùng id_card cho một khuôn mặt trích xuất từ thẻ Căn cước công dân.
metadata	json_object	Không	—	Bất kỳ metadata key-value nào để lưu cùng khách hàng 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}

Chỉ cung cấp id hoặc base64, không bao giờ cả hai. CAKE khuyến nghị dùng id thay vì base64.

Trả về: UpdateFaceAuthResponse

Ví dụ request

curl -X POST \
  '<BASE_URL>/v1/update_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" }
    ],
    "face_type": "selfie",
    "device_id": "device_00000001",
    "app_id": "app_00000001",
    "lat": "10.7769",
    "lng": "106.7009",
    "metadata": {
      "key1": { "key11": "value11", "key12": "value12" },
      "key2": "value2"
    }
  }'

Response

{
  "data": {
    "status": "success",
    "request_id": "cfc7b8d5-f2e2-437b-80e5-d600dfad26e2",
    "face_auth": {
      "user_id": "user_00000001",
      "status": "VERIFIED"
    }
  },
  "errors": [],
  "success": true,
  "code": 0,
  "message": "Success"
}

Trường	Kiểu	Mô tả
data.status	string	success hoặc failure.
data.request_id	string	Request ID; cung cấp cho CAKE Support khi cần kiểm tra log.
data.face_auth.user_id	string	User ID mà hồ sơ thuộc về.
data.face_auth.status	string	Trạng thái hồ sơ sau khi cập nhật.

WARNING

Việc cập nhật thay thế template sinh trắc học mà mọi lần xác thực trong tương lai sẽ được đối chiếu. Hãy đặt endpoint này phía sau một lớp xác thực mạnh của riêng nó — một kẻ tấn công có thể gọi nó cho user_id của người khác có thể đăng ký khuôn mặt của chính mình và chiếm đoạt tài khoản.

Lỗi

Việc cập nhật chạy cùng cổng kiểm tra chất lượng và đối chiếu như đăng ký:

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.
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.
2001014	Vượt giới hạn tốc độ đăng ký.
2001015	Vượt giới hạn brute-force khi đăng ký.
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.
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.
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_id_not_found	Không tìm thấy Access ID.
register_rate_limit_exceeded	Vượt giới hạn tốc độ đăng ký.
register_brute_force_limit_exceeded	Vượt giới hạn brute-force khi đăng ký.
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.
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.
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.

Khác với đăng ký, cập nhật không có lỗi user_already_registered hay face_already_registered — hồ sơ được mặc định là đã tồn tại.

Bước tiếp theo

• Lấy thông tin Face Authen — xác nhận trạng thái hồ sơ sau đó
• Xóa Face Authen — xóa hồ sơ thay vì thay thế nó