Nhảy tới nội dung
Phiên bản: 2.3.0

Hiệu chỉnh quy trình xử lý chứng từ

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

Mục đích​

API cho phép hiệu chỉnh quy trình xử lý của chứng từ sau khi chứng từ đã được gửi xử lý.

Khi chứng từ đã được gửi đến các bên tham gia trong quy trình, các bên thực hiện xử lý chứng từ theo thứ tự/quy trình đã thiết lập. Trong quá trình xử lý, người tạo chứng từ được phép hiệu chỉnh phần quy trình chưa thực hiện xử lý.

  • Request URL: /api/documents/adjust-process
  • HTTP method: POST
  • HTTP content-type: application/json
  • Authorize: Bearer token
  • Parameter:
KeyTypeBắt buộcMô tả
idstringCóID chứng từ cần hiệu chỉnh quy trình.
fixedPositionbooleanKhôngCấu hình cố định vị trí ký: true là cố định vị trí ký, false là không cố định vị trí ký.
processesArray[object]CóMảng thông tin người tham gia và xử lý chứng từ cần cập nhật hoặc thêm vào phần quy trình chưa xử lý.
processes.processIdstringKhôngID của process hiện có. Có giá trị: hiệu chỉnh process hiện có. Không truyền hoặc null: thêm process mới.
processes.orderNointCóSố thứ tự xử lý trong quy trình.
processes.processedByUserCodestringCóMã của người xử lý trong quy trình.
processes.accessPermissionCodestringCóMã quyền xử lý chứng từ trong quy trình.
processes.positionstringKhôngVị trí / tọa độ ký
Rectagle = 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
processes.pageSignintKhôngTrang đặt khung chữ ký. Cần truyền khi dùng vị trí ký cố định cho quyền ký.
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
  • API này dùng sau khi chứng từ đã được gửi xử lý. Nếu cần cấu hình quy trình trước khi gửi, sử dụng Cập nhật quy trình chứng từ.
  • Chỉ được hiệu chỉnh các bước quy trình chưa được xử lý.
  • processId phải thuộc chứng từ cần hiệu chỉnh. Nếu không, API sẽ trả về lỗi.
  • F luôn nên được xếp trước D, E, EKYC và DR trong quy trình xử lý tuần tự nếu người ký cần dữ liệu đã điền trước khi ký.

Mẫu request​

Hiệu chỉnh các bước chưa xử lý bằng cách thay thế/thêm người xử lý:

{
    "id": "b5b6a4e8-4a95-483b-bcc9-a0cf1038c5c1",
    "processes": [
        {
            "orderNo": 1,
            "processedByUserCode": "NVANH",
            "accessPermissionCode": "D"
        },
        {
            "orderNo": 2,
            "processedByUserCode": "NVBAS",
            "accessPermissionCode": "E"
        }
    ]
}

Hiệu chỉnh process hiện có và thêm process mới:

{
    "id": "b5b6a4e8-4a95-483b-bcc9-a0cf1038c5c1",
    "fixedPosition": true,
    "processes": [
        {
            "processId": "8629d95b-aa15-4dd2-a7e4-08dee3d99e84",
            "orderNo": 2,
            "processedByUserCode": "USER_B",
            "accessPermissionCode": "D",
            "position": "440,750,570,820",
            "pageSign": 2
        },
        {
            "orderNo": 3,
            "processedByUserCode": "USER_C",
            "accessPermissionCode": "A"
        }
    ]
}

Mẫu response body​

{
    "data": {
        "id": "b5b6a4e8-4a95-483b-bcc9-a0cf1038c5c1",
        "createdDate": "2024-07-18T13:41:21.4627228",
        "lastModifiedDate": "2026-07-17T15:09:41.6939414+07:00",
        "no": "VAT.CKDS2",
        "subject": "Chứng từ quyết toán thuế 2026",
        "status": {
            "value": 5,
            "description": "Correcting"
        },
        "createdByUserId": 6,
        "processRecipientCount": 2,
        "waitingProcesses": [],
        "processInOrder": true,
        "isWaitToSignDraw": false,
        "isWaitToSignDigital": false,
        "isWaitToApprove": false,
        "isWaitToFillData": false,
        "isWaitToCoordinate": false,
        "isWaitToESign": false,
        "isWaitToEkyc": false,
        "processes": [
            {
                "id": "8629d95b-aa15-4dd2-a7e4-08dee3d99e84",
                "createdDate": "2026-07-17T15:09:41.6939379+07:00",
                "comId": 164,
                "isOrder": true,
                "orderNo": 2,
                "accessPermission": {
                    "value": 4,
                    "description": "Sign digital"
                },
                "status": {
                    "value": 1,
                    "description": "Waiting"
                },
                "processedByUserId": 6,
                "documentId": "b5b6a4e8-4a95-483b-bcc9-a0cf1038c5c1",
                "fillingItems": [],
                "attachments": []
            },
            {
                "id": "eba513b5-eb51-4314-a7e5-08dee3d99e84",
                "createdDate": "2026-07-17T15:09:41.6939402+07:00",
                "comId": 164,
                "isOrder": true,
                "orderNo": 2,
                "accessPermission": {
                    "value": 7,
                    "description": "E-Sign"
                },
                "status": {
                    "value": 1,
                    "description": "Waiting"
                },
                "processedByUserId": 2341,
                "documentId": "b5b6a4e8-4a95-483b-bcc9-a0cf1038c5c1",
                "fillingItems": [],
                "attachments": []
            }
        ],
        "messages": [],
        "file": {
            "name": "vat2026.pdf",
            "size": 777261
        },
        "downloadUrl": "{HOST}/Api/Download?token=F42Mxflf",
        "downloadOriginalUrl": "{HOST}/Api/Download?token=yDmW286I",
        "downloadWatermarkMetadataUrl": "{HOST}/Api/Download?token=tmvuA",
        "fixedPosition": false
    },
    "success": true,
    "code": 0,
    "messages": [
        "Update document success"
    ]
}

Mẫu response lỗi​

Process ID không thuộc chứng từ:

{
    "success": false,
    "code": 0,
    "messages": [
        "Process with Id '3a60b176-0f71-41af-4f2b-08ded1c2cf74, 64db826c-5ddf-4c02-4f2c-08ded1c2cf74' not found in the document"
    ]
}

Mã người xử lý không tồn tại:

{
    "success": false,
    "code": 0,
    "messages": [
        "User code 'USER_B3' not found"
    ]
}

Bảng mô tả lỗi​

Mẫu thông báo lỗiNguyên nhânCách xử lý
Process with Id '{ids}' not found in the documentMột hoặc nhiều processId không thuộc chứng từ cần hiệu chỉnh.Kiểm tra lại processes[].id hiện tại của chứng từ trước khi hiệu chỉnh.
User code '{code}' not foundprocessedByUserCode không tồn tại hoặc không khả dụng trong công ty.Kiểm tra lại mã người xử lý và trạng thái người dùng.
Cập nhật lần cuối vào bởi NghiepPV