Phát hiện thẻ ID

Định vị mọi thẻ ID (ID card) bên trong một ảnh và trả về tọa độ các góc cùng nhãn thẻ. Dùng nó để xác nhận một thẻ có mặt và được lấy khung đúng trước khi chạy OCR hoặc kiểm tra giả mạo.

Endpoint

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

{
  "card_type": "vn.national_id",
  "image": {
    "id": "a4facba3-334b-41fb-97e3-4766cb70ae29",
    "base64": "",
    "label": "id_card.vn.national_id.front",
    "metadata": "{}"
  }
}

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.
image	ImageData	Có	—	Ảnh mặt trước của thẻ định danh.

ImageData

interface ImageData {
  id?: string;
  base64?: string;
  label?: string;
  metadata?: string; // Chuỗi JSON
}

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. Nếu bạn dùng base64, hãy gửi thêm label và metadata và bỏ qua id. Nếu bạn dùng id, hãy bỏ qua ba trường còn lại.

Ví dụ request

curl -X POST \
  '<BASE_URL>/v1/detect_id_cards_sync' \
  -H 'Authorization: ATV <ACCESS_ID>:<SIGNATURE>' \
  -H 'X-TV-Timestamp: <TIMESTAMP>' \
  -H 'Content-Type: application/json' \
  -d '{
    "card_type": "vn.national_id",
    "image": {
      "id": "a4facba3-334b-41fb-97e3-4766cb70ae29"
    }
  }'

Response

{
  "data": {
    "request_id": "f77bf948-fce3-48f3-b61c-396e4cd9a89b",
    "status": "success",
    "image": {
      "id": "854322f0-eb49-4bd6-b870-050fcc088d10",
      "cards": [
        {
          "card_box": {
            "top_left": { "x": 90.52290163561702, "y": 110.761657032324 },
            "top_right": { "x": 981.4022462964058, "y": 101.39770825190935 },
            "bottom_left": { "x": 102.62150720786303, "y": 679.5154545297846 },
            "bottom_right": { "x": 996.863339483738, "y": 661.6368409626185 }
          },
          "card_label": "vn.cccd_new.front",
          "transformed_image_id": ""
        }
      ]
    }
  },
  "errors": []
}

Trường	Kiểu	Mô tả
data.request_id	string	Request ID; cung cấp cho CAKE Support khi cần kiểm tra log.
data.status	string	success hoặc failure.
data.image.id	string	ID của ảnh đã phân tích.
data.image.cards	array	Một phần tử cho mỗi thẻ được phát hiện trong ảnh.
data.image.cards[].card_label	string	Nhãn thẻ được phát hiện, ví dụ vn.cccd_new.front.
data.image.cards[].transformed_image_id	string	ID của ảnh thẻ đã được chỉnh nghiêng/cắt. Chỉ có mặt khi cấu hình tenant enable_create_image là true.
data.image.cards[].card_box	CardBox	Tọa độ các góc của thẻ được phát hiện.

CardBox

Trường	Kiểu	Mô tả
top_left	Point	Góc trên-trái, { "x": float, "y": float }.
top_right	Point	Góc trên-phải.
bottom_left	Point	Góc dưới-trái.
bottom_right	Point	Góc dưới-phải.

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.
request_not_found_exception	Không tìm thấy request ID khi poll kết quả theo id.
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

• Xác minh sanity thẻ ID — cổng chất lượng bao phủ mờ, chói lóa, bản photocopy và ảnh nhiều thẻ
• Đọc thông tin thẻ ID — trích xuất các trường của thẻ