Xác minh sanity thẻ ID

Kiểm tra chất lượng của một hoặc hai ảnh thẻ ID (ID card) và trả về một kết luận (verdict) như good, image1_not_qualified hoặc photocopied. Hãy chạy bước này trước Đọc thông tin thẻ ID, Phát hiện giả mạo thẻ ID hoặc So sánh khuôn mặt — một ảnh thẻ chất lượng kém sẽ làm giảm độ tin cậy của mọi kiểm tra downstream.

Endpoint

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

{
  "card_type": "vn.national_id",
  "image1": {
    "id": "7db00808-0416-45cf-a5cb-3b6dfbd7bb74",
    "base64": "",
    "label": "id_card.vn.national_id.front",
    "metadata": "{}"
  },
  "image2": {
    "id": "a4facba3-334b-41fb-97e3-4766cb70ae29",
    "base64": "",
    "label": "id_card.vn.national_id.back",
    "metadata": "{}"
  },
  "special_id_type": ""
}

Tham số:

Tham số	Kiểu	Bắt buộc	Mặc định	Mô tả
card_type	string	Có	—	Loại thẻ định danh. Xem Khuyến nghị sử dụng.
image1	ImageData	Có	—	Ảnh mặt trước của thẻ, hoặc mặt sau khi image2 để trống.
image2	ImageData	Không	—	Ảnh mặt sau của thẻ.
special_id_type	string	Không	default	Chuỗi ID do CAKE cung cấp để chọn một use case đặc biệt. Bỏ qua để dùng mặc định.

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ụ: {"id":"<ID>","type":1}

Chỉ cung cấp id hoặc base64 cho mỗi ảnh, không bao giờ cả hai.

Ví dụ request

curl -X POST \
  '<BASE_URL>/v1/verify_id_card_sanity_sync' \
  -H 'Authorization: ATV <ACCESS_ID>:<SIGNATURE>' \
  -H 'X-TV-Timestamp: <TIMESTAMP>' \
  -H 'Content-Type: application/json' \
  -d '{
    "card_type": "vn.national_id",
    "image1": { "id": "7db00808-0416-45cf-a5cb-3b6dfbd7bb74" },
    "image2": { "id": "a4facba3-334b-41fb-97e3-4766cb70ae29" }
  }'

Response

{
  "data": {
    "status": "success",
    "card_sanity": {
      "score": 1,
      "verdict": "good"
    },
    "image1": {
      "id": "3ebebfe1-cf6c-4c7a-bee2-2dba834a6f1d",
      "transformed_image_id": "",
      "card_box": null
    },
    "image2": null,
    "request_id": "f77bf948-fce3-48f3-b61c-396e4cd9a89b"
  },
  "errors": []
}

Trường	Kiểu	Mô tả
data.status	string	success hoặc failure.
data.card_sanity.verdict	string	good, hoặc vấn đề đầu tiên phát hiện được. Xem Định nghĩa kết luận.
data.card_sanity.score	float	Khoảng 0–1. Khi verdict là good, score là 1; với các kết luận khác, giá trị càng cao nghĩa là thẻ càng có khả năng không đạt yêu cầu.
data.card_sanity.info	string	Ngữ cảnh bổ sung tùy chọn — ví dụ 6 chữ số cuối của chip CCCD.
data.image1	ImageResult	Kết quả cho ảnh thứ nhất.
data.image2	ImageResult	Kết quả cho ảnh thứ hai, hoặc null khi không được cung cấp.
data.request_id	string	Request ID; cung cấp cho CAKE Support khi cần kiểm tra log.

ImageResult

Trường	Kiểu	Mô tả
id	string	ID của ảnh đã phân tích.
transformed_image_id	string	ID của ảnh đã biến đổi, chỉ có mặt khi ảnh đã được biến đổi.
card_box	CardBox	Tọa độ các góc của thẻ được phát hiện: top_left, top_right, bottom_left, bottom_right, mỗi góc { "x": int, "y": int }.

Chỉ vấn đề đầu tiên phát hiện được sẽ được trả về, không phải danh sách đầy đủ các lỗi. Hãy hiển thị cho người dùng một thông báo chụp lại chung chung (không bao giờ hiển thị verdict hay score) rồi kiểm tra lại.

Các kết luận về chói lóa (glare)

Khi một kết luận nêu tên một cảnh báo trên image1 hoặc image2, cảnh báo đó là một trong blurry, dirty, too_dark, too_bright, glare, glare_safe, glare_unsafe:

Trường	Kiểu	Mô tả
glare	string	Ảnh có một điểm chói lóa, có thể ở bất kỳ đâu trên ảnh.
glare_safe	string	Có chói lóa, nhưng nằm ngoài các vùng chứa thông tin thiết yếu như số ID, họ tên và ngày sinh.
glare_unsafe	string	Chói lóa rơi vào một vùng quan trọng và có thể ảnh hưởng đến kết quả OCR.

Lỗi

Mã	Thông báo
2001010	Không tìm thấy Access ID.
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.
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.
image_not_found_exception	Không tìm thấy image ID trong DB.
rate_limit_exception	Số lượng request vượt quá giới hạn throughput của bạn.
internal_server_error	Xảy ra lỗi không mong đợi trong quá trình xử lý request.

Bước tiếp theo

• Định nghĩa kết luận — ý nghĩa của từng kết luận sanity
• Đọc thông tin thẻ ID — trích xuất các trường của thẻ khi sanity đạt yêu cầu