Xác minh NFC

Xác minh một lần đọc chip đã hoàn tất với cơ sở dữ liệu công an quốc gia C06 và đóng giao dịch. Đây là kết quả đáng tin cậy duy nhất trong luồng NFC — hãy quyết định dựa trên kết quả này, không phải những gì SDK đã báo cáo.

Endpoint

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

{
  "document_id": "001xxxxxxxxx",
  "ref_id": "ref_00000001",
  "verification_key": "<VERIFICATION_KEY>"
}

Tham số:

Tham số	Kiểu	Bắt buộc	Mặc định	Mô tả
document_id	string	Có	—	Document ID. Độ dài tối đa 64.
ref_id	string	Có	—	ID tham chiếu giao dịch. Độ dài tối đa 64.
verification_key	string	Có	—	Verification key được trả về bởi Đọc NFC. Độ dài tối đa 128.
force_rar_verify	bool	Không	false	Xác minh với C06 bất kể trạng thái xác minh hiện tại.
verify_transaction_only	bool	Không	false	Chỉ xác minh tính toàn vẹn của response từ Đọc NFC, không gọi C06.

Trả về: VerifyNfcResponse

Xác thực lệnh gọi này bằng HMAC — xem Tổng quan § Xác thực.

INFO

verify_transaction_only kiểm tra rằng lần đọc không bị can thiệp, nhưng bỏ qua hoàn toàn việc tra cứu C06 — nó không xác nhận công dân có tồn tại trong cơ sở dữ liệu quốc gia hay không. Chỉ dùng nó cho các kiểm tra toàn vẹn thuần túy, không bao giờ thay thế cho một lần xác minh đầy đủ.

Ví dụ request

curl --location '<BASE_URL>/v1/verify_nfc' \
  --header 'Authorization: ATV <ACCESS_ID>:<SIGNATURE>' \
  --header 'X-TV-Timestamp: <TIMESTAMP>' \
  --header 'Content-Type: application/json' \
  --data '{
    "document_id": "001xxxxxxxxx",
    "ref_id": "ref_00000001",
    "verification_key": "<VERIFICATION_KEY>"
  }'

Response

{
  "success": true,
  "code": 0,
  "message": "success",
  "request_id": "50e34861-d362-46ac-bf93-119e8dc6f2bf",
  "data": {
    "citizen_identify": "001xxxxxxxxx",
    "old_citizen_identify": "xxxxxxxxx",
    "full_name": "Nguyễn Văn A",
    "date_of_birth": "12/12/1990",
    "date_of_expiry": "12/12/2030",
    "gender": "Nam",
    "nationality": "Việt Nam",
    "ethnic": "Kinh",
    "religion": "Không",
    "place_of_origin": "Xã An Khánh, Huyện Châu Thành, Tỉnh Bến Tre",
    "place_of_residence": "Tổ 1, Phường Bến Nghé, Quận 1, TP. Hồ Chí Minh",
    "personal_identification": "Sẹo chấm cách 1cm trên đuôi mày trái",
    "date_provide": "01/01/2021",
    "father_name": "Nguyễn Văn B",
    "mother_name": "Trần Thị C",
    "partner_name": "",
    "face_image": "/9j/4AAQSkZJRgABAQA…",
    "is_verified": true,
    "verified_at": 1672531200
  }
}

Trường	Kiểu	Mô tả
code	int	Mã lỗi — 0 nghĩa là không có lỗi. Độ dài tối đa 10.
request_id	string	ID request của server, dùng để tracing. Độ dài tối đa 64.
data.is_verified	bool	Trạng thái xác minh NFC với C06.
data.verified_at	int	Unix timestamp của thời điểm lần đọc NFC được xác minh. Độ dài tối đa 10.

Các trường data còn lại mang thông tin định danh chủ thẻ, có cấu trúc giống hệt response của Đọc NFC.

Khi thành công, trạng thái giao dịch chuyển sang VERIFIED.

WARNING

Hãy xác minh header X-Signature trước khi tin tưởng is_verified — một response chưa ký hoặc chưa được xác minh là một response chưa được xác thực. Xem Tổng quan § Ký response.

Lỗi

Mã	Mô tả
2001010	API key không đúng.
2001019	Không tìm thấy reference ID.
2001020	Lock giao dịch thất bại.
2001021	Request giao dịch không hợp lệ.
2001023	Khóa giao dịch không hợp lệ.
5001000	Lỗi server nội bộ.

Mã	Mô tả
401	Bạn không được phép thực hiện hành động này.
500	Xảy ra lỗi không mong đợi trong quá trình xử lý request.

Bước tiếp theo

• Lấy dữ liệu NFC — truy xuất dữ liệu chip thô và đã phân tích được lưu trữ sau đó
• Định nghĩa các trường CCCD — cách chuẩn hóa và lưu trữ các trường đã xác minh