API xác thực CCCD

Một endpoint duy nhất trên AgentGW: gửi số CCCD và chứng thư số đọc từ chip, nhận kết quả hợp lệ hay không. Theo Phụ lục II — Đặc tả API kết nối.

Phụ lục chỉ quy định API giữa hệ thống của đơn vị và AgentGW. API giữa AgentGW và hệ thống eID do RAR quản lý, đơn vị không gọi trực tiếp.

Endpoint

MụcGiá trị
Mục đíchXác thực thẻ CCCD gắn chip qua chứng thư số trên chip
URLhttp://<địa-chỉ-AgentGW>:8443/eid/api/verify/request
MethodPOST

Header

HeaderNội dung
content-typeapplication/json; charset=utf-8
request_idMã duy nhất cho mỗi yêu cầu, đơn vị tự sinh; khuyến nghị UUID v4 chữ thường; không dùng lại.
request_timeyyyyMMddHHmmss, múi giờ GMT+7. Máy gửi phải đồng bộ giờ.
license_idMã giấy phép RAR cấp; hệ thống dùng nó để tìm cấu hình và khoá công khai. Sandbox mặc định LIC_TEST_001 nếu RAR thông báo.
device_typeMã loại thiết bị / nền tảng do RAR cấp hoặc chấp thuận; không tự đổi.
dia_chiTỉnh / thành phố thường trú ghi trên căn cước.
signatureChữ ký RSA-SHA256, xem Khoá CSK & chữ ký.

Request body

TrườngKiểuBắt buộcMô tả
id_cardStringCóSố CCCD gắn chip. AgentGW tự mã hoá trước khi chuyển tiếp; phía gọi không cần mã hoá.
dscertStringCóChứng thư số trên chip, Base64, một dòng. Phải giống tuyệt đối chuỗi đã ký.
authentication_locationStringKhôngĐịa điểm phát sinh yêu cầu, tối đa 255 ký tự, đúng thực tế.
authentication_purposeStringKhôngMục đích nghiệp vụ, tối đa 255 ký tự.
authentication_sourceStringKhôngNguồn / kênh khởi tạo (URL website, ứng dụng di động, hệ thống nghiệp vụ…), tối đa 255 ký tự.
{
  "id_card": "<số CCCD>",
  "dscert": "<chứng thư số trên chip, Base64>",
  "authentication_location": "<địa điểm>",
  "authentication_purpose": "<mục đích>",
  "authentication_source": "<nguồn>"
}

Response

Thành công (HTTP 200)

{
  "responds": {
    "responseId": "<mã phản hồi>",
    "exitcode": 0,
    "result": true,
    "message": "valid idcard",
    "time": 1679411830
  },
  "signature": "<chữ ký của hệ thống eID trên đối tượng responds>"
}
TrườngKiểuMô tả
responds.responseIdStringMã phản hồi, dùng truy vết và đối soát.
responds.exitcodeInteger0 là thành công; khác 0 xem Mã lỗi.
responds.resultBooleantrue nếu chứng thư trên chip hợp lệ và do Bộ Công an ký phát hành.
responds.messageStringMô tả trạng thái.
responds.timeIntegerThời điểm xử lý, Unix timestamp (giây).
signatureStringChữ ký RSA-SHA256 Base64 của hệ thống eID trên responds.

HTTP 200 chưa phải là thẻ hợp lệ. Phải đọc cả exitcode và result. Trên Sandbox, chứng thư giả vẫn trả 200 với result: false.

Thất bại (HTTP khác 200)

{ "error_code": "<mã lỗi>", "description": "<mô tả>" }

Header X-Verifier-Source của response cho biết lỗi từ đâu: verifier (AgentGW) hay platform (RAR).

Mẫu gọi

REQUEST_ID=$(cat /proc/sys/kernel/random/uuid)
REQUEST_TIME=$(TZ=Asia/Ho_Chi_Minh date +%Y%m%d%H%M%S)
SIGNING="$REQUEST_ID|$REQUEST_TIME|$LICENSE_ID|$DEVICE_TYPE|$DIA_CHI|$ID_CARD|$DSCERT"
SIGNATURE=$(printf '%s' "$SIGNING" | openssl dgst -sha256 -sign "$CSK_KEY" | base64 -w0)

curl -sS -X POST "http://$AGENTGW:8443/eid/api/verify/request" \
  -H "content-type: application/json; charset=utf-8" \
  -H "request_id: $REQUEST_ID" -H "request_time: $REQUEST_TIME" \
  -H "license_id: $LICENSE_ID" -H "device_type: $DEVICE_TYPE" \
  -H "dia_chi: $DIA_CHI" -H "signature: $SIGNATURE" \
  --data "{\"id_card\":\"$ID_CARD\",\"dscert\":\"$DSCERT\"}"

Mẫu do người soạn wiki viết theo đặc tả, chưa chạy thử với AgentGW thật.

Lưu ý khi tích hợp

Bảo mật và nhật ký