Phiên bản: 2.3.0

Lấy danh sách chứng từ

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

Mục đích

Hàm lấy thông tin danh sách chứng từ của người dùng hoặc các chứng từ được chia sẻ từ các người dùng khác trong hệ thống.

Request URL: /api/documents
HTTP method: GET
Authorize: Bearer token
Parameter: Không yêu cầu, tuy nhiên có thể thêm các tùy chọn bên dưới để thực hiện lọc hoặc tìm kiếm danh sách chứng từ.

Key	Type	Description
`status`	int	Trạng thái chứng từ: 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 -4: Đã hết hạn -3: Đã hủy -2: Đã xóa -1: Đã bị từ chối
`contractStatus`	int	Trạng thái hợp đồng: 0: Không xác định 1: Còn hiệu lực 2: Gần hết hiệu lực -2: Chưa có hiệu lực -1: Hết hiệu lực
`documentTemplateId`	int	Id mẫu chứng từ
`departmentId`	int	Id bộ phận
`documentTypeId`	int	Id loại chứng từ
`recipientIds`	Array[int]	Mảng Id người nhận
`createdByUserId`	int	Id người tạo
`batchImportId`	int	Id lô import
`createdFrom`	string	Tạo từ ngày
`createdTo`	string	Tạo đến ngày
`completedFrom`	string	Hoàn thành từ ngày
`completedTo`	string	Hoàn thành đến ngày
`customerCode`	string	Mã khách hàng
`waitToApprove`	boolean	Chờ duyệt
`waitToSignDigital`	boolean	Chờ ký số
`waitToSignDraw`	boolean	Chờ ký nháy
`contractValueFrom`	string	Giá trị hợp đồng từ
`contractValueTo`	string	Giá trị hợp đồng đến
`search`	string	Thông tin tìm kiếm theo mã chứng từ hoặc tên chứng từ
`page`	int	Số trang cần lấy dữ liệu (Mặc định hệ thống đang là 1)
`pageSize`	int	Số record dữ liệu mà hệ thống sẽ trả về sau mỗi request (Mặc định hệ thống đang là 10 record)

Mẫu request

Query param:
    page: 1
    pageSize:10
    search: FA902
Request: /api/documents?page=1&pageSize=10&search=FA902

Mẫu response body

{
    "data": {
        "items": [
            {
                "id": "fa07d61e-0fff-41a3-e618-08dad69d1b1b",
                "createdDate": "2022-12-05T15:45:47.8532528",
                "lastModifiedDate": "2022-12-05T15:46:07.5741114",
                "no": "FA902",
                "subject": "Hợp đồng FA902",
                "hasVerified": false,
                "hasSeal": false,
                "requireVerifiedUserSigning": false,
                "status": {
                    "value": 2,
                    "description": "Ready document"
                },
                "contractStatus": {
                    "value": 0,
                    "description": "Undefined"
                },
                "description": "Chứng từ thử nghiệm",
                "department": {
                    "id": 33,
                    "name": "VNPT eContract",
                    "code": "DHB",
                },
                "createdByUserId": 1163,
                "processRecipientCount": 2,
                "waitingProcess": {
                    "id": "cfa4f1cd-7db3-477d-8de7-08dad69d1b3b",
                    "createdDate": "2022-12-05T15:45:47.8532366",
                    "comId": 164,
                    "isOrder": true,
                    "orderNo": 1,
                    "pageSign": 1,
                    "position": "28,672,208,762",
                    "displayType": {
                        "value": 0,
                        "description": "0"
                    },
                    "accessPermission": {
                        "value": 2,
                        "description": "Sign draw"
                    },
                    "status": {
                        "value": 1,
                        "description": "Waiting"
                    },
                    "processedByUserId": 1163,
                    "documentId": "fa07d61e-0fff-41a3-e618-08dad69d1b1b"
                },
                "processInOrder": true,
                "isWaitToSignDraw": false,
                "isWaitToSignDigital": false,
                "isWaitToApprove": false,
                "isWaitToFillData": false,
                "isWaitToCoordinate": false,
                "isWaitToESign": false,
                "isWaitToEkyc": false,
                "isFillable": false,
                "type": {
                    "id": 1089,
                    "code": "CNCL",
                    "name": "Hợp đồng cấp nước",
                    "description": "Hợp đồng của cấp nước chợ lớn",
                    "documentCount": 1
                },
                "documentTemplate": {
                   "id": 1141,
                   "name": "Mẫu hợp đồng thuê nhà",
                   "createdDate": "2022-11-18T16:07:18.1590328",
                   "fileName": "DocTemplate.docx",
                   "downloadUrl": "{HOST}/Api/Download?token=...",
                   "pdfDownloadUrl":"{HOST}/Api/Download?token..."
                },
                "batchImport": {
                    "id": 1232,
                    "createdDate": "2022-12-05T15:45:44.199619",
                    "uploadedByUserId": 1163,
                    "numberOfRecords": 2,
                    "name": "20221205.A5BO",
                },
                "processes": [
                    {
                        "id": "cfa4f1cd-7db3-477d-8de7-08dad69d1b3b",
                        "createdDate": "2022-12-05T15:45:47.8532366",
                        "comId": 164,
                        "isOrder": true,
                        "orderNo": 1,
                        "pageSign": 1,
                        "position": "28,672,208,762",
                        "displayType": {
                            "value": 0,
                            "description": "0"
                        },
                        "accessPermission": {
                            "value": 2,
                            "description": "Sign draw"
                        },
                        "status": {
                            "value": 1,
                            "description": "Waiting"
                        },
                        "processedByUserId": 1163,
                        "documentId": "fa07d61e-0fff-41a3-e618-08dad69d1b1b"
                    }
                ],
                "histories": [
                    {
                        "createdDate": "2022-12-05T15:45:47.8532366",
                        "requestType": {
                            "value": 0,
                            "description": "Web"
                        },
                        "ipAddress": "::1",
                        "user": {
                            "id": 1163,
                            "code": "SYSADMIN",
                            "name": "Quản trị hệ thống",
                            "email": "admin@dochub.vn",
                            "comId": 164,
                            "username": "admin@dochub.vn"
                        },
                        "activity": {
                            "value": 1,
                            "description": "Create document"
                        }
                    },
                ],
                "attachments": [],
                "relatedDocuments": [],
                "messages": [],
                "file": {
                    "name": "FA902.pdf",
                    "size": 186793
                },
                "downloadUrl": "{HOST}/Api/Download?token=...",
                "isMarkStar": false,
                "isLaborContractDocument": false
            }
        ],
        "totalCount": 1,
        "pageCount": 1,
        "page": 1,
        "pageSize": 10,
        "hasNextPage": false,
        "hasPreviousPage": false
    },
    "success": true,
    "code": 0,
    "messages": []
}

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 danh sách chứng từ và thông tin phân trang (xem chi tiết bên dưới)

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

Key	Type	Description
`items`	array	Danh sách chứng từ (`Array[object]`) (xem chi tiết bên dưới)
`totalCount`	int	Tổng số bản ghi tìm thấy
`pageCount`	int	Tổng số trang
`page`	int	Trang hiện tại
`pageSize`	int	Số lượng bản ghi trên một trang
`hasNextPage`	boolean	Có trang tiếp theo hay không (true: Có, false: Không)
`hasPreviousPage`	boolean	Có trang trước đó hay không (true: Có, false: Không)

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

Danh sách chứa các đối tượng chứng từ với các thuộc tính của 1 phần tử:

Key	Type	Description
`id`	string	ID chứng từ (định dạng GUID)
`createdDate`	string	Thời gian tạo chứng từ (định dạng ISO 8601)
`lastModifiedDate`	string	Thời gian cập nhật gần nhất (định dạng ISO 8601)
`no`	string	Mã chứng từ
`subject`	string	Tiêu đề chứng từ
`hasVerified`	boolean	Trạng thái xác thực chứng từ (true: Đã xác thực, false: Chưa xác thực)
`hasSeal`	boolean	Chứng từ sẽ được chứng nhận bởi VNPT SEAL (true: Có, false: Không)
`requireVerifiedUserSigning`	boolean	Yêu cầu người ký đã xác thực danh tính (true: Bắt buộc xác thực, false: Không bắt buộc)
`status`	object	Trạng thái của chứng từ: `{"value": int, "description": string}` -4: Đã hết hạn -3: Đã hủy -2: Đã xóa -1: Đã bị từ chối 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 6: Đang trong hàng chờ 7: Đang xử lý ký tự động
`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 -2: Chưa có hiệu lực -1: Hết hiệu lực
`description`	string	Mô tả chi tiết về chứng từ
`department`	object	Thông tin phòng ban/bộ phận: `{"id": int, "name": string, "code": string}`
`createdByUserId`	int	ID người tạo chứng từ
`processRecipientCount`	int	Tổng số người tham gia xử lý chứng từ
`waitingProcess`	object	Thông tin chi tiết lượt xử lý đang chờ (xem chi tiết bên dưới)
`processInOrder`	boolean	Cấu hình xử lý tuần tự (true: Theo thứ tự, false: Song song)
`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	Cho phép điền dữ liệu vào form chứng từ (true/false)
`type`	object	Loại chứng từ: { "id": int, "code": string, "name": string, "description": string, "documentCount": int }
`documentTemplate`	object	Mẫu chứng từ sử dụng: { "id": int, "name": string, "createdDate": string, "fileName": string, "downloadUrl": string, "pdfDownloadUrl": string }
`batchImport`	object	Thông tin lô import (nếu có): { "id": int, "createdDate": string, "uploadedByUserId": int, "numberOfRecords": int, "name": string }
`processes`	array	Danh sách các lượt xử lý trong quy trình (`Array[object]`) (xem chi tiết bên dưới)
`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]`)
`messages`	array	Danh sách tin nhắn/trao đổi trong chứng từ (`Array[object]`)
`file`	object	Thông tin file chứng từ gốc: `{"name": string, "size": int}`
`downloadUrl`	string	Đường dẫn tải xuống file chứng từ
`isLaborContractDocument`	boolean	Có phải hợp đồng lao động hay không (true: Có, false: Không)

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

Danh sách chứa các đối tượng lượt xử lý trong quy trình chứng từ với các thuộc tính của 1 phần tử:

Key	Type	Description
`id`	string	ID định danh của lượt xử lý
`createdDate`	string	Thời gian tạo lượt xử lý
`comId`	int	ID công ty/đơn vị xử lý
`isOrder`	boolean	Xác định có thứ tự xử lý hay không
`orderNo`	int	Thứ tự xử lý trong quy trình
`pageSign`	int	Trang đặt khung chữ ký
`position`	string	Tọa độ vị trí đặt khung chữ ký
`displayType`	object	Kiểu hiển thị chữ ký: `{ "value": int, "description": string }`
`accessPermission`	object	Quyền xử lý chứng từ: `{"value": int, "description": string}` 1: Chỉ xem 2: Ký nháy 3: Phê duyệt 4: Ký số 5: Điền thông tin 6: Điều phối 7: Ký điện tử 8: Ký xác thực eKYC
`status`	object	Trạng thái của lượt xử lý: `{ "value": int, "description": string }` -1: Đã từ chối 1: Chờ xử lý 2: Đã xem 3: Đã ký 4: Đã phê duyệt 5: Đã điền thông tin 7: Đã điều phối 8: Đang trong hàng chờ
`processedByUserId`	int	ID của người dùng thực hiện xử lý
`documentId`	string	ID chứng từ liên quan

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
`user`	object	Thông tin người thực hiện: { "id": "ID người dùng", "code": "Mã người dùng", "name": "Tên người dùng", "email": "Email người dùng", "comId": "ID công ty", "username": "Tên tài khoả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 danh sách items:​

Chi tiết danh sách processes:​

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