Đặc Tả Kỹ Thuật, Thông Số Kỹ Thuật Và Thông Tin Phục Vụ Kết Nối Đến Cổng Kết Nối Dịch Vụ Chứng Thực Chữ Ký Số Công Cộng

Phan Duy Ngày đăng 22/10/2026

Mô hình kết nối, luồng ký số 17 bước, 4 API (ca_providers, get_certificate, sign, get_status), sandbox, mã lỗi và checklist tích hợp Cổng eSign NEAC.

Đặc Tả Kỹ Thuật, Thông Số Kỹ Thuật Và Thông Tin Phục Vụ Kết Nối Đến Cổng Kết Nối Dịch Vụ Chứng Thực Chữ Ký Số Công Cộng

v2.0 – Phiên bản tài liệu NEAC 2026
4 API – HTTP POST, JSON
17 bước – Luồng ký số qua Cổng
Hash – Không gửi nội dung tệp

📋 Cổng eSign NEAC là gì?

Cổng kết nối dịch vụ chứng thực chữ ký số công cộng (gọi tắt là Cổng eSign, tên miền esign.neac.gov.vn) do Trung tâm Chứng thực điện tử quốc gia (NEAC) vận hành. Cổng đóng vai trò "trạm trung chuyển": phần mềm, hệ thống thông tin có tính năng ký số (HTTT) chỉ cần tích hợp một lần với Cổng eSign là có thể gửi yêu cầu ký số từ xa đến chứng thư của nhiều tổ chức cung cấp dịch vụ chứng thực chữ ký số công cộng (CA) khác nhau.

Tài liệu "Đặc tả kỹ thuật, thông số kỹ thuật và thông tin phục vụ kết nối đến Cổng kết nối dịch vụ chứng thực chữ ký số công cộng" phiên bản 2.0 (NEAC, 2026) quy định cách kết nối theo khoản 3 Điều 8 Thông tư 15/2025/TT-BKHCN.

Luật Giao dịch điện tử số 20/2023/QH15 (22/6/2023): Luật gốc về giao dịch điện tử, chữ ký điện tử
Nghị định 23/2025/NĐ-CP (21/02/2025): Quy định về chữ ký điện tử và dịch vụ tin cậy
Thông tư 15/2025/TT-BKHCN (15/8/2025): Yêu cầu kỹ thuật đối với phần mềm ký số, phần mềm kiểm tra chữ ký số và cổng kết nối dịch vụ chứng thực chữ ký số công cộng

📄 Tài liệu đặc tả kỹ thuật kết nối Cổng eSign (phiên bản 2.0) – Trung tâm Chứng thực điện tử quốc gia (NEAC), 2026 - file Word. Tải về

🔗 Mô hình kết nối: Người dùng - HTTT - Cổng eSign - CA

Người ký dùng chứng thư chữ ký số do CA công cộng cấp và thao tác hoàn toàn trên giao diện của HTTT (phần mềm kế toán, hóa đơn, hợp đồng điện tử, cổng dịch vụ...). Yêu cầu ký đi qua Cổng eSign để được điều hướng đến đúng CA. CA xác thực người dùng qua ứng dụng trên thiết bị cá nhân, ký và trả chữ ký về Cổng eSign; Cổng ghi nhận giao dịch rồi trả chữ ký cho HTTT nhúng vào văn bản.

Mô hình kết nối giữa công dân, hệ thống thông tin, Cổng eSign NEAC và các tổ chức cung cấp dịch vụ chứng thực chữ ký số công cộng

Mô hình kết nối Cổng eSign - nguồn: tài liệu đặc tả kỹ thuật phiên bản 2.0 của NEAC

🔒 Điểm then chốt về bảo mật: HTTT chỉ gửi mã băm (hash) dạng Base64 của tệp cần ký. Cổng eSign không nhận nội dung tệp; việc gắn chữ ký vào tệp do HTTT thực hiện.

🔄 Luồng ký số 17 bước qua Cổng eSign

Chuẩn bị (bước 1-2): Người dùng tải tệp lên HTTT và bấm ký; HTTT băm tệp theo chuẩn mã băm an toàn quy định tại Thông tư 15/2025/TT-BKHCN.
Lấy chứng thư (bước 3-6): HTTT gọi Cổng eSign (xác thực bằng thông tin Cổng cấp) để lấy chứng thư; Cổng điều hướng sang CA tương ứng và trả thông tin chứng thư về HTTT.
Gửi yêu cầu ký (bước 7-9): HTTT gửi yêu cầu ký kèm mã băm Base64; Cổng trả về transaction_id và chuyển yêu cầu sang CA.
Xác thực và ký (bước 10-13): CA gửi yêu cầu xác thực về thiết bị của người ký; người ký xác nhận trên ứng dụng của CA; CA ký lên mã băm và trả chữ ký về Cổng eSign.
Nhận chữ ký và hoàn tất (bước 14-17): HTTT dùng transaction_id để lấy chữ ký Base64, gắn chữ ký vào tệp gốc và trả tệp đã ký cho người dùng theo Thông tư 15/2025/TT-BKHCN.

Sơ đồ tuần tự 17 bước quy trình ký số qua Cổng eSign NEAC giữa công dân, hệ thống thông tin, Cổng eSign và CA

Sơ đồ luồng ký số qua Cổng eSign - nguồn: tài liệu đặc tả kỹ thuật phiên bản 2.0 của NEAC

🧩 Danh sách 4 API và môi trường tích hợp

Tất cả API dùng phương thức HTTP POST, header Content-Type: application/json, dữ liệu JSON.

1 Lấy danh sách CA công cộng /signing/remotesigning/ca_providers – Tham số request chính: -; Dữ liệu trả về: -
2 Lấy chứng thư chữ ký số còn hiệu lực của người ký /signing/remotesigning/get_certificate – Tham số request chính: sp_id sp_password user_id ca_name serial_number; Dữ liệu trả về: user_certificates (cert_id, cert_data, chain_data, serial_number)
3 Gửi yêu cầu ký số lên mã hash /signing/remotesigning/sign – Tham số request chính: sp_id sp_password user_id ca_name sign_files serial_number; Dữ liệu trả về: transaction_id
4 Lấy giá trị chữ ký số /signing/remotesigning/get_status – Tham số request chính: sp_id sp_password user_id ca_name transaction_id; Dữ liệu trả về: signatures (doc_id, signature_value)

Chính thức: https://esign.neac.gov.vn
Thử nghiệm (sandbox): https://esign-sandbox.neac.gov.vn

⚙️ Tham số quan trọng và ví dụ request

✅ sp_id, sp_password: thông tin xác thực do Cổng eSign cấp cho HTTT.
✅ user_id: số CCCD hoặc mã số thuế của cá nhân, tổ chức muốn ký.
✅ ca_name: mã CA công cộng (lấy từ API 1); serial_number: số hiệu chứng thư.
✅ sign_files: danh sách tệp cần ký, mỗi tệp gồm data_to_be_signed (mã hash), doc_id, file_type (xml/json/pdf...), sign_type = hash. Ký được nhiều tệp trong một giao dịch.
✅ doc_id phải hiển thị đồng thời trên giao diện HTTT và ứng dụng của CA để người ký đối chiếu đúng tài liệu.

Ví dụ request API ký số (/signing/remotesigning/sign):

{
  "sp_id": "xxx.apps.esign.com",
  "sp_password": "xxxxxxxx-xxxxxxxxxxxx",
  "user_id": "0123456789",
  "ca_name": "xxx-ca",
  "serial_number": "5404fffeb7033fb3...",
  "sign_files": [
    {
      "data_to_be_signed": "IBo1hd0NFdejK/grSmOA0tiPfgLnpcHY5Gufa2bfdbXJFLI=",
      "doc_id": "30c-7401-2562",
      "file_type": "pdf",
      "sign_type": "hash"
    }
  ]
}

Ví dụ response API lấy chữ ký (/signing/remotesigning/get_status):

{
  "status_code": 200,
  "esign_code": 2000,
  "message": "SUCCESS",
  "data": {
    "transaction_id": "xxx-8e43-4bdf-a601-ee7a756e9aeb",
    "signatures": [
      { "doc_id": "30c-7401-2562", "signature_value": "U3TNGFftSJoDjYiClGRE5SMP..." }
    ]
  }
}

⏳ Chữ ký có thể chưa có ngay: khi người ký chưa xác nhận trên ứng dụng CA, signature_value sẽ rỗng. HTTT cần gọi lại get_status theo chu kỳ hợp lý và xử lý trường hợp người dùng từ chối (status 501, esign_code 4000).

🚦 Bảng mã status_code và esign_code

200: Gọi API thành công
400: Tài liệu không hợp lệ
401: Thông tin xác thực không hợp lệ
402: Mã hash không đúng định dạng
403: Chứng thư chữ ký số hoặc user_id không hợp lệ
404: Không tìm thấy thông tin giao dịch
405: Thông tin sp_id, sp_password không hợp lệ
500: Lỗi hệ thống
501: Ký số thất bại hoặc người dùng từ chối ký

esign_code: 2000 trong ví dụ phản hồi thành công; 4000 = người dùng từ chối ký.

✅ Checklist triển khai cho doanh nghiệp, nhà phát triển

Đăng ký kết nối với NEAC: Liên hệ Cổng eSign để được cấp sp_id, sp_password cho hệ thống của bạn; tham khảo hướng dẫn tại esign.neac.gov.vn/IntegrationGuide.
Tích hợp và kiểm thử trên sandbox: Chạy đủ 4 API trên esign-sandbox.neac.gov.vn, gồm cả các ca lỗi 401-405 và người dùng từ chối ký.
Băm tệp đúng chuẩn Thông tư 15/2025/TT-BKHCN: Chỉ gửi mã băm Base64; giữ tệp gốc trên HTTT để gắn chữ ký sau khi nhận.
Thiết kế giao diện hiển thị doc_id: Người ký phải thấy cùng một mã tài liệu trên HTTT và ứng dụng CA trước khi xác nhận.
Gắn chữ ký và trả tệp đã ký: Nhúng chữ ký vào đúng định dạng tệp (PDF, XML, JSON...) và kiểm tra lại chữ ký bằng phần mềm kiểm tra chữ ký số trước khi đưa vào vận hành.
Bảo mật thông tin xác thực: Lưu sp_id/sp_password phía máy chủ, không đặt trong ứng dụng di động hay mã JavaScript chạy trên trình duyệt.

❓ Câu hỏi thường gặp về Cổng eSign NEAC

Cổng eSign NEAC dùng để làm gì?

Cổng eSign (esign.neac.gov.vn) là cổng kết nối dịch vụ chứng thực chữ ký số công cộng do NEAC vận hành. Phần mềm tích hợp một lần với Cổng là gửi được yêu cầu ký số từ xa đến chứng thư của nhiều CA công cộng khác nhau.

Cổng eSign có nhận nội dung tài liệu cần ký không?

Không. Hệ thống thông tin chỉ gửi mã băm (hash) dạng Base64 của tệp. Cổng eSign không nhận các thông tin có trong tệp; việc gắn chữ ký vào tệp do hệ thống thông tin thực hiện.

Có bao nhiêu API kết nối Cổng eSign?

Tài liệu phiên bản 2.0 có 4 API dùng HTTP POST: lấy danh sách CA công cộng (ca_providers), lấy chứng thư (get_certificate), ký số lên mã hash (sign) và lấy thông tin chữ ký (get_status).

Môi trường thử nghiệm của Cổng eSign là gì?

Tên miền thử nghiệm là https://esign-sandbox.neac.gov.vn; tên miền chính thức là https://esign.neac.gov.vn.

Làm sao để có sp_id và sp_password?

Đây là thông tin xác thực do Cổng eSign cung cấp cho hệ thống thông tin kết nối. Doanh nghiệp, nhà phát triển liên hệ NEAC theo hướng dẫn tại esign.neac.gov.vn/IntegrationGuide để đăng ký.

Mã lỗi 501 khi ký số qua Cổng eSign nghĩa là gì?

status_code 501 nghĩa là ký số thất bại hoặc người dùng từ chối ký; esign_code 4000 cho biết người dùng từ chối ký.

📰 Văn bản pháp lý và nguồn tham khảo

Tài liệu đặc tả kỹ thuật kết nối Cổng eSign, phiên bản 2.0 (bản Word) - duypc.com
Hướng dẫn tích hợp Cổng kết nối dịch vụ chứng thực chữ ký số công cộng - esign.neac.gov.vn
Trung tâm Chứng thực điện tử quốc gia (NEAC) - rootca.gov.vn

ℹ️ Bài viết tóm tắt tài liệu đặc tả kỹ thuật phiên bản 2.0 của NEAC, mang tính tham khảo. Khi tích hợp, luôn dùng tài liệu và hướng dẫn mới nhất tại esign.neac.gov.vn/IntegrationGuide.