Tạo chứng từ cơ bản

Ngày cập nhật: 07 tháng 07, 2026
Người cập nhật: VNPT eContract's team

---

Mô tả quy trình tạo chứng từ cơ bản khi tích hợp giữa hệ thống quản lý của đơn vị và VNPT eContract. Trong trường hợp hệ thống của khách hàng đã tạo sẵn tệp chứng từ (.docx hoặc .pdf) — việc soạn thảo và chỉnh sửa được thực hiện hoàn toàn bên ngoài VNPT eContract — đơn vị chỉ cần sử dụng tệp này và thực hiện theo quy trình xử lý như sau.

Sử dụng hướng dẫn này khi hệ thống của khách hàng chịu trách nhiệm chuẩn bị nội dung chứng từ, còn VNPT eContract chịu trách nhiệm lưu trữ chứng từ, chuyển chứng từ đến người xử lý, thu thập chữ ký/phê duyệt và trả về trạng thái xử lý.

Chuẩn bị trước khi tích hợp

Chuẩn bị các thông tin sau trước khi gọi API tạo chứng từ:

Thông tin	Mô tả
Tài khoản và token	Tài khoản API dùng để gọi hàm đăng nhập và lấy Bearer token.
Tệp chứng từ	Nội dung chứng từ cuối cùng do hệ thống khách hàng chuẩn bị. Nếu dùng API v1 tạo chứng từ, cần upload định dạng tệp được API này hỗ trợ, thường là PDF theo trang mô tả API chi tiết.
Metadata chứng từ	no, subject, typeId, departmentId, và các thông tin tùy chọn như description, customerCode, customerInformation, tệp đính kèm hoặc chứng từ liên quan.
Người tham gia quy trình	Mã người dùng của tất cả người xử lý: xem, phê duyệt, ký điện tử, ký số, ký nháy, điền dữ liệu hoặc điều phối chứng từ.
Vị trí ký	Cần chuẩn bị khi quy trình dùng vị trí ký cố định. Chuẩn bị pageSign và position theo định dạng của API cập nhật quy trình.
Cơ chế đồng bộ	Xác định hệ thống khách hàng có cần gọi API danh sách chứng từ để đồng bộ trạng thái, lịch sử và thông tin chứng từ mới nhất hay không.

Luồng quy trình

Diễn giải quy trình

• Hệ thống quản lý của đơn vị xuất ra tệp chứng từ định dạng .docx hoặc .pdf.
• Gọi hàm đăng nhập (1) để lấy access token phục vụ các bước xử lý tiếp theo.
• Gọi hàm danh sách loại chứng từ và danh sách bộ phận để lấy id loại chứng từ và id bộ phận.
• Gọi hàm tạo chứng từ (3) để khởi tạo và nhận id chứng từ (4).
• Gọi hàm cập nhật quy trình chứng từ (5) để bổ sung thông tin quy trình xử lý (gồm các bước xử lý và người thực hiện).
• Sau khi cập nhật quy trình, gọi hàm gửi quy trình chứng từ (7). Hệ thống sẽ kiểm tra quy trình, gửi thông báo cho người xử lý (8), và trả về waitingProcess chứa thông tin người xử lý tiếp theo.
• Người dùng ở từng bước của quy trình sẽ nhận thông báo qua email/SMS/ứng dụng và thực hiện xử lý chứng từ (phê duyệt, ký điện tử, ký số) (10 + 11). Hệ thống xử lý chữ ký, cập nhật trạng thái, sau đó chuyển sang người xử lý kế tiếp, lặp lại cho đến bước cuối cùng.
• Gọi hàm danh sách chứng từ để tra cứu trạng thái (15), lịch sử xử lý và các thông tin liên quan. Đơn vị có thể dùng dữ liệu này để đồng bộ ngược về hệ thống quản lý (tùy chọn).

Thứ tự API dành cho dev

Bước	API	Dữ liệu cần chuẩn bị	Kết quả cần lưu / bước tiếp theo
1	Đăng nhập	Username/password của tài khoản API.	Lưu access token và gửi dưới dạng Bearer token ở các request tiếp theo.
2	Danh sách loại chứng từ và danh sách bộ phận	Chưa cần dữ liệu chứng từ; gọi để tra cứu dữ liệu danh mục.	Lấy typeId và departmentId để tạo chứng từ.
3	Tạo chứng từ	Tệp chứng từ và metadata như no, subject, typeId, departmentId.	Lưu data.id làm ID chứng từ. Lúc này chứng từ mới được tạo, chưa gửi đến người xử lý.
4	Cập nhật quy trình chứng từ	ID chứng từ, processInOrder, fixedPosition, và processes.	Kiểm tra danh sách processes trả về trước khi gửi quy trình.
5	Gửi quy trình chứng từ	ID chứng từ.	Trạng thái chứng từ chuyển sang đang xử lý; dùng waitingProcess để xác định người đang chờ xử lý.
6	Xử lý chứng từ	waitingProcess.id, dữ liệu hành động, OTP nếu cần, vị trí ký/chữ ký nếu cần.	Nếu còn bước tiếp theo, response trả về waitingProcess mới; lặp lại đến khi hoàn tất.
7	Danh sách chứng từ	Tham số tìm kiếm/lọc như mã chứng từ, trạng thái hoặc ngày tạo.	Đồng bộ trạng thái, lịch sử và thông tin tải chứng từ về hệ thống khách hàng nếu cần.

Lưu ý quan trọng khi tích hợp

Chủ đề	Hướng dẫn
Mã chứng từ	no nên là duy nhất trong luồng tích hợp để hệ thống khách hàng đối soát dữ liệu với VNPT eContract.
Tạo và gửi chứng từ	Tạo chứng từ chỉ lưu tệp và metadata. Người xử lý chỉ nhận thông báo sau khi gọi API gửi quy trình.
waitingProcess.id	API xử lý chứng từ cần ID của bước đang chờ xử lý, không phải ID chứng từ. Lấy giá trị này từ response gửi quy trình, response xử lý, danh sách chứng từ hoặc luồng đăng nhập bằng mã xử lý.
Quy trình tuần tự	Nếu processInOrder là true, người xử lý tiếp theo chỉ xử lý được sau khi người trước hoàn tất.
Quy trình không tuần tự	Nếu processInOrder là false, nhiều người có thể xử lý song song tùy cấu hình quy trình.
Tọa độ ký	Với vị trí ký cố định, position là tọa độ khung ký và pageSign là trang ký.
Xử lý OTP	Một số hành động ký/phê duyệt cần gọi hai lần: lần đầu yêu cầu OTP, lần hai xác nhận bằng OTP nhận qua email/SMS.
Đồng bộ trạng thái	Nếu hệ thống khách hàng cần trạng thái gần thời gian thực, cần thiết kế cơ chế polling hoặc job đồng bộ theo trạng thái và mã chứng từ.

Checklist triển khai khuyến nghị

• Tạo và lưu mapping giữa ID bản ghi của hệ thống khách hàng, mã chứng từ no, và data.id của VNPT eContract.
• Kiểm tra tệp chứng từ mở được và có đúng số trang cuối cùng trước khi tính tọa độ ký.
• Kiểm tra typeId, departmentId, và toàn bộ processedByUserCode trước khi gửi quy trình.
• Lưu trạng thái chứng từ và waitingProcess mới nhất sau mỗi response gửi/xử lý/tra cứu.
• Xử lý riêng response yêu cầu OTP và response hoàn tất xử lý.
• Ghi log ID request, ID chứng từ, mã chứng từ và thông báo lỗi để hỗ trợ vận hành.

cẩn thận

• Luồng mô tả trên đã lược bỏ các tương tác giữa VNPT eContract với các hệ thống ký số, HSM, xác thực...
• Tùy vào nghiệp vụ của đơn vị mà bước Gọi xử lý chứng từ (10 - 11) sẽ thay đổi: có thể người dùng tương tác trực tiếp với VNPT eContract mà không thông qua 3rd System (trường hợp người dùng dùng web view của VNPT eContract để ký).
• Bước Gọi danh sách chứng từ (15) có thể có hoặc không, tùy vào mục đích đồng bộ dữ liệu của đơn vị.