Lấy dữ liệu NFC

Truy xuất dữ liệu NFC đã lưu trữ cho một document — bao gồm cả data group thô đọc được từ chip lẫn các trường thông tin định danh đã phân tích. Token của giao dịch chỉ đọc được đúng document_id đã gửi trong chính giao dịch đó.

Endpoint

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

{
  "document_id": "001xxxxxxxxx"
}

Tham số:

Tham số	Kiểu	Bắt buộc	Mặc định	Mô tả
document_id	string	Có	—	Số CCCD/CMND của người có dữ liệu NFC đang được truy xuất.

Trả về: GetNfcResponse

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}.

Ví dụ request

curl --location '<BASE_URL>/v1/get_nfc' \
  --header 'Authorization: Bearer <JWT_TOKEN>' \
  --header 'X-TV-Timestamp: <TIMESTAMP>' \
  --header 'Content-Type: application/json' \
  --data '{
    "document_id": "001xxxxxxxxx"
  }'

Response

{
  "success": true,
  "code": 0,
  "message": "success",
  "request_id": "request_id",
  "data": {
    "ref_id": "ref_00000001",
    "nfc_raw": {
      "sod": "d4IG/TCCBvkGCSqGSIb3DQEHAqCC…",
      "dg1": "YV1fH1pJRFZOTTAwMXh4eHh4eHh4eA…",
      "dg2": "dYIx1n9hgjHRAgEBf2CCMcmhDoEB…",
      "dg13": "bYIBmzCCAZcCAQEGBijTFgEACDGC…",
      "dg14": "boIBfjGCAXowDQYIBAB/AAcCAgIC…",
      "dg15": "b4IBJjCCASIwDQYJKoZIhvcNAQEB…",
      "com": "",
      "issue_date": "01/01/2021",
      "document_id": "001xxxxxxxxx"
    },
    "nfc_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,
      "created_at": 1672531200
    }
  }
}

Trường	Kiểu	Mô tả
data.ref_id	string	ID tham chiếu giao dịch mà dữ liệu được ghi nhận theo.
data.nfc_raw	NFCRaw	Các data group thô đọc được từ chip.
data.nfc_data	NFCData	Các trường thông tin định danh chủ thẻ đã phân tích.

NFCRaw

Trường	Kiểu	Mô tả
sod	string	Document Security Object. Base64.
dg1	string	Data group 1 — MRZ. Base64.
dg2	string	Data group 2 — ảnh khuôn mặt. Base64.
dg13	string	Data group 13 — thông tin cá nhân bổ sung. Base64.
dg14	string	Data group 14 — tùy chọn bảo mật cho xác thực chip. Base64.
dg15	string	Data group 15 — public key dùng cho active authentication. Base64.
com	string	Thành phần dữ liệu Common, liệt kê các data group có mặt trên chip.
issue_date	string	Ngày cấp thẻ, DD/MM/YYYY.
document_id	string	Document ID mà bản ghi này thuộc về.

NFCData

Cùng cấu trúc với response của Đọc NFC, thêm hai timestamp và không có verification_key:

Trường	Kiểu	Mô tả
is_verified	bool	Bản ghi có được xác minh với C06 hay không.
verified_at	int	Unix timestamp của thời điểm xác minh.
created_at	int	Unix timestamp của thời điểm bản ghi được tạo.

WARNING

Endpoint này chỉ trả về bản ghi của đúng document_id đã được gửi trong cùng giao dịch — token không thể đọc bất kỳ giấy tờ nào khác. Response vẫn chứa đầy đủ dữ liệu định danh và ảnh chân dung trên chip: không bao giờ ghi log hay lưu cache trên thiết bị.

Lỗi

Mã	Mô tả
2001002	internal_bad_gateway
2001027	Token không hợp lệ.
2001029	Không tìm thấy thông tin NFC.
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

• Định nghĩa các trường CCCD — quy tắc chuẩn hóa và lưu trữ cho các trường được trả về ở đây
• Tổng quan — toàn bộ vòng đời giao dịch