Đọc thông tin thẻ ID

Trích xuất các trường được in và mã hóa từ một ảnh thẻ ID (ID card) — văn bản OCR, vùng đọc bằng máy MRZ, mã QR và, khi có, dữ liệu chip NFC — mỗi trường kèm một độ tin cậy.

Endpoint

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

{
  "card_type": "vn.national_id",
  "image1": {
    "id": "2dc863d6-1f68-4c82-8380-dd34e4ed7da0",
    "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ẻ. Xem Khuyến nghị sử dụng.
image1	ImageData	Có	—	Ảnh mặt trước hoặc mặt sau của thẻ định danh.

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, không bao giờ cả hai.

Ví dụ request

curl --location '<BASE_URL>/v1/read_id_card_info_sync' \
  --header 'Authorization: ATV <ACCESS_ID>:<SIGNATURE>' \
  --header 'X-TV-Timestamp: <TIMESTAMP>' \
  --header 'Content-Type: application/json' \
  --data '{
    "card_type": "vn.national_id",
    "image1": {
      "id": "e94288e6-7ab5-4aeb-9608-8382f4ceb92f",
      "base64": "",
      "label": "id_card.vn.national_id.back",
      "metadata": "{}"
    }
  }'

Response

{
  "data": {
    "request_id": "09c1bf6b-2522-4202-b3e5-a2d63dc2d0ea",
    "status": "success",
    "card_information": [
      {
        "field": "name",
        "value": "NGUYỄN VĂN A",
        "confidence_score": 0.904328,
        "confidence_verdict": "SURE",
        "digit_confidence_scores": []
      }
    ],
    "image1": {
      "id": "2dc863d6-1f68-4c82-8380-dd34e4ed7da0",
      "card_box": {
        "top_left": { "x": 134, "y": 191 },
        "top_right": { "x": 946, "y": 191 },
        "bottom_left": { "x": 134, "y": 710 },
        "bottom_right": { "x": 946, "y": 710 }
      },
      "ocr": {
        "parsed": [
          {
            "field": "id",
            "value": "001xxxxxxxxx",
            "confidence_score": 0.90224093,
            "confidence_verdict": "SURE",
            "digit_confidence_scores": []
          }
        ],
        "char_probs": [],
        "confidence_score": 0,
        "entropy": 0,
        "group": 0,
        "label": 0,
        "line": 0,
        "text": ""
      },
      "mrz": { "parsed": [], "char_probs": [], "confidence_score": 0, "entropy": 0, "group": 0, "label": 0, "line": 0, "text": "" },
      "qr": { "parsed": [], "char_probs": [], "confidence_score": 0, "entropy": 0, "group": 0, "label": 0, "line": 0, "text": "" },
      "nfc": null
    },
    "image2": null
  },
  "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.card_information	ParsedField[]	Các trường của thẻ đã được hợp nhất, gộp từ mọi nguồn có sẵn.
data.image1	ImageResult	Kết quả trích xuất theo từng nguồn 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.

ImageResult

Trường	Kiểu	Mô tả
id	string	ID của ảnh đã phân tích.
card_box	CardBox	Tọa độ các góc của thẻ được phát hiện, mỗi góc { "x": int, "y": int }.
ocr	ExtractionResult	Các trường đọc được từ bề mặt in của thẻ.
mrz	ExtractionResult	Các trường đọc được từ vùng đọc bằng máy.
qr	ExtractionResult	Các trường đọc được từ mã QR.
nfc	ExtractionResult	Các trường đọc được từ chip NFC, hoặc null khi không có dữ liệu chip nào được cung cấp.

ExtractionResult

Trường	Kiểu	Mô tả
parsed	ParsedField[]	Các trường có cấu trúc được trích xuất từ nguồn này.
text	string	Văn bản thô đọc được từ nguồn này.
char_probs	float[]	Xác suất tin cậy theo từng ký tự.
confidence_score	float	Độ tin cậy tổng thể cho nguồn này.
entropy	float	Entropy của kết quả nhận dạng.
group	int	Chỉ số nhóm nội bộ.
label	int	Chỉ số nhãn nội bộ.
line	int	Chỉ số dòng trong nguồn.

ParsedField

Trường	Kiểu	Mô tả
field	string	Tên trường, ví dụ id, name.
value	string	Giá trị đã trích xuất.
confidence_score	float	Độ tin cậy của giá trị đã trích xuất, khoảng 0–1.
confidence_verdict	string	Độ tin cậy dạng phân loại, ví dụ SURE.
digit_confidence_scores	float[]	Độ tin cậy theo từng chữ số cho các trường dạng số.

INFO

Không coi một trường có độ tin cậy thấp là dữ liệu đã được xác minh. Hãy chặn việc chấp nhận dựa trên confidence_verdict và confidence_score, và chuyển bất kỳ giá trị nào dưới ngưỡng của bạn sang xét duyệt thủ công — đặc biệt là số ID và ngày sinh.

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

• Phát hiện giả mạo thẻ ID — đối chiếu chéo OCR, MRZ và QR để tìm dấu hiệu giả mạo
• So sánh khuôn mặt — so khớp ảnh chân dung trên thẻ với ảnh selfie