Import lô chứng từ nâng cao
Ngày cập nhật: 01 tháng 07, 2026
Người cập nhật: VNPT eContract's team
Mục đích
Thực hiện tạo hàng loạt chứng từ bằng mẫu chứng từ đã chuẩn bị trước đó, tham khảo Quản lý mẫu chứng từ Hoặc tải file mẫu chứng từ tại đây
- Request URL:
/api/v2/batch-imports/create-advanced - HTTP method:
POST - HTTP content-type:
application/json - Authorize:
Bearer token - Parameter:
| Key | Type | Description |
|---|---|---|
name | string | [Bắt buộc] Tên lô chứng từ |
departmentId | int | [Bắt buộc] Id bộ phận |
documentTypeId | int | [Bắt buộc] Id loại chứng từ |
documentTemplateId | int | [Bắt buộc] Id mẫu chứng từ |
parameters | List<string> | [Bắt buộc] Danh sách tham số |
rows | List<List<string>> | [Bắt buộc] Danh sách các dữ liệu |
mẹo
accessPermissionCode là các quyền truy cập xử lý chứng từ:
- 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
cẩn thận
- F luôn được xếp trước D, E, EKYC và DR trong quy trình xử lý tuần tự.
- Tham khảo biến
{{#items}}nếu bạn muốn truyền kiểu dữ liệu dạng mảng (array) - Dùng ký tự
\nđể xuống dòng (xem ví dụ ở biến{{generalTerms}}) - Độ dài các biến mặc định là 2000 ký tự
- Mỗi dòng trong
rowsphải có số lượng giá trị bằng đúng số lượng phần tử trongparameters, dữ liệu được ánh xạ theo thứ tự vị trí. - Các giá trị ngày của chứng từ như
{{D.ExpiryDate}},{{D.ValidFrom}},{{D.ValidTo}}phải đúng định dạng hợp lệdd/MM/yyyy. {{D.No}}là thông tin bắt buộc và không được trùng với mã chứng từ đã tồn tại.
Quy tắc kiểm tra dữ liệu
| Trường / quy tắc | Mô tả |
|---|---|
parameters và rows | Mỗi dòng dữ liệu phải có số lượng giá trị bằng đúng số lượng phần tử trong parameters; nếu không request sẽ lỗi. |
{{D.No}} | Mã chứng từ là bắt buộc và không được trùng với mã chứng từ đã tồn tại. |
| Các trường ngày | Giá trị ngày phải hợp lệ và dùng định dạng dd/MM/yyyy, ví dụ 22/12/2028. |
{{P.Code}} và {{P.AccessPermission}} | Người xử lý được truyền theo từng cặp lặp lại. Thêm một cặp mới để thêm người xử lý tiếp theo. |
| Biến trong mẫu chứng từ | Biến trong mẫu được ánh xạ theo đúng tên tham số và vị trí dữ liệu trong từng dòng. |
Mẫu request
{
"name": "[DEMO] Lô hợp đồng thuê nhà 02/2023",
"departmentId": 1,
"documentTypeId": 1,
"documentTemplateId": 2,
"parameters": [
"{{D.FileName}}", // Tên file
"{{D.No}}", // Bắt buộc | Mã chứng từ
"{{D.Subject}}", // Bắt buộc | Tiêu đề chứng từ
"{{D.ExpiryDate}}", // Ngày hết hạn xử lý chứng từ
"{{D.CusCode}}", // Mã khách hàng
"{{D.CusName}}", // Tên khách hàng
"{{D.ContractValue}}", // Giá trị hợp đồng
"{{D.ValidFrom}}", // Hiệu lực hợp đồng từ ngày
"{{D.ValidTo}}", // Hiệu lực hợp đồng đến ngày
"{{D.RefDocs}}", // Mã chứng từ liên quan, nhiều mã cách nhau dấu ;
"{{D.Description}}", // Mô tả của chứng từ
"{{D.IsOrder}}", // Quy trình | Xử lý tuần tự: Y, không tuần tự: N
"{{D.FixedPosition}}", // Quy trình | Cố định vị trí ký: Y, không cố định vị trí ký: N (mặc định)
"{{P.Code}}", // Quy trình | Mã người dùng xử lý chứng từ thứ 1
"{{P.AccessPermission}}", // Quy trình | Quyền truy cập người dùng thứ 1
"{{P.Code}}", // Quy trình | Mã người dùng xử lý chứng từ thứ 2
"{{P.AccessPermission}}", // Quy trình | Quyền truy cập người dùng thứ 2, thêm người xử lý bằng cặp dữ liệu {{P.Code}} và {{P.AccessPermission}}
"{{day}}", // biến được lấy từ mẫu chứng từ
"{{month}}", // biến được lấy từ mẫu chứng từ
"{{year}}", // biến được lấy từ mẫu chứng từ
"{{fullname}}", // biến được lấy từ mẫu chứng từ
"{{birthday}}", // biến được lấy từ mẫu chứng từ
"{{generalTerms}}", // biến được lấy từ mẫu chứng từ
"{{#items}}" // biến được lấy từ mẫu chứng từ
],
"rows": [
[
"nguyenvana.pdf",
"HDTN.01",
"Hợp đồng thuê nhà ông Nguyễn Văn A",
"22/12/2022",
"CustomerCode",
"Công ty TNHH ABC",
"250000000",
"22/12/2022",
"22/12/2030",
"HDTN.00",
"Nội dung mô tả hợp đồng",
"Y",
"N",
"baoth",
"DR",
"nguyenvana",
"D",
"17",
"02",
"2022",
"Nguyễn Văn A",
"15/06/2000",
"- Tuân thủ quy định về việc sử dụng trang thiết bị, máy móc, vật tư của người lao động.\n- Chấp hành quy định về trang phục, tác phong, thái độ làm việc của người lao động.\n- Chấp hành quy định về an toàn, vệ sinh lao động trong môi trường làm việc.",
"[ {\"no\": \"1\",\"name\": \"Quy trinh\",\"creator\": \"Ngo Thuy Trinh\",\"year\": \"2025\"}, {\"no\": \"2\",\"name\": \"Quy dinh\",\"creator\": \"Thuy Trinh\",\"year\": \"2020\"} ]"
],
[
"tranthuytrinh.pdf",
"HDTN.02",
"Hợp đồng thuê nhà ông Trần Thùy Trinh",
"22/12/2022",
"",
"",
"250000000",
"22/12/2022",
"22/12/2030",
"HDTN.00",
"Nội dung mô tả hợp đồng",
"Y",
"Y",
"baoth",
"DR",
"tranthuytrinh",
"D",
"20",
"02",
"2022",
"Trần Thùy Trinh",
"15/02/1990",
"- Tuân thủ quy định về bảo vệ bí mật kinh doanh, bí mật công nghệ của doanh nghiệp.\n- Chấp hành quy định về an toàn, vệ sinh lao động trong môi trường làm việc.",
"[ {\"no\": \"1\",\"name\": \"Quy trinh phong A\",\"creator\": \"Ngo Thuy Trinh\",\"year\": \"04.2025\"}, {\"no\": \"2\",\"name\": \"Quy dinh\",\"creator\": \"Thuy Trinh\",\"year\": \"2020\"} ]"
]
]
}
Mẫu response lỗi
Khi lô chứng từ được tạo nhưng có một hoặc nhiều dòng dữ liệu không hợp lệ, API trả về success: false, trạng thái lô là Error, và chi tiết lỗi theo từng dòng được trả về trong data.errors. Đây cũng là danh sách lỗi được hiển thị khi nhấn nút Lỗi tại danh sách import lô chứng từ.
{
"data": {
"id": 8820,
"createdDate": "2026-07-07T10:19:13.1868649+07:00",
"uploadedByUserId": 2060,
"numberOfRecords": 2,
"name": "1. Hợp đồng thuê mô hình tiền thuê cố định",
"status": {
"value": -1,
"description": "Error"
},
"documents": [],
"errors": [
{
"row": 1,
"message": "Document no 'HDTN.011' has already been used"
},
{
"row": 1,
"message": "Expiry date '22/12/2028s' is invalid"
},
{
"row": 2,
"message": "Document no 'HDTN.021' has already been used"
}
],
"importType": {
"value": 1,
"description": "Documents created from templates"
}
},
"success": false,
"code": 0,
"messages": [
"An error occurred while creating the document batch. Check the detailed error by clicking the [Error] button in the batch import list"
]
}
Nếu cấu trúc dòng dữ liệu không hợp lệ, API có thể từ chối request trước khi tạo lô chứng từ. Trường hợp này không có data.errors.
{
"success": false,
"code": 0,
"messages": [
"All length of row must equal length of parameter"
]
}
Bảng mô tả lỗi
| Mẫu thông báo lỗi | Nguyên nhân | Vị trí kiểm tra |
|---|---|---|
All length of row must equal length of parameter | Có ít nhất một dòng trong rows có số lượng giá trị khác số lượng phần tử trong parameters. | messages |
Document no '{value}' has already been used | Mã chứng từ đã tồn tại. | data.errors[].message |
Document no '' is invalid | Mã chứng từ bắt buộc đang bị trống hoặc không hợp lệ. | data.errors[].message |
{Tên trường} '{value}' is invalid | Giá trị của trường không hợp lệ, ví dụ giá trị ngày sai định dạng. | data.errors[].message |
row | Số thứ tự dòng phát sinh lỗi, bắt đầu từ 1. | data.errors[].row |
Mẫu response body
{
"data": {
"id": 8817,
"createdDate": "2026-07-01T09:09:03.711771+07:00",
"uploadedByUserId": 2060,
"numberOfRecords": 2,
"name": "[DEMO] Lô hợp đồng thuê nhà 02/2023",
"status": {
"value": 1,
"description": "Processing"
},
"documents": [
{
"id": "a1308132-c333-4e77-3be0-08dedbcc7d3b",
"createdDate": "2026-07-01T09:09:03.7235086+07:00",
"lastModifiedDate": "2026-07-01T09:09:03.7235082+07:00",
"expiryDate": "2028-12-22T00:00:00",
"validFrom": "2022-12-22T00:00:00",
"validTo": "2030-12-22T00:00:00",
"contractValue": 250000000,
"customerCode": "CustomerCode",
"customerInformation": "Công ty TNHH ABC",
"no": "HDTN.011",
"subject": "Hợp đồng thuê nhà ông Nguyễn Văn A",
"hasVerified": false,
"hasVerify": false,
"status": {
"value": 1,
"description": "New"
},
"contractStatus": {
"value": 1,
"description": "Contract valid"
},
"description": "Nội dung mô tả hợp đồng",
"createdByUserId": 2060,
"processRecipientCount": 2,
"waitingProcesses": [],
"processInOrder": true,
"isWaitToSignDraw": false,
"isWaitToSignDigital": false,
"isWaitToApprove": false,
"isWaitToFillData": false,
"isWaitToCoordinate": false,
"isWaitToESign": false,
"isWaitToEkyc": false,
"isFillable": false,
"batchImportId": 8817,
"processes": [
{
"id": "f85f3a42-3c39-484e-7f28-08dedbcc7d5b",
"createdDate": "2026-07-01T09:09:03.7234518+07:00",
"comId": 2211,
"isOrder": true,
"orderNo": 1,
"displayType": {
"value": 2,
"description": "Text and image"
},
"accessPermission": {
"value": 2,
"description": "Sign draw"
},
"status": {
"value": 1,
"description": "Waiting"
},
"processedByUserId": 2060,
"documentId": "a1308132-c333-4e77-3be0-08dedbcc7d3b",
"fillingItems": [],
"attachments": []
},
{
"id": "fdf3008a-7fc2-4b68-7f29-08dedbcc7d5b",
"createdDate": "2026-07-01T09:09:03.7234727+07:00",
"comId": 2211,
"isOrder": true,
"orderNo": 2,
"displayType": {
"value": 2,
"description": "Text and image"
},
"accessPermission": {
"value": 4,
"description": "Sign digital"
},
"status": {
"value": 1,
"description": "Waiting"
},
"processedByUserId": 16156,
"documentId": "a1308132-c333-4e77-3be0-08dedbcc7d3b",
"fillingItems": [],
"attachments": []
}
],
"accessibleViewProcesses": [],
"histories": [],
"attachments": [],
"relatedDocuments": [
null
],
"linkedDocuments": [],
"messages": [],
"downloadUrl": "{HOST}/Api/Download?token=DeDfL...",
"downloadOriginalUrl": "{HOST}/Api/Download?token=rM6C5...",
"downloadWatermarkMetadataUrl": "{HOST}/Api/Download?token=vfp1...",
"fillingItems": [],
"sharedUsers": [],
"isMarkStar": false,
"requiresSealSendConfirmation": false
},
{
"id": "242d03f5-42c9-4747-3be1-08dedbcc7d3b",
"createdDate": "2026-07-01T09:09:03.7235923+07:00",
"lastModifiedDate": "2026-07-01T09:09:03.7235923+07:00",
"expiryDate": "2028-12-22T00:00:00",
"validFrom": "2022-12-22T00:00:00",
"validTo": "2030-12-22T00:00:00",
"contractValue": 250000000,
"customerCode": "",
"customerInformation": "",
"no": "HDTN.021",
"subject": "Hợp đồng thuê nhà ông Trần Thùy Trinh",
"hasVerified": false,
"hasVerify": false,
"status": {
"value": 1,
"description": "New"
},
"contractStatus": {
"value": 1,
"description": "Contract valid"
},
"description": "Nội dung mô tả hợp đồng",
"createdByUserId": 2060,
"processRecipientCount": 2,
"waitingProcesses": [],
"processInOrder": true,
"isWaitToSignDraw": false,
"isWaitToSignDigital": false,
"isWaitToApprove": false,
"isWaitToFillData": false,
"isWaitToCoordinate": false,
"isWaitToESign": false,
"isWaitToEkyc": false,
"isFillable": false,
"batchImportId": 8817,
"processes": [
{
"id": "c6baab9c-51fd-4d7f-7f2a-08dedbcc7d5b",
"createdDate": "2026-07-01T09:09:03.7235639+07:00",
"comId": 2211,
"isOrder": true,
"orderNo": 1,
"displayType": {
"value": 2,
"description": "Text and image"
},
"accessPermission": {
"value": 2,
"description": "Sign draw"
},
"status": {
"value": 1,
"description": "Waiting"
},
"processedByUserId": 2060,
"documentId": "242d03f5-42c9-4747-3be1-08dedbcc7d3b",
"fillingItems": [],
"attachments": []
},
{
"id": "cb9982ee-5f27-4ba7-7f2b-08dedbcc7d5b",
"createdDate": "2026-07-01T09:09:03.7235663+07:00",
"comId": 2211,
"isOrder": true,
"orderNo": 2,
"displayType": {
"value": 2,
"description": "Text and image"
},
"accessPermission": {
"value": 4,
"description": "Sign digital"
},
"status": {
"value": 1,
"description": "Waiting"
},
"processedByUserId": 6199,
"documentId": "242d03f5-42c9-4747-3be1-08dedbcc7d3b",
"fillingItems": [],
"attachments": []
}
],
"accessibleViewProcesses": [],
"histories": [],
"attachments": [],
"relatedDocuments": [
null
],
"linkedDocuments": [],
"messages": [],
"downloadUrl": "{HOST}/Api/Download?token=Z6LgAW4...",
"downloadOriginalUrl": "{HOST}/Api/Download?token=dLnA...",
"downloadWatermarkMetadataUrl": "{HOST}/Api/Download?token=bJv6...",
"fillingItems": [],
"sharedUsers": [],
"isMarkStar": false,
"requiresSealSendConfirmation": false
}
],
"errors": [],
"importType": {
"value": 1,
"description": "Documents created from templates"
}
},
"success": true,
"code": 0,
"messages": [
"Import batch document success"
]
}