Phiên bản: 2.3.0

Tạo chứng từ nhiều file

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

Mục đích

Tạo mới một chứng từ hỗ trợ nhiều file, cho phép tải lên đồng thời nhiều file thành phần trong cùng một chứng từ. API trả về DocumentId của chứng từ và danh sách fileInfoId tương ứng với từng file đã tải lên. Các fileInfoId được sử dụng làm thông tin đầu vào khi cấu hình quy trình ký cho từng file tại API cập nhật quy trình chứng từ.

Request URL: /v2/documents/create
HTTP method: POST
HTTP content-type: multipart/form-data
Authorize: Bearer token
Parameter:

Key	Type	Bắt buộc	Description
`no`	string(40)	Có	Số/mã chứng từ
`subject`	string(200)	Có	Tiêu đề chứng từ
`description`	string(500)	Không	Mô tả chứng từ
`typeId`	int	Có	Id loại chứng từ theo danh mục hệ thống
`departmentId`	int	Có	Id phòng/ban phát hành chứng từ
`files`	array<file>	Có	Danh sách các file thành phần của chứng từ, được truyền trực tiếp trong request theo định dạng multipart/form-data. Hỗ trợ truyền nhiều file trong cùng một request
`relatedDocumentIds`	array<GUID>	Không	`DocumentId` của chứng từ đã tồn tại — dùng khi cần trích xuất/liên kết thêm file vào chứng từ đã có sẵn
`attachments`	array<file>	Không	Mảng danh sách tệp tin đính kèm theo chứng từ
`customerCode`	string(500)	Không	Mã khách hàng, được sử dụng để định danh hoặc tham chiếu khách hàng liên quan đến chứng từ
`customerInformation`	string(100)	Không	Thông tin khách hàng liên quan đến chứng từ

Mẫu request

Trường	Giá trị mẫu
`no`	DOCUMENT-MF-001
`subject`	Chứng từ nhiều file DOCUMENT-MF-001
`description`	Ví dụ khởi tạo chứng từ nhiều file
`typeId`	8950
`departmentId`	9855
`files`	[Tai-lieu-chinh.pdf, Phu-luc-01.pdf]

Mẫu response body

{
    "data": {
        "id": "f5b0c112-d357-44ce-b8a8-7cb77d3d0b9e",
        "createdDate": "2026-08-13T11:12:51.3713264+07:00",
        "lastModifiedDate": "2026-08-13T11:12:51.3714737+07:00",
        "no": "DOCUMENT-MF-001",
        "subject": "Chứng từ nhiều file DOCUMENT-MF-001",
        "hasVerified": false,
        "hasVerify": false,
        "hasSeal": false,
        "requireVerifiedUserSigning": false,
        "status": {
            "value": 1,
            "description": "New"
        },
        "contractStatus": {
            "value": 0,
            "description": "Undefined"
        },
        "description": "Ví dụ khởi tạo chứng từ nhiều file",
        "createdByUserId": 27938,
        "processRecipientCount": 0,
        "waitingProcesses": [
        ],
        "processInOrder": false,
        "isWaitToSignDraw": false,
        "isWaitToSignDigital": false,
        "isWaitToApprove": false,
        "isWaitToFillData": false,
        "isWaitToCoordinate": false,
        "isWaitToESign": false,
        "isWaitToEkyc": false,
        "isFillable": false,
        "type": {
            "id": 8950,
            "code": "DOCID",
            "name": "Chứng từ thử nghiệm",
            "documentCount": 1,
            "enableVnptSeal": false,
            "requireVerifiedUserSigning": false,
            "children": []
        },
        "processes": [],
        "accessibleViewProcesses": [],
        "histories": [
            {
                "createdDate": "2026-08-13T11:12:51.6256727+07:00",
                "requestType": {
                    "value": 0,
                    "description": "Web"
                },
                "ipAddress": "10.70.39.34",
                "activity": {
                    "value": 1,
                    "description": "Create document"
                }
            }
        ],
        "attachments": [],
        "relatedDocuments": [],
        "linkedDocuments": [],
        "messages": [],
        "fillingItems": [],
        "sharedUsers": [],
        "isMarkStar": false,
        "downloadFileUrls": [
            {
                "id": "9d2a2be2-e55e-4c17-f7ec-08def8f12485",
                "fileName": "Tai-lieu-chinh.pdf",
                "orderNo": 1,
                "size": 288288,
                "fileType": {
                    "value": 0,
                    "description": "General"
                },
                "downloadUrl": "{HOST}/api/Download?token=..."
            },
            {
                "id": "bd4421b7-9aef-4a40-f7ed-08def8f12485",
                "fileName": "Phu-luc-01.pdf",
                "orderNo": 2,
                "size": 73919,
                "fileType": {
                    "value": 0,
                    "description": "General"
                },
                "downloadUrl": "{HOST}/api/Download?token=..."
            }
        ],
        "zipDownloadUrl": "{HOST}/api/Download/MergeFilesZipDocument?token=...",
        "requiresSealSendConfirmation": false,
        "fixedPosition": false,
        "isLaborContractDocument": false
    },
    "success": true,
    "code": 0,
    "messages": [
        "Create document success"
    ]
}

Mô tả Response Body

Key	Type	Description
`success`	boolean	Trạng thái phản hồi của yêu cầu (true: Thành công, false: Thất bại)
`code`	int	Mã phản hồi từ hệ thống
`messages`	array	Danh sách thông báo hoặc lỗi trả về từ hệ thống
`data`	object	Đối tượng chứa thông tin chi tiết của chứng từ vừa tạo (xem chi tiết bên dưới)

Chi tiết dữ liệu trong `data`:

Key	Type	Description
`id`	GUID	`DocumentId` của chứng từ vừa tạo
`createdDate`	datetime	Thời điểm tạo chứng từ (định dạng ISO 8601)
`lastModifiedDate`	datetime	Thời điểm cập nhật gần nhất (định dạng ISO 8601)
`no`	string	Số/mã chứng từ (trùng giá trị `no` trong request)
`subject`	string	Tiêu đề chứng từ
`description`	string	Mô tả chứng từ
`hasVerified`	boolean	Chứng từ đã được xác thực hay chưa
`hasVerify`	boolean	Chứng từ có yêu cầu xác thực hay không
`hasSeal`	boolean	Chứng từ có yêu cầu chứng thực thông điệp (VNPT SEAL) hay không
`requireVerifiedUserSigning`	boolean	Có yêu cầu người ký phải xác thực định danh hay không
`status`	object	Trạng thái của chứng từ: `{"value": int, "description": string}` 1: Chứng từ mới 2: Sẵn sàng 3: Đang xử lý 4: Đã hoàn tất 5: Đang hiệu chỉnh -1: Đã bị từ chối -2: Đã xóa -3: Đã hủy
`contractStatus`	object	Trạng thái hiệu lực hợp đồng: `{"value": int, "description": string}` 0: Không xác định 1: Còn hiệu lực 2: Gần hết hiệu lực -1: Hết hiệu lực -2: Chưa có hiệu lực
`createdByUserId`	int	Id người tạo chứng từ
`processRecipientCount`	int	Số người tham gia xử lý quy trình
`waitingProcesses`	array	Danh sách người đang chờ xử lý (rỗng khi chứng từ chưa gửi quy trình)
`processInOrder`	boolean	Quy trình xử lý tuần tự (true) hay song song (false)
`isWaitToSignDraw`	boolean	Trạng thái đang chờ ký nháy (true/false)
`isWaitToSignDigital`	boolean	Trạng thái đang chờ ký số (true/false)
`isWaitToApprove`	boolean	Trạng thái đang chờ phê duyệt (true/false)
`isWaitToFillData`	boolean	Trạng thái đang chờ điền thông tin (true/false)
`isWaitToCoordinate`	boolean	Trạng thái đang chờ điều phối (true/false)
`isWaitToESign`	boolean	Trạng thái đang chờ ký điện tử (E-Sign) (true/false)
`isWaitToEkyc`	boolean	Trạng thái đang chờ ký xác thực eKYC (true/false)
`isFillable`	boolean	Chứng từ có cho phép điền dữ liệu (form-filling) hay không
`type`	object	Loại chứng từ (xem chi tiết bên dưới): { "id": int, "code": string, "name": string, "documentCount": int, "enableVnptSeal": boolean, "requireVerifiedUserSigning": boolean, "children": array }
`processes`	array	Danh sách bước xử lý đã cấu hình cho chứng từ (rỗng tại bước tạo mới)
`accessibleViewProcesses`	array	Danh sách người được cấp quyền xem chứng từ
`histories`	array	Lịch sử thao tác trên chứng từ (`Array[object]`) (xem chi tiết bên dưới)
`attachments`	array	Danh sách tệp đính kèm đi kèm chứng từ (`Array[object]`)
`relatedDocuments`	array	Danh sách chứng từ liên quan (`Array[object]`)
`linkedDocuments`	array	Danh sách chứng từ được liên kết (`Array[object]`)
`messages`	array<string>	Thông báo bổ sung ở cấp `data` (khác `messages` ở cấp ngoài response)
`fillingItems`	array	Danh sách trường dữ liệu cần điền (nếu chứng từ dạng biểu mẫu)
`sharedUsers`	array	Danh sách người được chia sẻ xem chứng từ
`isMarkStar`	boolean	Chứng từ có được đánh dấu sao hay không
`downloadFileUrls`	array	Danh sách file thành phần đã tải lên (`Array[object]`) (xem chi tiết bên dưới)
`zipDownloadUrl`	string	Đường dẫn tải toàn bộ file dưới dạng zip
`requiresSealSendConfirmation`	boolean	Có yêu cầu xác nhận trước khi gửi chứng thực thông điệp (VNPT SEAL) hay không
`fixedPosition`	boolean	Vị trí ký có bị cố định hay không
`isLaborContractDocument`	boolean	Chứng từ có gắn với hợp đồng lao động (`LaborContractId`) hay không

Chi tiết đối tượng `type`:

Key	Type	Description
`id`	int	Id loại chứng từ
`code`	string	Mã loại chứng từ (ví dụ: `DOCID`)
`name`	string	Tên loại chứng từ
`documentCount`	int	Số chứng từ đã tạo theo loại này
`enableVnptSeal`	boolean	Loại chứng từ có bật chứng thực thông điệp (VNPT SEAL) hay không
`requireVerifiedUserSigning`	boolean	Loại chứng từ có yêu cầu xác thực người ký hay không
`children`	array	Danh sách loại chứng từ con (nếu có)

Chi tiết danh sách `downloadFileUrls`:

Danh sách chứa các đối tượng file thành phần đã tải lên với các thuộc tính của 1 phần tử:

Key	Type	Description
`id`	GUID	`fileInfoId` của file thành phần — dùng làm đầu vào ở API Cập nhật quy trình chứng từ
`fileName`	string	Tên file
`orderNo`	int	Thứ tự file trong chứng từ
`size`	int	Kích thước file (byte)
`fileType`	object	Loại file: `{"value": int, "description": string}`
`downloadUrl`	string	Đường dẫn tải file

Chi tiết lịch sử thao tác (`histories`):

Key	Type	Description
`createdDate`	string	Thời gian thực hiện thao tác (định dạng ISO 8601)
`requestType`	object	Nguồn thực hiện request: `{"value": int, "description": string}` -1: Unspecified (Không xác định) 0: Web 1: Api 3: Service (Dịch vụ hệ thống) 4: Mobile (Ứng dụng di động)
`ipAddress`	string	Địa chỉ IP thực hiện
`activity`	object	Thao tác thực hiện: `{"value": int, "description": string}` -3: Hủy chứng từ -2: Xóa chứng từ -1: Từ chối chứng từ 1: Tạo chứng từ 2: Cập nhật chứng từ 3: Mời người nhận 4: Xem chứng từ 5: Ký chứng từ 6: Tải chứng từ

Mục đích​

Mẫu request​

Mẫu response body​

Mô tả Response Body​

Chi tiết dữ liệu trong data:​

Chi tiết đối tượng type:​

Chi tiết danh sách downloadFileUrls:​

Chi tiết lịch sử thao tác (histories):​