Đọc NFC

Gửi các data group thô đọc được từ chip CCCD và trả về thông tin định danh chủ thẻ đã phân tích, ảnh chân dung trên chip, và một verification_key mà backend của bạn cần để hoàn tất luồng. Được gọi bởi Mobile SDK.

Endpoint

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

{
  "sod": "d4IG/TCCBvkGCSqGSIb3DQEHAqCC…",
  "dg1": "YV1fH1pJRFZOTTAwMXh4eHh4eHh4eA…",
  "dg2": "dYIx1n9hgjHRAgEBf2CCMcmhDoEB…",
  "dg13": "bYIBmzCCAZcCAQEGBijTFgEACDGC…",
  "dg14": "boIBfjGCAXowDQYIBAB/AAcCAgIC…",
  "dg15": "b4IBJjCCASIwDQYJKoZIhvcNAQEB…",
  "document_id": "001xxxxxxxxx",
  "ref_id": "ref_00000001"
}

Tham số:

Tham số	Kiểu	Bắt buộc	Mặc định	Mô tả
sod	string	Có	—	Document Security Object trích xuất từ chip NFC. Base64.
dg1	string	Có	—	Data group 1 — MRZ. Trích xuất từ chip NFC. Base64.
dg2	string	Có	—	Data group 2 — ảnh khuôn mặt. Trích xuất từ chip NFC. Base64.
dg13	string	Có	—	Data group 13 — thông tin cá nhân bổ sung. Trích xuất từ chip NFC. Base64.
dg14	string	Có	—	Data group 14 — tùy chọn bảo mật cho xác thực chip. Trích xuất từ chip NFC. Base64.
dg15	string	Có	—	Data group 15 — public key dùng cho active authentication. Trích xuất từ chip NFC. Base64.
document_id	string	Có	—	Số CCCD/CMND của người có chip đang được xác minh.
ref_id	string	Có	—	ID tham chiếu giao dịch từ Tạo giao dịch.

Trả về: ReadNfcResponse

Xác thực lệnh gọi này bằng JWT token từ Tạo giao dịch, dạng Authorization: Bearer {token} — không dùng HMAC.

Ví dụ request

curl --location '<BASE_URL>/v1/read_nfc' \
  --header 'Authorization: Bearer <JWT_TOKEN>' \
  --header 'X-TV-Timestamp: <TIMESTAMP>' \
  --header 'Content-Type: application/json' \
  --data '{
    "sod": "d4IG/TCCBvkGCSqGSIb3DQEHAqCC…",
    "dg1": "YV1fH1pJRFZOTTAwMXh4eHh4eHh4eA…",
    "dg2": "dYIx1n9hgjHRAgEBf2CCMcmhDoEB…",
    "dg13": "bYIBmzCCAZcCAQEGBijTFgEACDGC…",
    "dg14": "boIBfjGCAXowDQYIBAB/AAcCAgIC…",
    "dg15": "b4IBJjCCASIwDQYJKoZIhvcNAQEB…",
    "document_id": "001xxxxxxxxx",
    "ref_id": "ref_00000001"
  }'

Response

{
  "success": true,
  "code": 0,
  "message": "success",
  "request_id": "request_id",
  "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,
    "verification_key": "<VERIFICATION_KEY>"
  }
}

NFCData

Trường	Kiểu	Mô tả
citizen_identify	string	Số CCCD 12 chữ số.
old_citizen_identify	string	Số CMND cũ gồm 9 chữ số, nếu công dân từng có.
full_name	string	Họ tên đầy đủ theo pháp lý của chủ thẻ.
date_of_birth	string	Ngày sinh, DD/MM/YYYY.
date_of_expiry	string	Ngày hết hạn thẻ, DD/MM/YYYY.
gender	string	Nam (nam) hoặc Nữ (nữ).
nationality	string	Quốc tịch, ví dụ Việt Nam.
ethnic	string	Dân tộc, ví dụ Kinh.
religion	string	Tôn giáo, ví dụ Không (không có).
place_of_origin	string	Quê quán — nơi sinh đăng ký của công dân.
place_of_residence	string	Địa chỉ thường trú đã đăng ký.
personal_identification	string	Đặc điểm nhận dạng in trên thẻ.
date_provide	string	Ngày cấp thẻ, DD/MM/YYYY.
father_name	string	Họ tên cha.
mother_name	string	Họ tên mẹ.
partner_name	string	Họ tên vợ/chồng, rỗng nếu không được ghi nhận.
face_image	string	Ảnh chân dung JPEG mã hóa Base64, đọc từ DG2.
is_verified	bool	Dữ liệu chip có vượt qua kiểm tra toàn vẹn tại thời điểm đọc hay không.
verification_key	string	Key backend của bạn gửi cho Xác minh NFC. Độ dài tối đa 128.

WARNING

is_verified trả về ở đây chỉ phản ánh lần đọc chip, không phải một lần kiểm tra với C06. Không dùng giá trị này để phê duyệt onboarding — SDK đang chạy trên một thiết bị bạn không kiểm soát. Hãy hoàn tất luồng bằng Xác minh NFC và quyết định dựa trên kết quả phía server đó.

Lỗi

Mã	Mô tả
2001002	internal_bad_gateway
2001019	Không tìm thấy giao dịch.
2001020	Lock giao dịch thất bại.
2001021	Request giao dịch không hợp lệ.
2001022	Giao dịch đã được xác minh.
2001027	Token không hợp lệ.
2001030	Document ID không hợp lệ.
4001000	Tham số đầu vào vi phạm một ràng buộc.
4291000	Số lượng request vượt quá giới hạn throughput.
5001000	internal_server_error

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

• Xác minh NFC — biến verification_key thành một kết quả xác minh dựa trên C06
• Định nghĩa các trường CCCD — định dạng, quy tắc kiểm tra hợp lệ và chuẩn hóa cho mọi trường ở trên