Phiên bản: 2.3.0

Xử lý chứng từ nhiều file

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

Mục đích

Xử lý lượt quy trình gốc của chứng từ nhiều file. API xác định file thành phần cần ký bằng fileInfoId và hỗ trợ xử lý thêm các lượt quy trình liền kề.

Request URL: /v2/documents/process
HTTP method: POST
HTTP content-type: application/json
Authorize: Bearer token

Tham số

Key	Type	Bắt buộc	Mô tả
`processId`	string (GUID)	Có	ID lượt xử lý gốc. Lấy từ `waitingProcess.id` hoặc `processes[].id`.
`reason`	string	Không	Lý do xử lý, ký, phê duyệt hoặc từ chối.
`reject`	boolean	Không	`true` là từ chối chứng từ; `false` là xử lý bình thường.
`signatureDisplayMode`	int	Không	Chế độ hiển thị: `1` chỉ văn bản, `2` văn bản và hình ảnh, `3` chỉ hình ảnh.
`signatureImage`	string	Không	Hình ảnh chữ ký dạng Base64/Data URI.
`signingPage`	int	Không	Trang đặt chữ ký.
`signingPosition`	string	Không	Tọa độ ký dạng `llx,lly,urx,ury`.
`fileInfoId`	string (GUID)	Không	ID file thành phần cần ký. Lấy từ API Lấy thông tin chứng từ, ví dụ `downloadFileUrls[].id`.
`signatureText`	string	Không	Nội dung hiển thị chữ ký.
`fontSize`	int	Không	Cỡ chữ ký.
`processAllAdjacentProcesses`	boolean	Không	Xử lý toàn bộ lượt quy trình liền kề bằng giá trị đã cấu hình.
`adjacentProcesses`	Array[object]	Không	Danh sách lượt quy trình liền kề cần xử lý cùng lượt gốc.

Object `adjacentProcesses`

Key	Type	Bắt buộc	Mô tả
`processId`	string (GUID)	Có	ID lượt xử lý liền kề.
`signingPage`	int	Không	Trang ký. Nếu không truyền, hệ thống dùng giá trị đã cấu hình.
`signingPosition`	string	Không	Tọa độ ký. Nếu không truyền, hệ thống dùng giá trị đã cấu hình.
`fileInfoId`	string (GUID)	Không	ID file thành phần cần ký cho lượt xử lý liền kề này.
`signatureDisplayMode`	int	Không	Chế độ hiển thị chữ ký cho Ký nháy/Ký điện tử.
`reason`	string	Không	Lý do xử lý/ký.
`signatureImage`	string	Không	Hình ảnh chữ ký dạng Base64/Data URI.
`signatureText`	string	Không	Nội dung hiển thị chữ ký.
`fontSize`	int	Không	Cỡ chữ ký.

cẩn thận

Với chứng từ có nhiều file, cần truyền đúng fileInfoId cho từng lượt có đặt chữ ký. Nếu không, hệ thống không xác định rõ file đích cần ký.
Không nên đồng thời truyền processAllAdjacentProcesses: true và adjacentProcesses nếu chưa xác nhận hành vi của phiên bản đang triển khai. Tài liệu nguồn chưa định nghĩa độ ưu tiên.
Các trường chữ ký bắt buộc có điều kiện tùy quyền xử lý, phương thức ký, chính sách OTP và vị trí ký đã cấu hình.

Quy tắc xử lý lượt liền kề

Cấu hình	Hành vi
`processAllAdjacentProcesses: false`, không có `adjacentProcesses`	Chỉ xử lý lượt gốc.
`processAllAdjacentProcesses: false`, có `adjacentProcesses`	Xử lý lượt gốc và các lượt liền kề được liệt kê.
`processAllAdjacentProcesses: true`, không có `adjacentProcesses`	Xử lý lượt gốc và toàn bộ lượt liền kề bằng giá trị đã cấu hình.

Mẫu request

{
  "processId": "a5af6828-6470-4282-8e42-08df1d03012f",
  "reason": "Đồng ý",
  "reject": false,
  "signatureDisplayMode": 2,
  "signatureImage": "data:image/png;base64,...",
  "signingPage": 1,
  "signingPosition": "10,100,200,150",
  "fileInfoId": "c85895bd-3b1c-428e-bc72-b285ff7e5286",
  "signatureText": "Xác nhận nội dung chứng từ",
  "fontSize": 12,
  "processAllAdjacentProcesses": false,
  "adjacentProcesses": [
    {
      "processId": "d70fdf67-3fc2-4ca0-8e41-08df1d03012f",
      "reason": "Đồng ý",
      "signatureDisplayMode": 2,
      "signatureImage": "data:image/png;base64,...",
      "signingPage": 2,
      "signingPosition": "10,100,200,150",
      "fileInfoId": "64b60a44-706c-4449-a866-bc880b755599",
      "signatureText": "Xác nhận nội dung chứng từ",
      "fontSize": 12
    }
  ]
}

Mẫu response body

Response trả về thông tin chứng từ, quy trình và file thành phần sau xử lý. Mẫu dưới đây đã được rút gọn nhưng vẫn là JSON hợp lệ.

{
  "data": {
    "id": "926cbf31-644b-43e1-a6f6-a4f222ecc1d0",
    "createdDate": "2026-09-28T14:24:31.1791577",
    "lastModifiedDate": "2026-09-28T15:15:49.1999547+07:00",
    "completedDate": "2026-09-28T15:15:49.2000205+07:00",
    "no": "26.TEST.SELN.N3XP",
    "subject": "Chứng từ 26.TEST.SELN.N3XP",
    "status": {
      "value": 4,
      "description": "Completed"
    },
    "processInOrder": true,
    "processes": [
      {
        "id": "6972d59f-7826-4346-1035-08df1d2f16e6",
        "orderNo": 1,
        "reason": "Đồng ý",
        "pageSign": 1,
        "position": "325,654,505,744",
        "accessPermission": {
          "value": 2,
          "description": "Sign draw"
        },
        "status": {
          "value": 3,
          "description": "Signed"
        },
        "documentId": "926cbf31-644b-43e1-a6f6-a4f222ecc1d0",
        "fileInfoId": "297b8d9a-4b24-42af-a5bb-d3531f6bcd7c"
      }
    ],
    "downloadFileUrls": [
      {
        "id": "297b8d9a-4b24-42af-a5bb-d3531f6bcd7c",
        "fileName": "Sample1.pdf",
        "downloadUrl": "{HOST}/Api/Download?token=...",
        "orderNo": 1,
        "size": 345882
      },
      {
        "id": "64b60a44-706c-4449-a866-bc880b755599",
        "fileName": "Sample2.pdf",
        "downloadUrl": "{HOST}/Api/Download?token=...",
        "orderNo": 2,
        "size": 192524
      }
    ],
    "zipDownloadUrl": "{HOST}/Api/Download/MergeFilesZipDocument?token=...",
    "fixedPosition": false
  },
  "success": true,
  "code": 0,
  "messages": [
    "Sign document success"
  ]
}

Lưu ý response

Key	Mô tả
`data.processes[].fileInfoId`	File thành phần được xử lý bởi lượt quy trình tương ứng.
`data.downloadFileUrls`	Thông tin tải xuống của từng file thành phần.
`data.zipDownloadUrl`	URL tải toàn bộ file thành phần dưới dạng ZIP.
`data.status`	Trạng thái chứng từ sau khi xử lý.

Mục đích​

Tham số​

Object adjacentProcesses​

Quy tắc xử lý lượt liền kề​

Mẫu request​

Mẫu response body​

Lưu ý response​