Đăng ký khuôn mặt

Đăng ký hồ sơ (profile) khuôn mặt của một người dùng, template mà mọi lần xác thực sau này sẽ được đối chiếu. Việc đăng ký chạy các kiểm tra sanity, liveness và đối chiếu chéo giữa các ảnh trước khi hồ sơ được tạo.

Endpoint

http

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

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 như mặt trước của thẻ ID. Cần ít nhất một ảnh.
`device_id`	string	Không	—	Device ID của người dùng, để lịch sử face auth trên admin portal cho biết thiết bị nào đã thực hiện đăng ký.
`app_id`	string	Không	—	App mà khách hàng đã dùng, để lịch sử face auth cho biết app nào đã thực hiện đăng ký.
`lat`	string	Không	—	Vĩ độ của thiết bị dùng cho lần đăng ký này.
`lng`	string	Không	—	Kinh độ của thiết bị dùng cho lần đăng ký 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, ví dụ khi đọc chip NFC của thẻ.
`metadata`	json_object	Không	—	Bất kỳ metadata key-value nào để lưu cùng khách hàng này. Cho phép object lồng nhau.

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.

INFO

faces là bắt buộc — gửi ít nhất một ảnh; một lần đăng ký không có khuôn mặt nào thì không có gì để đăng ký.

Trả về: RegisterFacesResponse

Ví dụ request

bash

curl -X POST \
  '<BASE_URL>/v1/face_auth_register' \
  -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" }
    ],
    "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

json

{
  "data": {
    "status": "success",
    "request_id": "cfc7b8d5-f2e2-437b-80e5-d600dfad26e2",
    "face_auth": {
      "user_id": "user_00000001",
      "status": "VERIFIED"
    }
  },
  "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ơ được tạo cho.
`data.face_auth.status`	string	Trạng thái hồ sơ, ví dụ `VERIFIED`.

WARNING

Một template khuôn mặt là dữ liệu sinh trắc học. Chỉ đăng ký khi có sự đồng ý của khách hàng, và dùng Xóa Face Authen để đáp ứng các yêu cầu xóa dữ liệu.

Lỗi

Việc đăng ký hiển thị các lỗi về chất lượng và đối chiếu đã từ chối lần đă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.
`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.
`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.
`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_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.
`user_already_registered`	`user_id` đã được đăng ký.
`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.

face_already_registered và user_already_registered là hai lỗi khác nhau: lỗi đầu nghĩa là khuôn mặt đó thuộc về một hồ sơ khác, lỗi sau nghĩa là user_id này đã có một hồ sơ rồi.

Bước tiếp theo

Xác minh Face Authen — xác thực dựa trên hồ sơ bạn vừa tạo
Cập nhật Face Authen — thay thế các khuôn mặt đã đăng ký sau này

Đăng ký khuôn mặt ​

Endpoint ​

ImageData ​

Ví dụ request ​

Response ​

Lỗi ​