Phiên bản: 2.3.0

Tạo lô chứng từ

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

Cho phép tạo lô chứng từ theo mẫu với dữ liệu đục lỗ. Quá trình tạo lô chứng từ gồm các bước sau:

Bước 1: Chuẩn bị file mẫu gồm các tham số cần đục lỗ
Bước 2: Tải file mẫu và cấu hình
Bước 3: Chuẩn bị dữ liệu để tạo lô chứng từ theo mẫu
Bước 4: Gọi API để tạo lô chứng từ theo mẫu
Bước 5: Gửi quy trình ký

Sử dụng hướng dẫn này khi hệ thống khách hàng cần tạo nhiều chứng từ có cùng cấu trúc mẫu, nhưng mỗi chứng từ có dữ liệu khác nhau như mã chứng từ, tiêu đề, người nhận, thứ tự ký và các giá trị đục lỗ trên mẫu.

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

Chuẩn bị các thông tin sau trước khi dựng request tạo lô 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 cho các request tiếp theo.
Mẫu chứng từ	Mẫu `.docx` đã được upload và cấu hình trên VNPT eContract. Cần lưu `documentTemplateId`.
Biến trong mẫu	Tên biến trong mẫu, ví dụ `{{ben_a}}`, `{{ben_b}}`, hoặc `{{#items}}`. Các tên này phải khớp với giá trị truyền trong `parameters`.
Dữ liệu danh mục	`departmentId` và `documentTypeId`, lấy từ API danh sách bộ phận và danh sách loại chứng từ.
Người nhận xử lý	Mã người dùng truyền trong `{{P.Code}}`. Cần kiểm tra người dùng tồn tại và đã cấu hình phương thức ký/phê duyệt phù hợp.
Nguồn dữ liệu tạo lô	Hệ thống khách hàng chuẩn bị một dòng dữ liệu cho mỗi chứng từ. Mỗi dòng phải có số lượng giá trị bằng đúng số lượng phần tử trong `parameters`.
Chiến lược gửi quy trình	Xác định tạo lô để kiểm tra trước, hay tạo xong sẽ gọi API gửi quy trình ngay.

Thứ tự API dành cho dev

Bước	API / thao tác	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`.
2	Upload/cấu hình mẫu chứng từ	Mẫu `.docx`, vị trí ký và cấu hình biến.	Lưu `documentTemplateId`.
3	Lấy chi tiết mẫu chứng từ	`documentTemplateId`.	Kiểm tra `fillableFields` để xác nhận tên biến.
4	Lấy bộ phận và loại chứng từ	Tham số tìm kiếm/lọc dữ liệu danh mục nếu cần.	Lưu `departmentId` và `documentTypeId`.
5	Dựng request tạo lô	`name`, các ID, `parameters`, và `rows`.	Kiểm tra độ dài từng dòng và các giá trị bắt buộc trước khi gọi API.
6	Import lô chứng từ nâng cao	JSON request body.	Lưu `data.id` làm ID lô và lưu ID chứng từ đã tạo nếu cần.
7	Kiểm tra lô đã tạo	ID lô hoặc màn hình web `/App/BatchImport`.	Kiểm tra chứng từ, dữ liệu và khung ký trước khi gửi.
8	Gửi quy trình lô chứng từ đã import	ID lô.	Chứng từ được gửi đến người nhận. Nếu nhận code `202`, cần chờ và gọi lại.
9	Theo dõi trạng thái	Danh sách lô, danh sách chứng từ hoặc webhook tùy thiết kế tích hợp.	Đồng bộ trạng thái và lỗi về hệ thống khách hàng nếu cần.

Chuẩn bị file mẫu gồm các tham số cần đục lỗ

Chuẩn bị file mẫu (định dạng .docx), gồm các tham số đục lỗ, quy tắc khai báo tên biến có dạng {{ten_bien}}. Ví dụ mẫu hợp đồng thuê nhà với các tham số:

Tải file mẫu và cấu hình

Đăng nhập vào hệ thống VNPT eContract Web và truy cập vào màn hình quản lý chứng từ /App/DocumentTemplate sau đó chọn “Tạo mới” để upload mẫu chứng từ

Sau khi thêm mới thành công, tiến hành chọn “Chỉnh sửa” để cấu hình vị trí ký và tham số

Chọn thêm vị trí ký để tiến hành thêm khung chữ ký cho người ký.

Thêm và đặt khung chữ ký vào đúng vị trí cần ký, có thể thêm nhiều khung chữ ký. Ví dụ sau thêm 2 khung chữ ký đặt ở cuối trang, với khung 1 là {{ben_a}} ký, khung 2 là {{ben_b}} ký.

Chuẩn bị dữ liệu để tạo chứng từ theo mẫu

Chuẩn bị dữ liệu request để gọi api tạo lô chứng từ theo mẫu, các thông tin cần có để tạo lô chứng từ gồm:

Tên lô chứng từ name: tên gọi dùng để phân biệt các lô chứng từ đã tạo.
Phòng ban departmentId: dùng để xác định chứng từ thuộc về phòng ban nào, phục vụ việc thống kê báo cáo.
Loại chứng từ documentTypeId: dùng để xác định loại chứng từ sẽ tạo, phục vụ việc thống kê báo cáo.
Mẫu chứng từ documentTemplateId: dùng để xác định thông tin mẫu chứng từ dùng để tạo lô.
Tham số parameters: dùng để xác định danh sách tên các tham số cần thiết phục phụ cho việc tạo chứng từ đục lỗ.
Dữ liệu từ hàng rows: dữ liệu từng hàng ứng với tham số bên trên đã khai báo, số lượng rows chính là số chứng từ tạo được.

Mỗi phần tử trong parameters được ánh xạ với giá trị cùng vị trí trong từng dòng của rows. Ví dụ, nếu parameters[1] là {{D.No}}, thì rows[n][1] là mã chứng từ của dòng n. Nếu có dòng có số lượng giá trị khác số lượng phần tử trong parameters, API sẽ không thể ánh xạ dữ liệu chính xác.

Sau đây là dữ liệu mẫu request tạo lô gồm 2 chứng từ với 2 người ký

{
    "name": "Lô chứng từ trình GĐ ký ngày 23/12/2022",
    "departmentId": 33,
    "documentTypeId": 47,
    "documentTemplateId": 1140,
    "parameters": [
        "{{D.FileName}}",
        "{{D.No}}",
        "{{D.Subject}}",
        "{{D.ExpiryDate}}",
        "{{D.Description}}",
        "{{D.IsOrder}}",
        "{{P.Code}}",
        "{{P.AccessPermission}}",
        "{{P.Code}}",
        "{{P.AccessPermission}}",
        "{{ben_a}}",
        "{{ben_b}}"
    ],
    "rows": [
        [
            "DOCUMENT_2",
            "CNCL_2",
            "Đơn đặt hàng 2",
            "",
            "Mô tả abc xyz",
            "Y",
            "baoth",
            "DR",
            "baoth",
            "D",
            "Nguyễn Văn A1",
            "Nguyễn Văn B1"
        ],
        [
            "DOCUMENT_3",
            "CNCL_3",
            "Đơn đặt hàng 3",
            "",
            "Mô tả abc xyz",
            "Y",
            "baoth",
            "DR",
            "baoth",
            "D",
            "Nguyễn Văn A2",
            "Nguyễn Văn B2"
        ]
    ]
}

Tham số parameters nên bắt đầu bằng nhóm thông tin chứng từ bên dưới. Cần truyền đúng tên và giữ thứ tự khớp với dữ liệu trong rows:

{{D.FileName}} : Tên tệp tin, chứng từ được tạo sẽ có tên theo file name đã khai báo.
{{D.No}} : Mã chứng từ, không được phép trùng, dùng cho việc tra cứu thông tin chứng từ.
{{D.Subject}} : Tiêu đề chứng từ, hiện thị ở màn hình danh sách chứng từ
{{D.ExpiryDate}} : Ngày hết hạn (định dạng dd/MM/yyyy), chứng từ sẽ tự động hủy bỏ nếu hết hạn xử lý
{{D.Description}} : Thông tin mô tả thêm, hiển thị khi xem chứng từ
{{D.IsOrder}} : Xử lý tuần tự (Y/N), dùng để xác định quy trình ký có theo thứ tự hay không. (bắt buộc)

Cặp tham số tiếp theo là thông tin về quy trình ký {{P.Code}} và {{P.AccessPermission}}. Thêm bao nhiêu cặp là sẽ tạo ra lô chứng từ với bấy nhiêu người xử lý.

{{P.Code}} : Mã người nhận, mỗi người dùng trong công ty có mã duy nhất.
{{P.AccessPermission}} : Quyền truy cập. Các giá trị thường dùng gồm V là chỉ xem, D là ký số, E là ký điện tử, EKYC là ký eKYC, DR là ký nháy, A là phê duyệt, F là điền dữ liệu, C là điều phối.

Cuối cùng là các tham số cần đục lỗ trên chứng từ, tên các tham số phải đúng với quy tắt đặt tên biến ban đầu và trùng tên với tên các tham số đã điền ở file mẫu bên trên. Ví dụ trên mẫu chứng từ có tham số với tên {{ben_a}} thì tên tham số truyền lên phải đúng là {{ben_a}}.

Quy tắc ánh xạ tham số

Quy tắc	Mô tả
Thông tin chứng từ hệ thống	Tham số bắt đầu bằng `{{D.` dùng để khai báo metadata chứng từ như tên file, mã chứng từ, tiêu đề, ngày hết hạn, mô tả và thứ tự xử lý.
Thông tin quy trình	Các cặp `{{P.Code}}` và `{{P.AccessPermission}}` lặp lại dùng để khai báo người nhận và quyền xử lý. Thêm một cặp mới để thêm một người xử lý.
Biến trong mẫu	Các tham số như `{{ben_a}}`, `{{ben_b}}` phải khớp với biến đã cấu hình trong mẫu chứng từ.
Biến dạng mảng	Dùng `{{#items}}` khi mẫu cần dữ liệu lặp. Giá trị trong row nên truyền dưới dạng chuỗi JSON khớp với cấu trúc mẫu.
Số dòng	Mỗi dòng trong `rows` tạo ra một chứng từ trong lô.
Số cột	Mỗi dòng phải có số lượng giá trị bằng đúng số lượng phần tử trong `parameters`.
Định dạng ngày	Các giá trị ngày như `{{D.ExpiryDate}}` nên dùng định dạng `dd/MM/yyyy`. Chỉ để trống khi nghiệp vụ cho phép.
Mã chứng từ	`{{D.No}}` nên là duy nhất để hệ thống khách hàng đối soát từng chứng từ đã tạo.

cẩn thận

Danh sách tham số parameters không được phép thay đổi phải truyền đúng thứ tự và quy tắc bên trên: Thông tin cơ bản -> Thông tin quy trình ký -> Thông tin đục lỗ.
Danh sách các dữ liệu rows: dữ liệu phải truyền đúng với thứ tự tham số bên trên.
Trong quy trình tuần tự, nên đặt quyền F trước D, E, EKYC và DR nếu người ký cần dữ liệu đã được điền trước khi ký.
Dùng ký tự \n trong giá trị của row khi chứng từ sinh ra cần xuống dòng.

Gọi Api để tạo lô chứng từ theo mẫu

Sử dụng API (/api/batch-imports/create-advanced) để tạo lô chứng từ theo dữ liệu mẫu chuẩn bị. Chi tiết tham khảo tại mục Hàm import lô chứng từ nâng cao.

Sau khi API trả về thành công, cần lưu các giá trị sau cho các bước tiếp theo:

Giá trị response	Mục đích sử dụng
`data.id`	ID lô dùng để gửi quy trình ký và tra cứu lô về sau.
`data.numberOfRecords`	Số chứng từ được yêu cầu tạo trong lô. Dùng để đối soát dữ liệu.
`data.documents[].id`	ID từng chứng từ được tạo. Lưu lại nếu hệ thống khách hàng cần theo dõi ở cấp chứng từ.
`data.documents[].no`	Mã chứng từ được tạo. Dùng để map ngược về dòng dữ liệu nguồn.
`data.documents[].status`	Trạng thái ban đầu của chứng từ trước khi gửi quy trình.
`data.errors`	Lỗi theo từng dòng nếu import lỗi hoặc API trả về chi tiết kiểm tra dữ liệu.

Sau khi tạo lô chứng từ thành công, có thể kiểm tra kết quả trên web thông qua địa chỉ ở /App/BatchImport.

Chọn button “Gửi quy trình” để xem thông tin chi tiết lô chứng từ đã tạo.

Bấm vào chi tiết để xem thông tin chứng từ đã tạo.

Kiểm tra thông tin chứng từ đã tạo đúng thông tin chưa, các khung chữ ký (nếu có). Chứng từ khi chưa gửi quy trình sẽ ở trạng thái “Chứng từ mới”, ở trạng thái này có thể cập nhật và chỉnh sửa thông tin nếu có sai soát (cập nhật thông qua các api hoặc cập nhật trên web).

Gửi quy trình ký

Sau khi tạo lô chứng từ thành công hệ thống sẽ trả về Id lô chứng từ đã tạo, dùng thông tin Id này để gửi quy trình ký. Chi tiết tham khảo tại Hàm gửi quy trình lô chứng từ đã import.

Lô chứng từ sau khi gửi đi thì chứng từ sẽ không thể chỉnh sửa. Nên cần kiểm tra thông tin kỹ trước khi gửi đi.

Khi lô có nhiều chứng từ, API gửi quy trình có thể trả về code 202 do hệ thống vẫn đang xử lý hoặc chuyển đổi file. Trường hợp này cần chờ một khoảng thời gian rồi gọi lại API gửi quy trình với cùng ID lô. Thời gian chờ nên phụ thuộc vào số lượng chứng từ trong lô và SLA tích hợp của khách hàng.

Checklist triển khai khuyến nghị

Kiểm tra biến trong mẫu trước khi gửi dữ liệu thật. Có thể dùng API chi tiết mẫu chứng từ hoặc màn hình cấu hình mẫu để đối chiếu parameters.
Kiểm tra mọi dòng trong rows có số lượng giá trị bằng đúng số lượng phần tử trong parameters trước khi gọi API tạo lô.
Kiểm tra các trường bắt buộc: name, departmentId, documentTypeId, documentTemplateId, {{D.No}}, {{D.Subject}}, {{D.IsOrder}}, và từng cặp người nhận.
Đảm bảo {{D.No}} là duy nhất giữa các chứng từ để tránh trùng mã chứng từ.
Lưu mapping giữa ID dòng dữ liệu nguồn, {{D.No}}, ID lô và ID chứng từ được tạo.
Kiểm tra chứng từ đã tạo trước khi gửi quy trình, đặc biệt là dữ liệu đục lỗ và khung chữ ký.
Xử lý retry khi API gửi quy trình trả về code 202.
Đồng bộ trạng thái bằng danh sách lô, danh sách chứng từ hoặc webhook tùy nhu cầu tích hợp.
Ghi log ID lô, mã chứng từ, số thứ tự dòng và thông báo lỗi API để hỗ trợ vận hành và đối soát.

Kiểm tra màn hình danh sách chứng từ sẽ thấy trạng thái toàn bộ chứng từ đã được gửi đi. Chọn button tìm kiếm để tìm kiếm danh sách lô chứng từ đã gửi

Chứng từ đã được gửi đến người nhận thành công, người nhận có thể xử lý các chứng từ đã nhận theo lô (xử lý hàng loạt).

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

Thứ tự API dành cho dev​

Chuẩn bị file mẫu gồm các tham số cần đục lỗ​

Tải file mẫu và cấu hình​

Chuẩn bị dữ liệu để tạo chứng từ theo mẫu​

Quy tắc ánh xạ tham số​

Gọi Api để tạo lô chứng từ theo mẫu​

Gửi quy trình ký​

Checklist triển khai khuyến nghị​