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ục | Giá trị |
|---|---|
| Mục đích | Xác thực thẻ CCCD gắn chip qua chứng thư số trên chip |
| URL | http://<địa-chỉ-AgentGW>:8443/eid/api/verify/request |
| Method | POST |
Header
| Header | Nội dung |
|---|---|
content-type | application/json; charset=utf-8 |
request_id | Mã 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_time | yyyyMMddHHmmss, múi giờ GMT+7. Máy gửi phải đồng bộ giờ. |
license_id | Mã 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_type | Mã loại thiết bị / nền tảng do RAR cấp hoặc chấp thuận; không tự đổi. |
dia_chi | Tỉnh / thành phố thường trú ghi trên căn cước. |
signature | Chữ ký RSA-SHA256, xem Khoá CSK & chữ ký. |
Request body
| Trường | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
id_card | String | Có | 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á. |
dscert | String | Có | Chứng thư số trên chip, Base64, một dòng. Phải giống tuyệt đối chuỗi đã ký. |
authentication_location | String | Không | Địa điểm phát sinh yêu cầu, tối đa 255 ký tự, đúng thực tế. |
authentication_purpose | String | Không | Mục đích nghiệp vụ, tối đa 255 ký tự. |
authentication_source | String | Không | Nguồ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ường | Kiểu | Mô tả |
|---|---|---|
responds.responseId | String | Mã phản hồi, dùng truy vết và đối soát. |
responds.exitcode | Integer | 0 là thành công; khác 0 xem Mã lỗi. |
responds.result | Boolean | true nếu chứng thư trên chip hợp lệ và do Bộ Công an ký phát hành. |
responds.message | String | Mô tả trạng thái. |
responds.time | Integer | Thời điểm xử lý, Unix timestamp (giây). |
signature | String | Chữ 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
- Tên header có dấu gạch dưới (
request_id,license_id…). Một số proxy, ví dụ nginx ở cấu hình mặc định, bỏ qua header loại này; nếu có proxy đứng giữa ứng dụng và AgentGW thì phải bật cho qua. (Ghi chú của người soạn wiki.) dia_chicó tiếng Việt và nằm trong chuỗi ký: ký trên byte UTF-8, gửi đúng chuỗi đó.- URL trong đặc tả ghi
http://trên cổng 8443; bản kiểm thử lại gọi một địa chỉhttpscủa Sandbox. Dùng theo URL RAR cấp. - Mẫu JSON trong tài liệu gốc thiếu dấu phẩy giữa các trường; bản trên đã sửa.
Bảo mật và nhật ký
- Không ghi khoá bí mật hay toàn bộ
dscertvào nhật ký. - Nhật ký tối thiểu:
request_id, thời điểm gửi, URL đích, HTTP status,error_code/exitcode, thời gian xử lý. - Không trả chi tiết về khoá, chuỗi ký, lỗi mật mã cho người dùng cuối.