PerPro API Documentation
MBGW Integration (Version20260825171306)

Quy trình Phê duyệt Tờ trình & Mobile Gateway

Tài liệu hướng dẫn tích hợp các API quy trình phê duyệt thông qua Mobile Gateway Transaction Codes (MBGW TranCode) dành cho Website Client và ứng dụng di động.

6 MBGW APIs PP_PROPOSAL_* TranCodes
2 Nhóm API Hộp thư & Quy trình phê duyệt
8 Actions Thao tác Phê duyệt & Review
PER_PRO MBGW Integration System

1. Danh sách Phê duyệt & Review

POST /api/v1/private/proposal-review-inbox/list TranCode: PP_PROPOSAL_CHECK_LIST — Lấy danh sách tờ trình phê duyệt/review PerPro theo 4 tab nghiệp vụ
Inbox
Lấy danh sách các tờ trình cần phê duyệt hoặc review của user hiện tại, phân chia theo 4 tab nghiệp vụ (PENDING_APPROVAL, PENDING_REVIEW, DELEGATED, PROCESSED).
Mỗi request sẽ trả về danh sách tờ trình và tổng số bản ghi (pagination.totalItems) của tab tương ứng, cho phép Client tải song song các tab độc lập một cách tối ưu.

Quy tắc kiểm tra & Ràng buộc nghiệp vụ (Validation Rules)

1. Phân quyền & Xác thực truy cập
  • Bắt buộc truyền Access Token qua Header (Authorization: Bearer <token>).
  • Quyền IAM yêu cầu: User phải có ít nhất 1 trong 3 quyền: PROPOSAL.APPROVE, PROPOSAL.REVIEW hoặc PROPOSAL.CREATE.
  • Người thực hiện (Actor) được trích xuất tự động từ Access Token của phiên đăng nhập (Client không cần truyền thêm thông tin user định danh trong payload).
2. Ý nghĩa của 4 Filter Tab
  • PENDING_APPROVAL: Mọi step APPROVE gán trực tiếp cho actor, chưa PROCESSED và chưa soft-delete.
  • PENDING_REVIEW: Mọi step REVIEW gán trực tiếp cho actor, chưa PROCESSED và chưa soft-delete.
  • DELEGATED: Mọi step chưa PROCESSED, chưa soft-delete có mapping uỷ quyền của actor đang ACTIVE, chưa revoke và chưa hết validTo.
  • PROCESSED: Mỗi proposal xuất hiện đúng 1 lần khi có step PROCESSED được actor hiện tại hoàn tất (approval_step.updated_by là email actor).
  • Trường canProcess: Ba filter công việc (PENDING_APPROVAL, PENDING_REVIEW, DELEGATED) trả theo từng step, do đó cùng 1 proposal có thể xuất hiện nhiều dòng khi actor có nhiều step liên quan; canProcess chỉ bằng true khi stepStatus = PROCESSING. Filter PROCESSED trả mỗi proposal 1 dòng và luôn có canProcess = false.

Mô tả Payload (Request)

Field Type Description
filter String Required Tab cần lọc: PENDING_APPROVAL, PENDING_REVIEW, DELEGATED, PROCESSED.
keyword String Optional Từ khóa tìm kiếm không phân biệt hoa thường trên Số tờ trình (number) và Trích yếu (subjectMatter).
currentPage Integer Optional Trang hiện tại (mặc định: 1, số bản ghi mỗi trang cố định perPage = 10).

Request Sample

JSON - Request Body 
{
    "filter": "PENDING_APPROVAL",
    "keyword": "0045/2026",
    "currentPage": 1
}

Response Sample (Thành công 200 OK)

JSON - Response 200 OK 
{
    "success": true,
    "code": "200",
    "message": "Lấy danh sách phê duyệt/review thành công.",
    "data": {
        "items": [
            {
                "proposalId": 45,
                "stepId": 120,
                "number": "0045/2026/TT",
                "subjectMatter": "Rà soát chi phí hạ tầng máy chủ",
                "proposalStatus": "UNDER_APPROVAL",
                "stepType": "APPROVE",
                "stepStatus": "PROCESSING",
                "stepResult": null,
                "assigneeEmail": "checker@example.com",
                "assigneeName": "Người duyệt",
                "isDelegated": false,
                "canProcess": true,
                "updatedAt": "2026-08-24T08:30:00+07:00"
            }
        ],
        "pagination": {
            "currentPage": 1,
            "perPage": 10,
            "totalItems": 1,
            "totalPages": 1,
            "hasNext": false,
            "hasPrev": false
        }
    }
}

2. Quy trình Phê duyệt & Thao tác

POST /api/v1/private/proposal-approvals/available-actions TranCode: PP_PROPOSAL_APPROVALS_AVAILABLE_ACTIONS — Lấy quy trình và thao tác phê duyệt khả dụng PerPro
Core
Lấy thông tin toàn bộ quy trình phê duyệt của tờ trình (dạng cây gồm các bước gốc steps và bước con childSteps), danh sách các bước đang chờ xử lý (currentSteps) và các hành động mà người dùng hiện tại được phép bấm (currentUserAllowedActions).

Quy tắc kiểm tra & Ràng buộc nghiệp vụ (Validation Rules)

1. Xác thực người gọi (Actor & Resource-Level Policy)
  • Bắt buộc truyền Access Token qua Header (Authorization: Bearer <token>).
  • Kiểm tra quyền truy cập: User đang đăng nhập phải có liên quan tới tờ trình mới được phép xem:
    • Là người tạo tờ trình (createdBy) hoặc người lập tờ trình (makerEmail).
    • Là người đồng trình trong danh sách (coRequesters).
    • Là người được phân công xử lý (assignee) của ít nhất một bước active trong quy trình.
    • Là người nhận ủy quyền còn hiệu lực (delegatedApprover) của ít nhất một bước trong quy trình.
Nếu user không thuộc bất kỳ vai trò nào trên, hệ thống sẽ trả về mã lỗi 403 Forbidden.
2. Cấu trúc Linked List & Kiểm tra xung đột đa bước
  • steps chỉ chứa các bước gốc theo đúng thứ tự prevStepId / nextStepId. Mỗi bước gốc có mảng childSteps chứa các bước review con.
  • currentSteps luôn là danh sách toàn bộ các bước PROCESSING. Nhiều bước processing chỉ hợp lệ khi tất cả là REVIEW và có cùng parentStepId.
  • Nếu cùng một User (hoặc người được ủy quyền) được giao xử lý nhiều hơn 1 bước PROCESSING cùng lúc trong cùng tờ trình, API trả về lỗi 409 Conflict (do payload perform-action không truyền stepId).

Mô tả Payload (Request)

Field Type Description
proposalId Integer Required ID của tờ trình cần lấy thông tin quy trình. Phải là số nguyên dương (>= 1).

Request Sample

JSON - Request Body 
{
    "proposalId": 123
}

Response Sample (Thành công 200 OK)

JSON - Response 200 OK 
{
    "success": true,
    "code": "200",
    "message": "Lấy thông tin quy trình và hành động được phép thành công.",
    "data": {
        "proposalId": 123,
        "proposalStatus": "UNDER_APPROVAL",
        "workflowCompleted": false,
        "requesterPermissions": [
            { "permission": "PROPOSAL.CREATE", "granted": true },
            { "permission": "PROPOSAL.APPROVE", "granted": true },
            { "permission": "PROPOSAL.REVIEW", "granted": false }
        ],
        "steps": [
            {
                "stepId": 1,
                "proposalId": 123,
                "nextStepId": 2,
                "prevStepId": null,
                "parentStepId": null,
                "stepType": "APPROVE",
                "status": "PROCESSED",
                "result": "APPROVED",
                "note": "Đồng ý phê duyệt",
                "assignee": {
                    "email": "user1@example.com",
                    "name": "Nguyễn Văn A",
                    "title": "Trưởng phòng",
                    "department": "Phòng IT",
                    "company": "Công ty ABC"
                },
                "delegatedApprover": null,
                "isCurrent": false,
                "isAssignedToRequester": false,
                "createdAt": "2026-08-24T08:00:00+07:00",
                "createdBy": "creator@example.com",
                "updatedAt": "2026-08-24T09:00:00+07:00",
                "updatedBy": "user1@example.com",
                "childSteps": []
            },
            {
                "stepId": 2,
                "proposalId": 123,
                "nextStepId": null,
                "prevStepId": 1,
                "parentStepId": null,
                "stepType": "APPROVE",
                "status": "PROCESSING",
                "result": null,
                "note": null,
                "assignee": {
                    "email": "user2@example.com",
                    "name": "Trần Thị B",
                    "title": "Phó Giám đốc",
                    "department": "Khối Vận hành",
                    "company": "Công ty ABC"
                },
                "delegatedApprover": null,
                "isCurrent": true,
                "isAssignedToRequester": true,
                "createdAt": "2026-08-24T08:00:00+07:00",
                "createdBy": "creator@example.com",
                "updatedAt": "2026-08-24T09:00:00+07:00",
                "updatedBy": "user1@example.com",
                "childSteps": []
            }
        ],
        "currentSteps": [
            {
                "stepId": 2,
                "proposalId": 123,
                "stepType": "APPROVE",
                "status": "PROCESSING",
                "result": null,
                "note": null,
                "assignee": {
                    "email": "user2@example.com",
                    "name": "Trần Thị B",
                    "title": "Phó Giám đốc",
                    "department": "Khối Vận hành",
                    "company": "Công ty ABC"
                },
                "delegatedApprover": null,
                "isCurrent": true,
                "isAssignedToRequester": true,
                "requiredPermission": "PROPOSAL.APPROVE",
                "currentUserAllowedActions": [
                    "approve",
                    "reject",
                    "need_rework",
                    "need_review",
                    "need_checker",
                    "delegate_approver"
                ],
                "createdAt": "2026-08-24T08:00:00+07:00",
                "createdBy": "creator@example.com",
                "updatedAt": "2026-08-24T09:00:00+07:00",
                "updatedBy": "user1@example.com"
            }
        ]
    }
}
POST /api/v1/private/proposal-approvals/eligible-reviewers TranCode: PP_PROPOSAL_APPROVALS_ELIGIBLE_REVIEWERS — Lấy danh sách reviewer hợp lệ PerPro từ IAM
Core
Lấy danh sách tất cả các tài khoản có quyền PROPOSAL.REVIEW trên hệ thống IAM để phục vụ chức năng yêu cầu thêm người thẩm định (action need_review) trên màn hình phê duyệt.

Quy tắc kiểm tra & Ràng buộc nghiệp vụ

1. Quyền IAM yêu cầu & Xác thực
  • Bắt buộc truyền Access Token qua Header (Authorization: Bearer <token>).
  • Quyền IAM yêu cầu: User gọi API bắt buộc phải có quyền PERMISSION:PROPOSAL:APPROVE. Nếu thiếu quyền sẽ bị từ chối với mã lỗi 403 Forbidden.
2. Cơ chế lọc & Sắp xếp danh sách
  • Hệ thống sẽ lấy danh sách các user có quyền REVIEW đối với module phê duyệt tờ trình.
  • Loại bỏ chính người gọi: Tự động lọc bỏ email của User đang đăng nhập khỏi danh sách kết quả.
  • Sắp xếp: Danh sách trả về được sắp xếp theo thứ tự bảng chữ cái dựa trên Tên người dùng (hoặc Email).

Mô tả Payload (Request)

API này không yêu cầu tham số payload trong body (truyền JSON rỗng {} hoặc body trống).

Request Sample

JSON - Request Body 
{}

Response Sample (Thành công 200 OK)

JSON - Response 200 OK 
{
    "success": true,
    "code": "200",
    "message": "Lấy danh sách reviewer hợp lệ thành công.",
    "data": {
        "items": [
            {
                "email": "reviewer1@example.com",
                "name": "Đặng Thị Thảo",
                "title": "Chuyên viên Thẩm định Rủi ro",
                "department": "Ban Thẩm định",
                "company": "Công ty ABC"
            },
            {
                "email": "reviewer2@example.com",
                "name": "Nguyễn Văn Hùng",
                "title": "Trưởng nhóm Pháp chế",
                "department": "Phòng Pháp chế",
                "company": "Công ty ABC"
            }
        ]
    }
}
POST /api/v1/private/proposal-approvals/perform-action TranCode: PP_PROPOSAL_APPROVALS_PERFORM_ACTION — Thực hiện thao tác phê duyệt/review PerPro (8 actions + noteTmp)
Core
Thực hiện hành động phê duyệt trên bước hiện tại của tờ trình. Hỗ trợ 8 hành động: approve, reject, need_rework, need_review, need_checker, reviewed, documents_request, delegate_approver.
Đồng thời hỗ trợ cơ chế nối thêm ghi chú tự động gắn timestamp UTC+7 (data.noteTmp) cho bất kỳ hành động nào.

Quy tắc kiểm tra & Ràng buộc nghiệp vụ (Validation Rules)

1. Quy tắc chung & Cơ chế Khóa đồng thời (Pessimistic Lock)
  • proposalId: Bắt buộc là số nguyên dương.
  • action: Bắt buộc là 1 trong 8 hành động được hỗ trợ: approve, reject, need_rework, need_review, need_checker, reviewed, documents_request, delegate_approver.
  • Bước hiện tại: Tờ trình phải có bước đang ở trạng thái PROCESSING và chưa có kết quả (result == null). User phải là effective assignee (hoặc người nhận ủy quyền hợp lệ).
  • Cơ chế chống xung đột: Hệ thống đảm bảo tính đồng bộ dữ liệu. Nếu bước phê duyệt đã bị một người dùng khác xử lý trước đó, API sẽ trả về lỗi 409 Conflict.
2. Cơ chế ghi chú bổ sung (noteTmp)
  • Mọi action đều có thể truyền kèm object data chứa noteTmp để nối thêm ghi chú vào bước hiện tại.
  • Format tự động: Backend lấy thời gian server (UTC+7) và nối vào cuối cột note theo định dạng: [YYYY-MM-DD HH:mm] - <noteTmp> (tự động xuống dòng nếu note cũ đã có nội dung).
  • Phân tách 2 loại note đối với need_review và need_checker:
    • noteTmp: Ghi chú nối thêm vào bước phê duyệt hiện tại.
    • note: Ghi chú khởi tạo giao cho reviewer/checker mới được thêm vào.
  • Tổng độ dài note sau khi nối không vượt quá 65535 ký tự.
3. Quy tắc cho các hành động bước APPROVE (approve, reject, need_rework)
  • Quyền IAM: User bắt buộc phải có quyền PERMISSION:PROPOSAL:APPROVE.
  • Trạng thái tờ trình: Bắt buộc phải là UNDER_APPROVAL.
  • Kiểm tra người nhận ủy quyền: Khi người nhận ủy quyền thực hiện phê duyệt, hệ thống sẽ kiểm tra lại hiệu lực của việc ủy quyền. Nếu quyền đã bị thu hồi hoặc xóa, request sẽ bị từ chối với lỗi 403.
Quy tắc chống tự phê duyệt (Chặn tuyệt đối): Người tạo tờ trình (createdBy) KHÔNG ĐƯỢC PHÉP thực hiện phê duyệt (approve) tờ trình của chính mình. Vi phạm sẽ bị trả về mã lỗi 01.
4. Quy tắc cho hành động "need_review" & "need_checker"
  • need_review: Chèn 1 root step REVIEW mới ngay TRƯỚC bước Approve hiện tại, chuyển step Review sang PROCESSING, khóa step Approve sang LOCKED và đưa proposal về PENDING_REVIEW. Reviewer phải có quyền PROPOSAL.REVIEW trong IAM.
  • need_checker: Chèn 1 root step APPROVE mới ngay TRƯỚC bước hiện tại, chuyển step mới sang PROCESSING, step hiện tại sang LOCKED; proposal giữ nguyên UNDER_APPROVAL. Checker phải có quyền PROPOSAL.APPROVE trong IAM và KHÔNG ĐƯỢC là người tạo tờ trình.
5. Quy tắc cho hành động "delegate_approver" (Ủy quyền)
  • Chỉ assignee gốc của bước APPROVE/PROCESSING mới được ủy quyền. Người nhận ủy quyền không được ủy quyền tiếp.
  • Người nhận ủy quyền phải nằm trong danh bạ perpro_delegation_recipient của actor, có quyền PROPOSAL.APPROVE trong IAM và KHÔNG ĐƯỢC là người tạo tờ trình.
  • Thiết lập ủy quyền thành công sẽ không làm thay đổi trạng thái của bước phê duyệt hiện tại.

Mô tả Payload (Request)

Field Type Description
proposalId Integer Required ID của tờ trình. Phải là số nguyên dương.
action String Required Loại hành động: approve, reject, need_rework, need_review, need_checker, reviewed, documents_request, delegate_approver.
data Object Conditional Đối tượng dữ liệu đính kèm. Bắt buộc truyền khi action là need_review, need_checker hoặc delegate_approver. Tùy chọn truyền khi muốn gửi noteTmp cho các action khác.

Request Sample 1: Action approve (Phê duyệt)

JSON - Request Body 
{
    "proposalId": 123,
    "action": "approve",
    "data": {
        "noteTmp": "Đồng ý phê duyệt phần hạn mức bổ sung theo biên bản họp."
    }
}

Request Sample 2: Action reject (Từ chối)

JSON - Request Body 
{
    "proposalId": 123,
    "action": "reject",
    "data": {
        "noteTmp": "Không đồng ý phê duyệt do rủi ro tài chính cao."
    }
}

Request Sample 3: Action need_rework (Yêu cầu làm lại)

JSON - Request Body 
{
    "proposalId": 123,
    "action": "need_rework",
    "data": {
        "noteTmp": "Đề nghị bổ sung thêm tài liệu đánh giá rủi ro."
    }
}

Request Sample 4: Action need_review (Yêu cầu thêm người thẩm định)

JSON - Request Body 
{
    "proposalId": 123,
    "action": "need_review",
    "data": {
        "reviewers": [
            { "email": "reviewer@example.com" }
        ],
        "note": "Nhờ anh xem giúp phần đánh giá rủi ro và các cam kết tài chính.",
        "noteTmp": "Chuyển thẩm định bổ sung trước khi phê duyệt."
    }
}

Request Sample 5: Action need_checker (Yêu cầu thêm người phê duyệt)

JSON - Request Body 
{
    "proposalId": 123,
    "action": "need_checker",
    "data": {
        "checkers": [
            { "email": "checker@example.com" }
        ],
        "note": "Nhờ anh duyệt bổ sung phần hạn mức tín dụng vượt thẩm quyền.",
        "noteTmp": "Trình cấp phê duyệt trung gian."
    }
}

Request Sample 6: Action reviewed (Đã thẩm định xong)

JSON - Request Body 
{
    "proposalId": 123,
    "action": "reviewed",
    "data": {
        "noteTmp": "Đã xem xét và đánh giá hồ sơ đầy đủ."
    }
}

Request Sample 7: Action documents_request (Yêu cầu bổ sung hồ sơ)

JSON - Request Body 
{
    "proposalId": 123,
    "action": "documents_request",
    "data": {
        "noteTmp": "Bổ sung thêm bản sao kê tài khoản ngân hàng."
    }
}

Request Sample 8: Action delegate_approver (Ủy quyền bước phê duyệt)

JSON - Request Body 
{
    "proposalId": 123,
    "action": "delegate_approver",
    "data": {
        "delegatedApprover": {
            "email": "delegate@example.com"
        },
        "validTo": "2026-12-31T23:59:59+07:00",
        "noteTmp": "Đồng ý ủy quyền xử lý bước phê duyệt hiện tại."
    }
}

Response Sample

JSON - Response 200 OK 
{
    "success": true,
    "code": "200",
    "message": "Phê duyệt bước hiện tại thành công.",
    "data": {
        "proposalId": 123,
        "performedAction": "approve",
        "proposalStatus": "UNDER_APPROVAL",
        "workflowCompleted": false,
        "requesterPermissions": [
            { "permission": "PROPOSAL.CREATE", "granted": true },
            { "permission": "PROPOSAL.APPROVE", "granted": true },
            { "permission": "PROPOSAL.REVIEW", "granted": false }
        ],
        "steps": [ "...danh sách các steps sau khi cập nhật..." ],
        "currentSteps": [ "...danh sách các bước đang chờ xử lý tiếp theo..." ]
    }
}
POST /api/v1/private/proposal-approvals/modify-steps TranCode: PP_PROPOSAL_APPROVALS_MODIFY_STEPS — Chỉnh sửa và lưu danh sách các bước phê duyệt PerPro
Core
Lưu và cập nhật lại toàn bộ danh sách các bước phê duyệt của tờ trình. Hỗ trợ tạo mới, cập nhật, đổi thứ tự và xóa mềm (soft-delete) các bước cũ không nằm trong danh sách truyền lên.
Alias Route: POST /api/v1/private/approval-steps/create (Hỗ trợ định dạng response list phẳng cho các component Portal phiên bản cũ).

Quy tắc kiểm tra & Ràng buộc nghiệp vụ

1. Quyền IAM & Người thực hiện (Actor Restriction)
  • Quyền IAM: Bắt buộc có quyền PERMISSION:PROPOSAL:CREATE.
  • Người thực hiện: CHỈ DUY NHẤT NGƯỜI TẠO TỜ TRÌNH (createdBy) mới được phép chỉnh sửa danh sách bước phê duyệt.
2. Ràng buộc danh sách bước (Steps Validation)
  • Tờ trình bắt buộc đang ở trạng thái DRAFT hoặc LOCKED.
  • steps: Bắt buộc là một mảng JSON danh sách, có ít nhất 1 bước (count >= 1).
  • Bước cuối cùng: Bắt buộc phải có stepType = APPROVE.
  • Chống tự duyệt: Người tạo tờ trình (createdBy) KHÔNG ĐƯỢC gán chính mình vào bất kỳ bước nào có stepType = APPROVE. Vi phạm trả lỗi 01 ngay lập tức.
  • Hệ thống sẽ tự động đối soát quyền với IAM và lưu lại thông tin hồ sơ (tên, chức danh, phòng ban, công ty).

Mô tả Payload (Request)

Field Type Description
proposalId Integer Required ID của tờ trình.
steps Array Required Danh sách các bước phê duyệt mới theo đúng thứ tự linked-list. Phải có ít nhất 1 bước.

Request Sample

JSON - Request Body 
{
    "proposalId": 20,
    "steps": [
        {
            "stepId": 113,
            "stepType": "REVIEW",
            "assignee": {
                "email": "reviewer@example.com"
            },
            "note": "Thẩm định hồ sơ ban đầu"
        },
        {
            "stepId": null,
            "stepType": "APPROVE",
            "assignee": {
                "email": "approver@example.com"
            },
            "note": "Phê duyệt tờ trình"
        }
    ]
}

Response Sample

JSON - Response 200 OK 
{
    "success": true,
    "code": "200",
    "message": "Lưu danh sách quy trình phê duyệt thành công.",
    "data": {
        "proposalId": 20,
        "modifiedStepCount": 2,
        "deletedStepCount": 0,
        "proposalStatus": "DRAFT",
        "workflowCompleted": false,
        "requesterPermissions": [
            { "permission": "PROPOSAL.CREATE", "granted": true },
            { "permission": "PROPOSAL.APPROVE", "granted": true },
            { "permission": "PROPOSAL.REVIEW", "granted": false }
        ],
        "steps": [ "...danh sách steps sau khi lưu..." ],
        "currentSteps": []
    }
}
POST /api/v1/private/proposal-approvals/trigger-step-flow TranCode: PP_PROPOSAL_APPROVALS_TRIGGER_STEP_FLOW — Khởi chạy quy trình phê duyệt PerPro (submit, rework-submit, additional_documents_submit)
Core
Khởi chạy quy trình phê duyệt lần đầu (submit), gửi lại tờ trình sau khi đã chỉnh sửa (rework-submit), hoặc gửi thông báo đã bổ sung tài liệu/chứng từ (additional_documents_submit).

Quy tắc kiểm tra theo từng Action

1. Action "submit" (Gửi duyệt lần đầu)
  • Trạng thái tờ trình: Phải là DRAFT.
  • Payload: CẤM truyền field steps trong request.
  • Tất cả các bước phải đang ở DRAFT và chưa có kết quả. Bước cuối cùng bắt buộc là APPROVE.
  • Mở bước đầu tiên thành PROCESSING, các bước sau thành LOCKED; proposal chuyển thành UNDER_APPROVAL (hoặc PENDING_REVIEW nếu bước đầu là Review).
2. Action "rework-submit" (Gửi lại sau khi chỉnh sửa)
  • Trạng thái tờ trình: Phải là REVISION_REQUIRED.
  • Payload: BẮT BUỘC truyền field steps chứa danh sách root steps mới/chỉnh sửa.
  • Hệ thống tự động thu hồi (revoke) các ủy quyền cũ, cập nhật danh sách bước, reset kết quả và khởi chạy lại từ bước đầu tiên.
3. Action "additional_documents_submit" (Gửi bổ sung chứng từ)
  • Trạng thái tờ trình: Phải là PENDING_DOCUMENTS.
  • Tờ trình phải có đúng 1 bước Review đang ở PROCESSING với kết quả REQUEST_DOCUMENTS.
  • Reset kết quả bước review về null (tiếp tục PROCESSING), chuyển tờ trình về PENDING_REVIEW.

Request Sample 1: Action submit (Gửi duyệt lần đầu)

JSON - Request Body 
{
    "proposalId": 123,
    "action": "submit"
}

Request Sample 2: Action rework-submit (Gửi lại sau khi chỉnh sửa)

JSON - Request Body 
{
    "proposalId": 123,
    "action": "rework-submit",
    "steps": [
        {
            "stepId": 1,
            "stepType": "APPROVE",
            "assignee": { "email": "approver1@example.com" },
            "note": "Phê duyệt bước 1"
        },
        {
            "stepId": null,
            "stepType": "APPROVE",
            "assignee": { "email": "approver2@example.com" },
            "note": "Phê duyệt bước 2"
        }
    ]
}

Request Sample 3: Action additional_documents_submit (Gửi bổ sung chứng từ)

JSON - Request Body 
{
    "proposalId": 123,
    "action": "additional_documents_submit"
}

3. Bảng Tra cứu Mã lỗi, Trạng thái & Ma trận Chuyển đổi

TRA CỨU Bảng Mã Lỗi & Trạng Thái Hệ Thống — Danh mục MBGW TranCode, mã lỗi, trạng thái tờ trình, trạng thái bước và ma trận transition
Reference

1. Bảng Tổng hợp Mobile Gateway Transaction Codes (MBGW Mapping)

Danh mục 6 mã giao dịch trên Mobile Gateway ánh xạ tới API PerPro Upstream (cấu hình trong mg_transaction, mg_integration và mg_transaction_component theo migration Version20260825171306.php):

MBGW TranCode (TRANSACTIONS.code) PerPro Upstream Endpoint Tên Transaction & Chức năng nghiệp vụ
PP_PROPOSAL_CHECK_LIST /api/v1/private/proposal-review-inbox/list Lấy danh sách tờ trình phê duyệt/review PerPro
PP_PROPOSAL_APPROVALS_AVAILABLE_ACTIONS /api/v1/private/proposal-approvals/available-actions Lấy quy trình và thao tác phê duyệt khả dụng PerPro
PP_PROPOSAL_APPROVALS_ELIGIBLE_REVIEWERS /api/v1/private/proposal-approvals/eligible-reviewers Lấy danh sách reviewer hợp lệ PerPro
PP_PROPOSAL_APPROVALS_PERFORM_ACTION /api/v1/private/proposal-approvals/perform-action Thực hiện thao tác phê duyệt/review PerPro
PP_PROPOSAL_APPROVALS_MODIFY_STEPS /api/v1/private/proposal-approvals/modify-steps Chỉnh sửa các bước phê duyệt PerPro
PP_PROPOSAL_APPROVALS_TRIGGER_STEP_FLOW /api/v1/private/proposal-approvals/trigger-step-flow Khởi chạy quy trình phê duyệt PerPro

2. Bảng Mã lỗi phản hồi (Error Codes)

Mọi lỗi phát sinh sau khi request vào Controller đều trả HTTP Status 200 kèm mã lỗi tương ứng trong response envelope code để Client dễ dàng xử lý:

Mã lỗi (Code) Tên lỗi Mô tả chi tiết & Trường hợp xảy ra
01 Creator Cannot Approve Người tạo tờ trình vi phạm quy tắc chống tự phê duyệt (cố tình thực hiện duyệt, gán mình làm người duyệt hoặc nhận ủy quyền).
400 Bad Request Payload JSON không hợp lệ, thiếu trường bắt buộc, sai định dạng email/validTo, sai kiểu dữ liệu, hoặc assignee không có quyền IAM tương ứng.
401 Unauthorized Phiên đăng nhập không hợp lệ, thiếu Bearer Token hoặc token đã hết hạn.
403 Forbidden Người dùng không có quyền truy cập tờ trình, không phải người tạo tờ trình khi modify/submit, không được giao xử lý bước hiện tại, hoặc cấu hình ủy quyền trong danh bạ đã bị xóa/thu hồi.
404 Not Found Không tìm thấy tờ trình (Proposal ID không tồn tại hoặc đã bị soft-delete).
409 Conflict Xung đột trạng thái: Bước phê duyệt đã bị người khác xử lý trước đó, trạng thái tờ trình không phù hợp với hành động, user được giao nhiều hơn 1 bước processing, hoặc vi phạm tính liên tục của linked-list.
503 Service Unavailable Dịch vụ IAM tạm thời không khả dụng khi xác thực quyền của assignee/reviewer/checker.
99 System Error Lỗi hệ thống không xác định trong quá trình xử lý.

3. Bảng Ma trận Chuyển đổi Trạng thái khi thực hiện Action (State Transitions)

Action Step Type Trạng thái trước Hành vi & Kết quả sau khi thực hiện
approve APPROVE UNDER_APPROVAL Append note nếu có noteTmp; Current step thành PROCESSED/APPROVED. Mở bước kế tiếp thành PROCESSING, hoặc chuyển proposal thành APPROVED nếu là bước cuối cùng (kết thúc workflow).
reject APPROVE UNDER_APPROVAL Append note nếu có noteTmp; Tất cả các bước chưa xử lý thành PROCESSED/REJECTED; Proposal chuyển sang REJECTED (kết thúc quy trình).
need_rework APPROVE UNDER_APPROVAL Append note nếu có noteTmp; Current step giữ PROCESSING với kết quả result = REWORK; Proposal chuyển sang REVISION_REQUIRED để người tạo sửa lại.
need_review APPROVE UNDER_APPROVAL Append note vào step hiện tại; Chèn 1 root step REVIEW/PROCESSING mới ngay trước step Approve hiện tại; Step Approve chuyển sang LOCKED; Proposal chuyển sang PENDING_REVIEW.
need_checker APPROVE UNDER_APPROVAL Append note vào step hiện tại; Chèn 1 root step APPROVE/PROCESSING mới ngay trước step Approve hiện tại; Step Approve chuyển sang LOCKED; Proposal giữ nguyên UNDER_APPROVAL.
delegate_approver APPROVE UNDER_APPROVAL Append note nếu có noteTmp; Tạo mapping ủy quyền có hiệu lực trong bảng perpro_approval_step_delegated_approver; Giữ nguyên trạng thái step và proposal.
reviewed REVIEW PENDING_REVIEW Append note nếu có noteTmp; Current step thành PROCESSED/REVIEWED; Mở lại bước Approve tiếp theo thành PROCESSING; Proposal chuyển về UNDER_APPROVAL.
documents_request REVIEW PENDING_REVIEW Append note nếu có noteTmp; Current step giữ PROCESSING với kết quả result = REQUEST_DOCUMENTS; Proposal chuyển sang PENDING_DOCUMENTS để người tạo nộp thêm hồ sơ.
submit — DRAFT Kích hoạt bước đầu tiên thành PROCESSING, các bước sau LOCKED; Proposal chuyển sang UNDER_APPROVAL (hoặc PENDING_REVIEW nếu bước 1 là Review).
rework-submit — REVISION_REQUIRED Thu hồi các ủy quyền cũ, cập nhật lại danh sách steps, reset kết quả; Bước 1 chuyển sang PROCESSING; Proposal chuyển sang UNDER_APPROVAL (hoặc PENDING_REVIEW).
additional_documents_submit — PENDING_DOCUMENTS Reset kết quả của bước Review đang request documents về null (tiếp tục PROCESSING); Proposal chuyển về PENDING_REVIEW.
Đã sao chép vào bộ nhớ tạm!