Phiên bản: 2.3.0

Xử lý chứng từ

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

Mục đích

Hàm thực hiện xử lý chứng từ một file theo quy trình, bao gồm 4 hình thức: Phê duyệt, Ký nháy, Ký điện tử và Ký số SmartCA. API cũng hỗ trợ xử lý các lượt xử lý liền kề cùng với lượt xử lý gốc.

Xem thêm: API Xử lý chứng từ hàng loạt

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

cẩn thận

Hàm thực hiện xử lý chứng từ cần thông tin processId (chính là waitingProcess.id/id của lượt xử lý) lấy từ API gửi quy trình chứng từ hoặc API đăng nhập bằng mã xử lý. Hàm này chỉ có tác dụng khi người dùng đã thực thi 1 trong 2 API trên trước đó và có dữ liệu về lượt xử lý (process) trả về từ response body.

Tham số xử lý quy trình liền kề

Có thể bổ sung các tham số tùy chọn sau vào request của các hình thức xử lý bên dưới:

Key	Type	Bắt buộc	Mô tả
`processAllAdjacentProcesses`	boolean	Không	Xử lý toàn bộ lượt xử lý liền kề bằng các giá trị đã cấu hình trên hệ thống.
`adjacentProcesses`	Array[object]	Không	Danh sách lượt xử lý liền kề cần xử lý cùng với lượt xử lý gốc.

Mỗi phần tử trong adjacentProcesses hỗ trợ:

Key	Type	Bắt buộc	Mô tả
`processId`	string	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.
`signatureDisplayMode`	int	Không	Chế độ hiển thị cho Ký nháy/Ký điện tử: `1` chỉ văn bản, `2` văn bản và hình ảnh, `3` chỉ hình ảnh.
`reason`	string	Không	Lý do xử lý/ký của lượt xử lý liền kề.
`signatureImage`	string	Không	Ảnh chữ ký dạng Base64/Data URI cho Ký nháy/Ký điện tử.
`signatureText`	string	Không	Nội dung hiển thị chữ ký cho Ký nháy/Ký điện tử.
`fontSize`	int	Không	Cỡ chữ ký cho Ký nháy/Ký điện tử.

Cấu hình	Hành vi
`processAllAdjacentProcesses: false`, không có `adjacentProcesses`	Chỉ xử lý lượt xử lý gốc xác định bởi `processId`.
`processAllAdjacentProcesses: false`, có `adjacentProcesses`	Xử lý lượt gốc và các lượt liền kề được khai báo cụ thể.
`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.

cẩn thận

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 giữa hai tùy chọn này.

Request mẫu xử lý quy trình liền kề

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

1. Phê duyệt (Approve)

Áp dụng cho lượt xử lý có accessPermission = 3 (Approve). Quy trình gồm 2 bước gọi API: bước 1 gửi yêu cầu để hệ thống gửi mã OTP xác nhận, bước 2 gửi lại kèm mã OTP để xác nhận phê duyệt.

Parameter

Key	Type	Description
`processId`	string	[Bắt buộc] Id lượt xử lý đang chờ (lấy từ `waitingProcess.id`/`process.id`)
`reason`	string	[Bắt buộc] Lý do phê duyệt / từ chối
`reject`	boolean	[Bắt buộc] Từ chối phê duyệt true: từ chối
`otp`	string	[Bắt buộc] Mã xác nhận OTP // Lần 1: truyền `null` // Lần 2: truyền mã OTP nhận được qua Email/SMS

Request mẫu — Lần 1

{
  "processId": "08f2f33f-1abc-4567-1a30-08def6b00923",
  "reason": "Đồng ý",
  "reject": false,
  "otp": null
}

Response mẫu — Lần 1 (Hệ thống gửi mã OTP xác nhận)

{
    "data": {
        "isBatchProcess": false,
        "isSingleProcess": false,
        "isProcessedByWorkerService": false,
        "processId": "08f2f33f-1abc-4567-1a30-08def6b00923",
        "documentId": "b0e5b86c-f4fb-42b4-9b7d-e679ce37e17a",
        "documentIds": [],
        "accessPermission": 3,
        "signMethod": 2,
        "signatureDisplayMode": 2,
        "batchProcessStatus": 0,
        "signingPage": 0,
        "reason": "Đồng ý",
        "confirmReason": "Đồng ý",
        "showReason": false,
        "fontSize": 0,
        "receiveOtpMethod": 1,
        "receiveOtpEmail": "example@gmail.com",
        "requireOtpConfirmation": true,
        "generateOtp": false,
        "vnptCaPluginAdvancedSign": false
    },
    "success": true,
    "code": 100,
    "messages": [
        "Send confirmation otp success"
    ]
}

thông tin

code: 100 và message "Send confirmation otp success" cho biết hệ thống đã gửi mã OTP đến Email/SMS của người dùng. Cần gọi lại API lần 2, giữ nguyên các tham số và bổ sung giá trị otp để hoàn tất phê duyệt.

Request mẫu — Lần 2 (Sau khi có mã OTP từ Email/SMS)

{
  "processId": "08f2f33f-1abc-4567-1a30-08def6b00923",
  "reason": "Đồng ý",
  "reject": false,
  "otp": "932230"
}

Response mẫu — Lần 2 (Phê duyệt thành công)

thông tin

Các Response đã được rút gọn

{
    "data": {
        "id": "b0e5b86c-f4fb-42b4-9b7d-e679ce37e17a",
        "createdDate": "2026-08-12T17:15:26.2252705",
        "lastModifiedDate": "2026-08-19T10:47:02.1618765+07:00",
        "completedDate": "2026-08-19T10:47:02.161878+07:00",
        "no": "26.CKDS.HR.EL49",
        "subject": "Chứng từ 26.CKDS.HR.EL49",
        "hasVerified": false,
        "hasVerify": false,
        "status": {
            "value": 4,
            "description": "Completed"
        },
        "contractStatus": {
            "value": 0,
            "description": "Undefined"
        },
        "createdByUserId": 2,
        "processRecipientCount": 1,
        "type": {
            "id": 1,
            "code": "CKDS",
            "name": "Chiết khấu doanh số",
            "description": "Chứng từ chiết khấu doanh số",
            "documentCount": 1,
            "children": []
        },
        "processes": [
            {
                "id": "08f2f33f-1abc-4567-1a30-08def6b00923",
                "createdDate": "2026-08-12T17:15:38.1856745",
                "comId": 1,
                "isOrder": true,
                "orderNo": 1,
                "reason": "Đồng ý",
                "displayType": {
                    "value": 0,
                    "description": "0"
                },
                "accessPermission": {
                    "value": 3,
                    "description": "Approve"
                },
                "status": {
                    "value": 4,
                    "description": "Approved"
                },
                "processedDate": "2026-08-19T10:47:02.1608829+07:00",
                "processedByUserId": 2,
                "documentId": "b0e5b86c-f4fb-42b4-9b7d-e679ce37e17a",
                "fillingItems": [],
                "fileInfoId": "c551a762-b4e8-4907-40ef-08def6b0091b",
                "attachments": []
            }
        ],
        "downloadUrl": "{{HOST}}/Api/Download?token=...",
        "downloadOriginalUrl": "{{HOST}}/Api/Download?token=...",
        "downloadWatermarkMetadataUrl": "{{HOST}}/Api/Download?token=...",
        "fixedPosition": false
    },
    "success": true,
    "code": 0,
    "messages": [
        "Approve document success"
    ]
}

2. Ký nháy (Sign draw)

Áp dụng cho lượt xử lý có accessPermission = 2 (Sign draw). Quy trình gồm 2 bước gọi API, tương tự Phê duyệt nhưng có thêm các tham số liên quan đến chữ ký (hình ảnh, vị trí, nội dung ký...).

Parameter

Key	Type	Description
`processId`	string	[Bắt buộc] Id lượt xử lý đang chờ (lấy từ `waitingProcess.id`/`process.id`)
`reason`	string	[Bắt buộc] Lý do ký / từ chối ký
`reject`	boolean	[Bắt buộc] Từ chối ký chứng từ true: từ chối ký chứng từ
`otp`	string	[Bắt buộc] Mã xác nhận OTP // Lần 1: truyền `null` // Lần 2: truyền mã OTP xác nhận ký/từ chối ký nhận được qua Email/SMS
`signatureDisplayMode`	int	[Bắt buộc] Chế độ hiển thị chữ ký 1: Chỉ văn bản 2: Văn bản và hình ảnh 3: Chỉ hình ảnh
`signatureImage`	string	[Bắt buộc] Hình ảnh chữ ký // chuỗi base64 của hình ảnh chữ ký
`signingPage`	int	[Bắt buộc] Số trang ký
`signingPosition`	string	[Bắt buộc] Vị trí / tọa độ ký Rectangle = `llx, lly, urx, ury` - llx, lly = tọa độ góc dưới cùng bên trái của chữ ký - urx = llx + width - ury = lly + height Gốc tọa độ là điểm dưới cùng bên trái của tài liệu
`signatureText`	string	[Bắt buộc] Nội dung ký
`fontSize`	int	[Bắt buộc] Cỡ chữ
`showReason`	boolean	[Bắt buộc] Hiển thị lý do false: không hiển thị lý do ký true: hiển thị lý do ký
`confirmTermsConditions`	boolean	[Bắt buộc] Xác nhận điều khoản pháp lý trước khi xử lý chứng từ false: không đồng ý true: đồng ý

Request mẫu — Lần 1

{
  "processId": "e3516f41-dc3f-4e04-ba61-6a658ffa1b52",
  "reason": "Đồng ý với nội dung trình ký",
  "reject": false,
  "otp": null,
  "signatureDisplayMode": 3,
  "signatureImage": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAD…",
  "signingPage": 1,
  "signingPosition": "10,110,202,200",
  "signatureText": "Signature Text",
  "fontSize": 12,
  "showReason": false,
  "confirmTermsConditions": true
}

Response mẫu — Lần 1 (Hệ thống gửi mã OTP xác nhận)

{
    "data": {
        "isBatchProcess": false,
        "isSingleProcess": false,
        "documentId": "b3db2a04-01fc-4cde-b27a-b24e26c77f86",
        "accessPermission": 2,
        "signMethod": 2,
        "signatureDisplayMode": 0,
        "batchProcessStatus": 0,
        "signingPage": 0,
        "signatureText": "Signature Text",
        "signatureImage": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAD…",
        "reason": "Đồng ý với nội dung trình ký",
        "confirmReason": "Đồng ý",
        "showReason": false,
        "fontSize": 0,
        "receiveOtpMethod": 1,
        "receiveOtpPhone": "0919XXXXXX",
        "receiveOtpEmail": "email_address",
        "requireOtpConfirmation": true,
        "vnptCaPluginAdvancedSign": false
    },
    "success": true,
    "code": 100,
    "messages": [
        "Send confirmation otp success"
    ]
}

Request mẫu — Lần 2 (Sau khi có mã OTP từ Email/SMS)

{
  "processId": "e3516f41-dc3f-4e04-ba61-6a658ffa1b52",
  "reason": "Đồng ý với nội dung trình ký",
  "reject": false,
  "otp": "089278",
  "signatureDisplayMode": 3,
  "signatureImage": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUg…",
  "signingPage": 1,
  "signingPosition": "10,110,202,200",
  "signatureText": "Signature Text",
  "fontSize": 12,
  "showReason": false,
  "confirmTermsConditions": true
}

Response mẫu — Lần 2 (Ký thành công)

Cấu trúc response giống response lần 2 của mục Phê duyệt ở trên (chi tiết chứng từ đầy đủ sau khi xử lý), riêng messages trả về:

thông tin

Các Response đã được rút gọn

{
    "data": {
        "id": "b3db2a04-01fc-4cde-b27a-b24e26c77f86",
        "createdDate": "2026-08-12T08:42:57.0910118",
        "lastModifiedDate": "2026-08-19T09:59:47.2167854+07:00",
        "completedDate": "2026-08-19T09:59:47.2169471+07:00",
        "no": "26.CKDS.HR.EL49",
        "subject": "Chứng từ 26.CKDS.HR.EL49",
        "hasVerified": false,
        "hasVerify": false,
        "status": {
            "value": 4,
            "description": "Completed"
        },
        "contractStatus": {
            "value": 0,
            "description": "Undefined"
        },
        "createdByUserId": 1,
        "processRecipientCount": 1,
        "waitingProcesses": [],
        "type": {
            "id": 1,
            "code": "CKDS",
            "name": "Chiết khấu doanh số",
            "description": "Chứng từ chiết khấu doanh số",
            "documentCount": 1,
            "children": []
        },
        "processes": [
            {
                "id": "df641313-b0d4-4020-1a2e-08def6b00923",
                "createdDate": "2026-08-12T08:42:57.1493998",
                "comId": 1,
                "isOrder": true,
                "orderNo": 1,
                "signatureText": "Xác nhận nội dung chứng từ",
                "reason": "Đồng ý",
                "pageSign": 4,
                "position": "345,190,485,250",
                "fontSize": 12,
                "displayType": {
                    "value": 2,
                    "description": "Text and image"
                },
                "signedMethod": {
                    "value": 2,
                    "description": "VNPT SmartCA"
                },
                "accessPermission": {
                    "value": 2,
                    "description": "Sign draw"
                },
                "status": {
                    "value": 3,
                    "description": "Signed"
                },
                "processedDate": "2026-08-19T09:59:47.1071048+07:00",
                "processedByUserId": 2,
                "documentId": "b3db2a04-01fc-4cde-b27a-b24e26c77f86"
            }
        ],
        "downloadUrl": "{{HOST}}/Api/Download?token=...",
        "downloadOriginalUrl": "{{HOST}}/Api/Download?token=...",
        "downloadWatermarkMetadataUrl": "{{HOST}}/Api/Download?token=...",
        "fixedPosition": false
    },
    "success": true,
    "code": 0,
    "messages": [
        "Sign document success"
    ]
}

3. Ký điện tử (E-Sign)

Áp dụng cho lượt xử lý có accessPermission = 7 (E-Sign). Tham số truyền lên, số bước gọi API (2 bước, có OTP) và cấu trúc response tương tự hoàn toàn mục Ký nháy ở trên.

Parameter

Tham số giống mục 2. Ký nháy: processId, reason, reject, otp, signatureDisplayMode, signatureImage, signingPage, signingPosition, signatureText, fontSize, showReason, confirmTermsConditions.

Request mẫu — Lần 1 và Lần 2

Tương tự mục Ký nháy: lần 1 truyền otp: null để hệ thống gửi mã OTP, lần 2 truyền lại kèm mã otp nhận được từ Email/SMS.

Response mẫu

Lần 1: code: 100, messages: ["Send confirmation otp success"] — cấu trúc data tương tự mục Ký nháy.
Lần 2 (thành công): code: 0, messages: ["Sign document success"] — cấu trúc data là chi tiết chứng từ đầy đủ sau khi xử lý (tương tự response lần 2 của mục Phê duyệt).

4. Ký số SmartCA

Áp dụng cho lượt xử lý có accessPermission liên kết với phương thức ký signMethod = 2 (VNPT Smart CA). Khác với 3 loại xử lý trên, Ký số SmartCA chỉ cần gọi API 1 lần duy nhất, không sử dụng cơ chế OTP qua Email/SMS — hệ thống sẽ gửi yêu cầu ký sang ứng dụng/dịch vụ SmartCA và chờ người dùng xác nhận ký từ phía SmartCA trước khi trả kết quả.

Parameter

Key	Type	Description
`processId`	string	[Bắt buộc] Id lượt xử lý đang chờ (lấy từ `waitingProcess.id`/`process.id`)
`reason`	string	[Bắt buộc] Lý do ký / từ chối ký
`reject`	boolean	[Bắt buộc] Từ chối ký chứng từ true: từ chối ký chứng từ
`signatureDisplayMode`	int	[Bắt buộc] Chế độ hiển thị chữ ký 1: Chỉ văn bản 2: Văn bản và hình ảnh 3: Chỉ hình ảnh
`signatureImage`	string	[Bắt buộc] Hình ảnh chữ ký // chuỗi base64 của hình ảnh chữ ký
`signingPage`	int	[Bắt buộc] Số trang ký
`signingPosition`	string	[Bắt buộc] Vị trí / tọa độ ký Rectangle = `llx, lly, urx, ury` (xem chi tiết quy tắc tính tọa độ ở mục 2. Ký nháy)
`signatureText`	string	[Bắt buộc] Nội dung ký
`fontSize`	int	[Bắt buộc] Cỡ chữ
`showReason`	boolean	[Bắt buộc] Hiển thị lý do false: không hiển thị lý do ký true: hiển thị lý do ký
`SmartCaCertId`	int	[Bắt buộc] Id chứng thư số SmartCA của người dùng dùng để ký (lấy từ `userCertificates[].id`/`defaultSmartCa.id`)
`isBusinessSmartCaAccount`	boolean	[Bắt buộc] Tài khoản SmartCA doanh nghiệp hay cá nhân true: Doanh nghiệp false: Cá nhân

Request mẫu

{
  "processId": "f17fafe8-2480-4131-b6dd-08defd9fcac4",
  "reason": "Đồng ý với nội dung trình ký",
  "reject": false,
  "signatureDisplayMode": 2,
  "signatureImage": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAD…",
  "signingPage": 1,
  "signingPosition": "334,614,474,674",
  "signatureText": "Signature Text",
  "fontSize": 12,
  "showReason": false,
  "SmartCaCertId": 3,
  "isBusinessSmartCaAccount": false
}

Response mẫu (Ký thành công)

Sau khi người dùng xác nhận ký trên ứng dụng SmartCA, API trả về kết quả với cấu trúc data là chi tiết chứng từ đầy đủ sau khi xử lý — giống với response lần 2 của mục Phê duyệt/Ký nháy, ví dụ:

thông tin

Các Response đã được rút gọn

{
    "data": {
        "id": "e3516f41-dc3f-4e04-ba61-6a658ffa1b52",
        "createdDate": "2026-08-12T08:42:57.0910118",
        "lastModifiedDate": "2026-08-19T10:37:47.8944885+07:00",
        "completedDate": "2026-08-19T10:37:47.8944888+07:00",
        "no": "26.CKDS.HR.EL49",
        "subject": "Chứng từ 26.CKDS.HR.EL49",
        "hasVerified": false,
        "hasVerify": false,
        "status": {
            "value": 4,
            "description": "Completed"
        },
        "contractStatus": {
            "value": 0,
            "description": "Undefined"
        },
        "createdByUserId": 1,
        "processRecipientCount": 2,
        "waitingProcesses": [],
        "type": {
            "id": 1,
            "code": "CKDS",
            "name": "Chiết khấu doanh số",
            "description": "Chứng từ chiết khấu doanh số",
            "documentCount": 1,
            "children": []
        },
        "processes": [
            {
                "id": "df641313-b0d4-4020-1a2e-08def6b00923",
                "createdDate": "2026-08-12T08:42:57.1493998",
                "comId": 1,
                "isOrder": true,
                "orderNo": 1,
                "signatureText": "Signature Text",
                "reason": "Đồng ý với nội dung trình ký",
                "pageSign": 1,
                "position": "334,614,474,674",
                "fontSize": 12,
                "displayType": {
                    "value": 2,
                    "description": "Text and image"
                },
                "signedMethod": {
                    "value": 2,
                    "description": "VNPT SmartCA"
                },
                "accessPermission": {
                    "value": 7,
                    "description": "E-Sign"
                },
                "status": {
                    "value": 3,
                    "description": "Signed"
                },
                "processedDate": "2026-08-19T10:11:07.1403968",
                "processedByUserId": 2,
                "documentId": "e3516f41-dc3f-4e04-ba61-6a658ffa1b52"
            }
        ],
        "fixedPosition": false
    },
    "success": true,
    "code": 0,
    "messages": [
        "Sign document success"
    ]
}

Mô tả Response Mẫu (lần 2)

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 thành công (xem chi tiết)

Các lỗi thường gặp

Message	Description
`Document process not found`	`processId` không tồn tại. Kiểm tra lại giá trị id lượt xử lý của chứng từ

Mục đích​

Tham số xử lý quy trình liền kề​

Request mẫu xử lý quy trình liền kề​

1. Phê duyệt (Approve)​

Parameter​

Request mẫu — Lần 1​

Response mẫu — Lần 1 (Hệ thống gửi mã OTP xác nhận)​

Request mẫu — Lần 2 (Sau khi có mã OTP từ Email/SMS)​

Response mẫu — Lần 2 (Phê duyệt thành công)​

2. Ký nháy (Sign draw)​

Parameter​

Request mẫu — Lần 1​

Response mẫu — Lần 1 (Hệ thống gửi mã OTP xác nhận)​

Request mẫu — Lần 2 (Sau khi có mã OTP từ Email/SMS)​

Response mẫu — Lần 2 (Ký thành công)​

3. Ký điện tử (E-Sign)​

Parameter​

Request mẫu — Lần 1 và Lần 2​

Response mẫu​

4. Ký số SmartCA​

Parameter​

Request mẫu​

Response mẫu (Ký thành công)​

Mô tả Response Mẫu (lần 2)​

Các lỗi thường gặp​

Mục đích

Tham số xử lý quy trình liền kề

Request mẫu xử lý quy trình liền kề

1. Phê duyệt (Approve)

Parameter

Request mẫu — Lần 1

Response mẫu — Lần 1 (Hệ thống gửi mã OTP xác nhận)

Request mẫu — Lần 2 (Sau khi có mã OTP từ Email/SMS)

Response mẫu — Lần 2 (Phê duyệt thành công)

2. Ký nháy (Sign draw)

Parameter

Request mẫu — Lần 1

Response mẫu — Lần 1 (Hệ thống gửi mã OTP xác nhận)

Request mẫu — Lần 2 (Sau khi có mã OTP từ Email/SMS)

Response mẫu — Lần 2 (Ký thành công)

3. Ký điện tử (E-Sign)

Parameter

Request mẫu — Lần 1 và Lần 2

Response mẫu

4. Ký số SmartCA

Parameter

Request mẫu

Response mẫu (Ký thành công)

Mô tả Response Mẫu (lần 2)

Các lỗi thường gặp