Phân tích thông tin QR

Phân tích payload QR thô từ một thẻ Căn cước công dân Việt Nam thành các trường có cấu trúc, bao gồm một cấu trúc địa chỉ đã được phân tách. Dùng nó khi client của bạn đã có sẵn chuỗi QR đã giải mã và cần chuẩn hóa nó mà không cần gửi một ảnh.

Endpoint

http

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

json

{
  "raw_qr": "string"
}

Tham số:

Tham số	Kiểu	Bắt buộc	Mặc định	Mô tả
`raw_qr`	string	Có	—	Chuỗi mã QR thô từ thẻ. Phân tách bằng dấu gạch đứng theo thứ tự: Số định danh (12 chữ số) \| Số định danh cũ (9 chữ số hoặc rỗng) \| Họ tên đầy đủ \| Ngày sinh (`DDMMYYYY`) \| Giới tính (`Nam`/`Nữ`) \| Quê quán \| Ngày cấp (`DDMMYYYY`).

Trả về: ParseQrInfoResponse

Ví dụ request

bash

curl --location '<BASE_URL>/v1/parse_qr_info_sync' \
  --header 'Authorization: ATV <ACCESS_ID>:<SIGNATURE>' \
  --header 'X-TV-Timestamp: <TIMESTAMP>' \
  --header 'Content-Type: application/json' \
  --data '{
    "raw_qr": "001xxxxxxxxx|xxxxxxxxx|Nguyễn Văn A|12121990|Nam|Tổ 1, Phường Bến Nghé, Quận 1, TP. Hồ Chí Minh|01012021"
  }'

Response

json

{
  "success": true,
  "code": 0,
  "message": "Success",
  "data": {
    "request_id": "f48085e4-3ae4-40bb-b0e1-9b2c72575bc1",
    "status": "success",
    "qr": {
      "parsed": [
        { "field": "id", "value": "001xxxxxxxxx", "confidence_score": 1.0, "confidence_verdict": "" },
        { "field": "name", "value": "Nguyễn Văn A", "confidence_score": 1.0, "confidence_verdict": "" },
        { "field": "dob", "value": "12/12/1990", "confidence_score": 1.0, "confidence_verdict": "" },
        { "field": "address_level_1_(city)", "value": "TP. Hồ Chí Minh", "confidence_score": 1.0, "confidence_verdict": "" }
      ],
      "raw": "001xxxxxxxxx|xxxxxxxxx|Nguyễn Văn A|12121990|Nam|Tổ 1, Phường Bến Nghé, Quận 1, TP. Hồ Chí Minh|01012021"
    }
  },
  "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.qr.raw`	string	Chuỗi QR thô như đã gửi lên.
`data.qr.parsed`	ParsedField[]	Các trường có cấu trúc được trích xuất từ payload QR.

ParsedField

Trường	Kiểu	Mô tả
`field`	string	Tên trường — xem bảng bên dưới.
`value`	string	Giá trị đã trích xuất.
`confidence_score`	float	Luôn là `1.0` đối với QR, vốn được mã hóa thay vì được nhận dạng.
`confidence_verdict`	string	Rỗng đối với các trường có nguồn từ QR.

Các trường được trả về

Bảy trường đầu vào phân tách bằng dấu gạch đứng, cộng với một cấu trúc địa chỉ được suy ra từ quê quán:

Trường	Kiểu	Mô tả
`id`	string	Số CCCD, 12 chữ số.
`id_1`	string	Số CMND cũ, 9 chữ số.
`name`	string	Họ tên đầy đủ.
`dob`	string	Ngày sinh, chuẩn hóa về `DD/MM/YYYY`.
`gender`	string	`Nam` hoặc `Nữ`.
`native_place`	string	Quê quán như được in trên thẻ.
`issue_date`	string	Ngày cấp, chuẩn hóa về `DD/MM/YYYY`.
`address_level_1_(city)`	string	Tỉnh hoặc thành phố trực thuộc trung ương.
`address_level_1_(city)_code`	string	Mã hành chính cấp tỉnh.
`address_level_2_(district)`	string	Huyện.
`address_level_2_(district)_code`	string	Mã hành chính cấp huyện.
`address_level_3_(ward)`	string	Xã, phường hoặc thị trấn.
`address_level_3_(ward)_code`	string	Mã hành chính cấp xã.
`address_level_4`	string	Thôn hoặc tổ dân cư.

Ngày tháng đến dưới dạng DDMMYYYY và trả về dưới dạng DD/MM/YYYY.

Lỗi

Việc kiểm tra hợp lệ payload QR có dải mã 2007xxx riêng của nó:

Mã	Thông báo
`2007001`	Số định danh QR không hợp lệ.
`2007002`	Số định danh cũ QR không hợp lệ.
`2007003`	Ngày sinh QR không hợp lệ.
`2007004`	Giá trị giới tính QR không hợp lệ.
`2007005`	Ngày cấp QR không hợp lệ.
`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ả
`invalid_qr_identity_number`	Số định danh phải chính xác 12 chữ số.
`invalid_qr_old_identity_number`	Số định danh cũ phải rỗng hoặc chính xác 9 chữ số.
`invalid_qr_date_of_birth`	Định dạng ngày sinh không hợp lệ hoặc ngày đó không tồn tại. Định dạng mong đợi là `DDMMYYYY`.
`invalid_qr_gender_value`	Giới tính phải là `Nam` (nam) hoặc `Nữ` (nữ).
`invalid_qr_issue_date`	Định dạng ngày cấp không hợp lệ hoặc ngày đó không tồn tại. Định dạng mong đợi là `DDMMYYYY`.
`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.
`internal_server_error`	Xảy ra lỗi không mong đợi trong quá trình xử lý request.

Bước tiếp theo

Đọc thông tin thẻ ID — trích xuất các trường tương tự từ một ảnh thay vì
Phát hiện giả mạo thẻ ID — đối chiếu chéo QR với OCR và MRZ

Phân tích thông tin QR ​

Endpoint ​

Ví dụ request ​

Response ​

ParsedField ​

Các trường được trả về ​

Lỗi ​

Bước tiếp theo ​