Import lô Hợp đồng lao động
Ngày cập nhật: 18 tháng 8, 2026
Người cập nhật: VNPT eContract's team
Mục đích
Cho phép tạo hàng loạt hợp đồng lao động (kèm chứng từ và cấu hình quy trình ký) trong một lần gọi, dựa trên một mẫu (template) chứng từ có sẵn — phù hợp khi cần import số lượng lớn HĐLĐ thay vì gọi tuần tự các API khởi tạo từng hợp đồng lẻ.
- Request URL:
/api/batch-imports/labor-contracts - HTTP method:
POST - HTTP content-type:
application/json - Authorize:
Bearer token - Parameter (Top-level):
| Key | Type | Bắt buộc | Mô tả |
|---|---|---|---|
departmentId | int | Có | Id phòng/ban phát hành |
documentTemplateId | int | Có | Id mẫu chứng từ (template) dùng để render nội dung hợp đồng |
documentTypeId | int | Có | Id loại chứng từ (ví dụ: 8950 = HĐLĐ) |
name | string | Có | Tên lô import |
laborContracts | array | Có | Danh sách hợp đồng cần import — mỗi phần tử gồm 4 nhóm: contract, employee, workflow, parameters (xem bên dưới) |
Chi tiết cấu trúc đối tượng trong mảng laborContracts:
1. Nhóm contract (Thông tin hợp đồng):
| Key | Type | Bắt buộc | Mô tả |
|---|---|---|---|
no | string | Có | Số hợp đồng lao động |
workingPosition | int | Có | Vị trí công việc theo danh mục hệ thống |
type | int | Có | Loại hợp đồng (2: Xác định thời hạn) |
reportType | int | Không | Hình thức báo cáo (1: Khai báo) |
jobTitle | string | Có | Chức danh công việc |
salary | number | Có | Mức lương |
positionAllowance | number | Không | Phụ cấp chức vụ |
seniorityAllowancePercent | number | Không | Tỷ lệ % phụ cấp thâm niên |
professionalSeniorityPercent | number | Không | Tỷ lệ % phụ cấp thâm niên nghề |
salaryAllowance | number | Không | Phụ cấp lương |
additionalCompensation | number | Không | Khoản bổ sung khác |
hazardousWorkFromDate | string | Không | Thời gian bắt đầu làm công việc nặng nhọc, độc hại, nguy hiểm (định dạng: yyyy-MM-dd) |
hazardousWorkToDate | string | Không | Thời gian kết thúc làm công việc nặng nhọc, độc hại, nguy hiểm (định dạng: yyyy-MM-dd) |
effectiveDate | string | Có | Ngày hợp đồng có hiệu lực (định dạng: yyyy-MM-dd) |
expiredDate | string | Không | Ngày hợp đồng hết hạn (định dạng: yyyy-MM-dd) |
socialInsuranceStartDate | string | Không | Ngày bắt đầu đóng bảo hiểm xã hội (định dạng: yyyy-MM-dd) |
socialInsuranceEndDate | string | Không | Ngày kết thúc đóng bảo hiểm xã hội (định dạng: yyyy-MM-dd) |
note | string | Không | Ghi chú hợp đồng |
signingMethod | int | Có | Hình thức ký (1: HĐLĐ điện tử) |
2. Nhóm employee, workflow, parameters:
| Key | Type | Bắt buộc | Mô tả |
|---|---|---|---|
employee.code | string | Có | Mã người lao động — phải đã được tạo trước bằng API mục 7.1 |
workflow.processInOrder | boolean | Có | Xác định quy trình ký có xử lý tuần tự (true) hay song song (false) |
workflow.templateId | int | Không | Id mẫu quy trình ký có sẵn; null nếu khai báo danh sách người xử lý thủ công bằng recipients |
workflow.recipients[].code | string | Có | Mã người dùng (user) được phân công xử lý chứng từ |
workflow.recipients[].accessPermission | string | Có | Mã quyền xử lý (ví dụ: "DR", "D" — theo danh mục quyền xử lý chứng từ của hệ thống, cần xác nhận đầy đủ danh mục với đội phát triển) |
parameters | object | Có | Object dạng key-value tự do, chứa các biến điền vào mẫu (template) hợp đồng — khớp với placeholder định nghĩa sẵn trong file mẫu (ví dụ: DIACHILV, BOPHAN, ...) |
Request mẫu
{
"departmentId": 9855,
"documentTemplateId": 8132,
"documentTypeId": 8950,
"name": "Import lô HĐLĐ xác định thời hạn HDLD-NVC-20260805062154B",
"laborContracts": [
{
"contract": {
"no": "HDLD-NVC-20260805062154B",
"workingPosition": 2,
"type": 2,
"reportType": 1,
"jobTitle": "Chuyên viên kinh doanh",
"salary": 20000000,
"positionAllowance": 1500000,
"seniorityAllowancePercent": 5,
"professionalSeniorityPercent": 6,
"salaryAllowance": 700000,
"additionalCompensation": 500000,
"hazardousWorkFromDate": null,
"hazardousWorkToDate": null,
"effectiveDate": "2026-02-01",
"expiredDate": "2027-06-24",
"socialInsuranceStartDate": "2026-02-01",
"socialInsuranceEndDate": null,
"note": "Hợp đồng lao động xác định thời hạn 12 tháng",
"signingMethod": 1
},
"employee": {
"code": "NVC20260805062154B"
},
"workflow": {
"processInOrder": true,
"templateId": null,
"recipients": [
{
"code": "BAOTH",
"accessPermission": "DR"
},
{
"code": "TRINHTTV",
"accessPermission": "D"
}
]
},
"parameters": {
"DIACHILV": "Tầng 10 toà nhà VNPT, Hà Nội",
"BOPHAN": "Nhân Sự",
"GIOLAMVIEC": "08:00-17:00 từ Thứ 2 đến Thứ 6",
"DVTIEN": "VND",
"NGAYCAP_CCCD": "2019-08-20",
"NOICAP_CCCD": "Công an TP Hà Nội",
"HKTT": "123 Phố Huế, Hai Bà Trưng, Hà Nội"
}
}
]
}
Response mẫu — HTTP 200
{
"data": {
"id": 22945,
"createdDate": "2026-08-05T13:21:56.0319878+07:00",
"uploadedByUserId": 27938,
"numberOfRecords": 1,
"name": "Import lô HĐLĐ xác định thời hạn HDLD-NVC-20260805062154B",
"status": {
"value": 1,
"description": "Processing"
},
"documents": [],
"errors": [],
"importType": {
"value": 3,
"description": "Labor contracts created from templates"
}
},
"success": true,
"code": 200,
"messages": [
"Create labor contract batch import successfully"
]
}
thông tin
Lưu ý: data.id chính là BatchImportId — cần lưu lại để sử dụng cho API Gửi quy trình lô chứng từ import (mục 7.5), hoặc để tra cứu trạng thái xử lý của lô. Trạng thái status trả về "Processing" (Đang xử lý) và documents rỗng tại thời điểm phản hồi do việc tạo hợp đồng/chứng từ trong lô được hệ thống xử lý bất đồng bộ (asynchronous) ở phía sau.
Response Parameter
| Key | Type | Description |
|---|---|---|
data | object | Thông tin chi tiết của lô import vừa được tạo (xem chi tiết bên dưới) |
success | boolean | Trạng thái xử lý yêu cầu (true: Thành công, false: Thất bại) |
code | int | Mã trạng thái phản hồi (200: Thành công) |
messages | array | Danh sách thông báo kết quả xử lý từ hệ thống |
Chi tiết đối tượng data trong Response:
| Key | Type | Description |
|---|---|---|
id | int | ID lô import (BatchImportId) — dùng làm tham số cho API mục 7.5 |
createdDate | string | Thời gian khởi tạo lô (định dạng ISO 8601) |
uploadedByUserId | int | ID người dùng thực hiện tải lên lô import |
numberOfRecords | int | Tổng số bản ghi hợp đồng trong lô import |
name | string | Tên lô import |
status | object | Trạng thái xử lý lô (1: Processing — Đang xử lý bất đồng bộ) |
documents | array | Danh sách các chứng từ tạo thành công (rỗng khi mới khởi tạo) |
errors | array | Danh sách thông báo lỗi phát sinh trong quá trình xử lý (nếu có) |
importType | object | Loai import (3: Labor contracts created from templates — Tạo HĐLĐ từ template mẫu) |
Các lỗi thường gặp (Batch Import)
success | messages | Ý nghĩa |
|---|---|---|
false | "Document number 'doc_no' already exists" | Số/mã chứng từ doc_no đã tồn tại trên hệ thống. Cần thay đổi số chứng từ khác trong file import. |
false | "Employee code 'empl_code' already has a labor contract that is not terminated" | Mã nhân viên empl_code đã có hợp đồng lao động đang hiệu lực (chưa chấm dứt). Cần kiểm tra lại thông tin hợp đồng. |