Phát hiện giả mạo thẻ ID

Kiểm tra một ảnh thẻ ID (ID card) để tìm dấu hiệu giả mạo, chỉnh sửa hoặc phát lại (replay) — một ảnh chân dung bị tráo, font chữ bị chỉnh sửa, một thẻ được chụp lại từ màn hình, hoặc thông tin tự mâu thuẫn giữa OCR, MRZ và QR.

Endpoint

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

{
  "card_type": "vn.national_id",
  "image": {
    "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.
image	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}

Ví dụ request

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

Response

{
  "data": {
    "status": "success",
    "card_tampering": {
      "score": 1,
      "verdict": "alert",
      "details": [
        {
          "verdict": "photo_tampered",
          "score": 0.9394838,
          "info": "photo tampering detected"
        }
      ]
    },
    "image_id": "2dc863d6-1f68-4c82-8380-dd34e4ed7da0",
    "image2_id": "",
    "request_id": "d24883b6-f9ad-4d8b-a0fa-e8c6c81df87e"
  },
  "errors": []
}

Trường	Kiểu	Mô tả
data.status	string	success hoặc failure.
data.card_tampering.verdict	string	Kết luận (verdict) tổng thể — good khi không phát hiện giả mạo, ngược lại là alert.
data.card_tampering.score	float	Độ tin cậy của kết luận tổng thể, khoảng 0–1.
data.card_tampering.details	TamperingDetail[]	Từng tín hiệu giả mạo cụ thể được kích hoạt.
data.image_id	string	ID của ảnh đã phân tích.
data.image2_id	string	ID của ảnh thứ hai, rỗng khi chỉ một ảnh được cung cấp.
data.request_id	string	Request ID; cung cấp cho CAKE Support khi cần kiểm tra log.

TamperingDetail

Trường	Kiểu	Mô tả
verdict	string	Tín hiệu giả mạo cụ thể, ví dụ photo_tampered, non_liveness, qr_info_not_match. Xem Định nghĩa kết luận.
score	float	Độ tin cậy của tín hiệu này, khoảng 0–1.
info	string	Giải thích dạng người đọc được về tín hiệu này.

WARNING

Một kết luận good là bằng chứng, không phải một đảm bảo. Phát hiện giả mạo mang tính xác suất — hãy kết hợp nó với sanity thẻ ID, so khớp khuôn mặt và bộ quy tắc của riêng bạn trước khi phê duyệt một lần onboarding, và ghi log toàn bộ mảng details để phục vụ kiểm toán.

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 và logic phát hiện đằng sau từng kết luận giả mạo
• Xác minh liveness khuôn mặt — kiểm tra phát lại (replay) tương đương ở phía selfie