Tích hợp VNPT SmartCA qua API và SDK cho doanh nghiệp

Ngày đăng: · Cập nhật:

Máy tính phát yêu cầu ký VNPT SmartCA và điện thoại dùng để xác nhận
Máy tính của đơn vị và điện thoại của người duyệt đảm nhận hai phần việc khác nhau.

Phòng nhân sự muốn nhân viên duyệt hợp đồng ngay trong ứng dụng công ty. Trước khi chọn cách tích hợp VNPT SmartCA, đội dự án cần chốt hai việc: máy chủ nào tạo yêu cầu ký và người dùng sẽ xác nhận yêu cầu ấy ở đâu. VNPT có tài liệu cho cả cách mở ứng dụng SmartCA bằng liên kết sâu và cách đưa màn hình xác nhận vào ứng dụng đối tác bằng SDK. Quyết định này ảnh hưởng trực tiếp đến bài thử nghiệm thu.

Giao cho một người theo dõi trọn một hợp đồng thử, từ lúc gửi yêu cầu đến khi mở được đúng bản đã ký.

Ai tạo giao dịch, ai xác nhận ký?

Một lần ký có hai đầu mối. Ứng dụng quản lý hợp đồng biết hồ sơ nào đang chờ, ai được phân công ký và phiên bản nào đã được duyệt. Phía dịch vụ ký nhận yêu cầu gắn với chứng thư. Đội kỹ thuật nên vẽ đường đi của đúng một hợp đồng mẫu trước khi bàn chuyện tích hợp cả kho tài liệu.

Trong mô hình dùng API, máy chủ của đối tác có thể lấy thông tin chứng thư, yêu cầu ký và tra trạng thái giao dịch theo đặc tả VNPT. Đây là phần giao tiếp giữa các hệ thống. Riêng việc người ký nhìn thấy gì, chuyển sang ứng dụng nào rồi quay lại đâu cần thiết kế tiếp theo phương án đã chọn.

Nếu doanh nghiệp đã có ứng dụng di động và chấp nhận việc chuyển ứng dụng, tài liệu Deeplink mô tả cách mở VNPT SmartCA để người dùng thao tác. Điện thoại cần cài ứng dụng SmartCA. Chọn cách này thì bài thử phải bao gồm cả lúc người dùng quay trở lại màn hình hợp đồng, kể cả trường hợp họ đóng ứng dụng giữa chừng.

Với SDK, hãy xem luồng xác nhận ngay trên ứng dụng tích hợp. VNPT mô tả cách máy chủ tạo giao dịch rồi chuyển mã nhận được cho SDK mở đúng yêu cầu đang chờ. Khi bàn giao giữa đội máy chủ và đội di động, nên ghi đúng tên trường theo tài liệu của bộ đang sử dụng. Hai đội cùng gọi một trường là “mã hồ sơ” rất dễ hiểu nhầm.

Chuẩn bị một hồ sơ thử đi được hết luồng

Chọn một hợp đồng giả định, gắn số tham chiếu nội bộ và giữ riêng bản trước ký. Ghi ai là chủ chứng thư dùng để thử, ứng dụng nào hiển thị nội dung cho người đó và nơi dự kiến lưu bản trả về. Một đề nghị “ký thử được là xong” sẽ bỏ sót việc trả bản ký về đúng hồ sơ khi nhiều hợp đồng cùng chờ duyệt.

Trong hướng dẫn SDK Lite, VNPT tách tài khoản kết nối cấp cho ứng dụng đối tác khỏi tài khoản của người ký. Danh mục thông tin đăng ký kết nối còn có địa chỉ chuyển hướng đăng nhập và địa chỉ trả kết quả. Nên để người phụ trách hệ thống kiểm tra từng địa chỉ trong cấu hình thử nghiệm. Đừng dùng chung một bộ thông tin bàn giao cho cả môi trường thử và môi trường thật.

Nếu doanh nghiệp thuê viết ứng dụng, cần ghi rõ bên nào có thể tiếp nhận kết quả ngay cả khi người dùng đã rời màn hình. Việc này nên thống nhất trước lúc thiết kế nút ký, vì nút chỉ là chỗ bắt đầu.

Đối chiếu đúng giao dịch

Hai điện thoại thử nghiệm đặt cạnh phiếu theo dõi giao dịch ký SmartCA
Phiếu đối soát giữ dấu vết của từng lần thử trên thiết bị.

Khi máy chủ tạo yêu cầu thành công, lưu mã giao dịch cùng mã hợp đồng và phiên bản tệp. Trong luồng SDK do VNPT mô tả, trường tran_code từ phản hồi của API được truyền vào getWaitingTransaction để mở yêu cầu xác nhận. Đối tác phụ trách báo cho người dùng biết có giao dịch chờ trong luồng này. Nếu điện thoại im lặng, kiểm tra khâu gửi thông báo trước khi tạo thêm một yêu cầu ký.

Đặc tả của hãng mô tả hai đường đối soát: dịch vụ gửi kết quả về bằng webhook, hoặc máy chủ đối tác chủ động hỏi trạng thái của giao dịch đã tạo. Khi có thông báo về, tra lại giao dịch gốc rồi mới cập nhật hồ sơ. Nếu màn hình vừa hết thời gian chờ, giữ nguyên mã đang theo dõi để tra tiếp. Tạo một lượt mới lúc này sẽ khiến người duyệt có thể nhìn thấy hai yêu cầu cho cùng hợp đồng.

Nghiệm thu bằng cả lần ký dở dang

Một kịch bản nên có hai hợp đồng cùng chờ trên cùng điện thoại. Cho người thử mở hợp đồng thứ hai, duyệt nó, rồi kiểm tra hợp đồng thứ nhất vẫn chờ. Tải bản kết quả từ hệ thống quản lý và kiểm chữ ký trên chính tệp đó. Cách thử này sẽ phát hiện lỗi gắn kết quả theo người dùng mà bỏ qua tài liệu.

Trong lượt tiếp theo, cho người ký thoát ra trước khi xác nhận. Ghi lại trạng thái trên máy chủ và trên màn hình người dùng. Cuối cùng thử tình huống ứng dụng chưa kịp nhận thông báo dù giao dịch đã hoàn tất. Người vận hành cần giải thích được hồ sơ đang ở đâu chỉ bằng thông tin giao dịch, không cần yêu cầu nhân viên ký lại theo phỏng đoán.

Hướng dẫn liên quan

Câu hỏi thường gặp

Đã có kết nối API thì còn cần người ký mở ứng dụng không?

Phải xem luồng xác nhận đã chọn. Tạo được giao dịch ở máy chủ chưa chứng minh người dùng đã xác nhận hay hợp đồng đã có chữ ký.

Đối tác có phải tự gửi thông báo trong luồng SDK không?

Có, trong luồng xác nhận của SDK mà VNPT mô tả, đối tác gửi thông báo sau khi máy chủ tạo giao dịch thành công.

Ứng dụng quay về trang hợp đồng là đã ký xong chưa?

Hãy đối chiếu trạng thái theo mã giao dịch và mở bản ký trả về. Việc chuyển màn hình tự nó chưa đủ để đóng hồ sơ.

Khi cần hỗ trợ đối soát, hãy chuẩn bị mã giao dịch thử, thời điểm xảy ra và bước cuối cùng đã hoàn tất. Không gửi thông tin bí mật của tài khoản kết nối.

Rà soát ngày 20/11/2026. Căn cứ tài liệu của VNPT về Deeplink, luồng nghiệp vụ SDK, đăng ký SDK Lite và đặc tả API SmartCA dành cho đối tác.

Gọi ngay