Phiên bản: 2.3.0

Tạo mới hoặc cập nhật Hợp đồng lao động (HĐLĐ)

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

Mục đích

Khởi tạo (hoặc cập nhật) một hợp đồng lao động gắn với người lao động đã tồn tại trong hệ thống (xác định qua EmployeeCode, tạo ở API mục 7.1). API trả về LaborContractId (dạng GUID) — giá trị này cần được lưu lại để sử dụng làm đầu vào cho API Tạo chứng từ cho HĐLĐ (mục 7.3).

Request URL: /api/labor-contracts/create-or-update
HTTP method: POST
HTTP content-type: application/json
Authorize: Bearer token
Parameter:

Key	Type	Bắt buộc	Mô tả
`EmployeeCode`	string	Có	Mã NLĐ đã được tạo ở API mục 7.1
`ContractNumber`	string	Có	Số hợp đồng lao động
`JobTitle`	string	Có	Chức danh công việc
`Salary`	number	Có	Mức lương
`WorkingPosition`	int	Có	Vị trí công việc theo danh mục hệ thống
`ContractType`	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)
`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
`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`)
`Note`	string	Không	Ghi chú hợp đồng
`SigningMethod`	int	Có	Hình thức ký (1: HĐLĐ điện tử)
`File`	string	Không	Đường dẫn/tên file mẫu hợp đồng dùng để render nội dung hợp đồng

cẩn thận

Lưu ý: Trong dữ liệu test, trường File truyền theo đường dẫn file cục bộ (local path) trên máy thực hiện test. Khi tích hợp thực tế, đối tác cần xác nhận với đội phát triển hệ thống về cơ chế truyền file hợp đồng chính thức (ví dụ: upload trước qua API tải file, hoặc tham chiếu tới mẫu hợp đồng có sẵn trên hệ thống).

Request mẫu

{
  "EmployeeCode": "NVC20260805062149",
  "ContractNumber": "HDLD-NVC-20260805062149",
  "JobTitle": "Chuyên viên kinh doanh",
  "Salary": 20000000,
  "WorkingPosition": 2,
  "ContractType": 2,
  "ReportType": 1,
  "PositionAllowance": 1000000,
  "SeniorityAllowancePercent": 0,
  "ProfessionalSeniorityPercent": 0,
  "SalaryAllowance": 500000,
  "AdditionalCompensation": 500000,
  "EffectiveDate": "2026-06-24",
  "ExpiredDate": "2027-06-24",
  "Note": "Hợp đồng lao động xác định thời hạn 12 tháng",
  "SigningMethod": 1,
  "File": "D:\\...\\Hop-dong-lao-dong-xac-dinh-thoi-han.pdf"
}

Response mẫu — HTTP 200

{
  "data": {
    "id": "969bfc9a-570f-4d4e-a98b-42361a73f7e8",
    "createdDate": "2026-08-05T13:21:53.7572904+07:00",
    "employee": {
      "id": 1430,
      "createdDate": "2026-08-05T13:21:52.8949042",
      "userId": 70427,
      "employeeCode": "NVC20260805062149",
      "fullName": "Nguyễn Văn Cường 2149",
      "dateOfBirth": "1997-02-17T00:00:00",
      "gender": 1,
      "identityNumber": "909218625041",
      "email": "nguyenvancuong20260805062149@example.com",
      "phoneNumber": "091****109",
      "socialInsuranceCode": "BH178591090921862504",
      "status": {
        "value": 1,
        "description": "Enabled"
      },
      "currentWorkingPosition": 1,
      "currentJobTitle": "Chuyên viên kinh doanh",
      "currentSalary": 20000000,
      "currentSalaryAllowance": 4,
      "currentContractType": 2,
      "currentReportType": 1,
      "currentContractEffectiveDate": "2026-01-15T00:00:00",
      "currentContractNote": "Hợp đồng lao động xác định thời hạn tạo qua API",
      "currentContractSigningMethod": {
        "value": 1,
        "description": "Electronic Labor Contract"
      },
      "syncStatus": {
        "value": 1,
        "description": "Not Synced"
      },
      "currentContractNumber": "HDLD-NVC-20260805062149"
    },
    "employeeFullName": "Nguyễn Văn Cường 2149",
    "contractNumber": "HDLD-NVC-20260805062149",
    "contractName": "Employment contract Nguyễn Văn Cường 2149",
    "status": {
      "value": 0,
      "description": "Draft"
    },
    "currentRevisionId": "7a2d74b5-140f-4893-8b4b-fc409077e289",
    "currentRevision": {
      "id": "7a2d74b5-140f-4893-8b4b-fc409077e289",
      "createdDate": "2026-08-05T13:21:53.7994921+07:00",
      "laborContractId": "969bfc9a-570f-4d4e-a98b-42361a73f7e8",
      "version": 1,
      "status": {
        "value": 0,
        "description": "Draft"
      },
      "actionType": {
        "value": 0,
        "description": "Initialization"
      },
      "currentLaborContractRenderId": "576b48e7-5472-4278-9168-11e23b7bec45",
      "employeeFullName": "Nguyễn Văn Cường 2149",
      "employeeDateOfBirth": "1997-02-17T00:00:00",
      "employeeGender": {
        "value": 1,
        "description": "Male"
      },
      "employeeIdentityNumber": "909218625041",
      "employeeSocialInsuranceNumber": "BH178591090921862504",
      "employeeEmail": "nguyenvancuong20260805062149@example.com",
      "employeePhoneNumber": "091****109",
      "contractNumber": "HDLD-NVC-20260805062149",
      "contractName": "Employment contract Nguyễn Văn Cường 2149",
      "contractType": {
        "value": 2,
        "description": "Fixed-term"
      },
      "jobTitle": "Chuyên viên kinh doanh",
      "workingPosition": {
        "value": 2,
        "description": "High-level Technical Specialist"
      },
      "salary": 20000000,
      "positionAllowance": 1000000,
      "seniorityAllowancePercent": 0,
      "professionalSeniorityPercent": 0,
      "salaryAllowance": 500000,
      "additionalCompensation": 500000,
      "effectiveDate": "2026-06-24T00:00:00",
      "expiredDate": "2027-06-24T00:00:00",
      "signingMethod": {
        "value": 1,
        "description": "Electronic Labor Contract"
      },
      "reportType": {
        "value": 1,
        "description": "Declaration"
      },
      "syncStatus": {
        "value": 1,
        "description": "Not Synced"
      },
      "downloadUrl": "{HOST}/Api/Download?token=...",
      "contractFile": {
        "fileName": "Hop-dong-lao-dong-xac-dinh-thoi-han.pdf",
        "fileSize": 358043
      }
    },
    "totalDocumentCount": 0
  },
  "success": true,
  "code": 0,
  "messages": [
    "Create labor contract success"
  ]
}

thông tin

Lưu ý: data.id chính là LaborContractId — cần lưu lại để sử dụng cho Tạo chứng từ cho HĐLĐ (mục 7.3). Hợp đồng vừa tạo có status = "Draft" (Nháp) cho đến khi chứng từ tương ứng được tạo và gửi quy trình ký.

Response Parameter

Key	Type	Description
`data`	object	Thông tin chi tiết Hợp đồng lao động vừa được khởi tạo/cập nhật (xem 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
`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`	string	ID hợp đồng lao động (GUID) — dùng làm `LaborContractId` cho bước tiếp theo
`createdDate`	string	Thời gian tạo hợp đồng (định dạng ISO 8601)
`employee`	object	Chi tiết thông tin người lao động liên kết (xem bên dưới)
`employeeFullName`	string	Họ và tên người lao động
`contractNumber`	string	Số hợp đồng lao động
`contractName`	string	Tên hợp đồng lao động
`status`	object	Trạng thái hợp đồng 0 Draft (Bản nháp) 1 Pending Signature (Chờ ký) 2 Signing (Đang ký) 3 Signed (Đã ký) 4 Effective (Đang hiệu lực) 5 Expired (Đã hết hạn) 6 Terminated (Đã chấm dứt) 7 Cancelled (Đã hủy) 8 Rejected (Bị từ chối) 9 Correcting (Đang chỉnh sửa)
`currentRevisionId`	string	GUID phiên bản hợp đồng hiện tại
`currentRevision`	object	Chi tiết thông tin phiên bản hợp đồng (xem bên dưới)
`totalDocumentCount`	int	Tổng số chứng từ liên quan đã tạo

Chi tiết đối tượng `employee` trong Response:

Key	Type	Description
`id`	int	ID người lao động
`createdDate`	string	Thời gian tạo bản ghi (định dạng ISO 8601)
`userId`	int	ID tài khoản người dùng liên kết
`employeeCode`	string	Mã người lao động
`fullName`	string	Họ và tên người lao động
`dateOfBirth`	string	Ngày sinh (định dạng ISO 8601)
`gender`	int	Giới tính (1: Nam, 2: Nữ)
`identityNumber`	string	Số CCCD/CMND
`email`	string	Địa chỉ email người lao động
`phoneNumber`	string	Số điện thoại
`socialInsuranceCode`	string	Mã số bảo hiểm xã hội
`status`	object	Trạng thái người lao động (1: Enabled)
`currentWorkingPosition`	int	Vị trí công việc hiện tại
`currentJobTitle`	string	Chức danh công việc hiện tại
`currentSalary`	number	Mức lương hiện tại
`currentSalaryAllowance`	number	Phụ cấp lương hiện tại
`currentContractType`	int	Loại hợp đồng hiện tại (2: Xác định thời hạn)
`currentReportType`	int	Hình thức báo cáo hợp đồng
`currentContractEffectiveDate`	string	Ngày hiệu lực hợp đồng hiện tại (định dạng ISO 8601)
`currentContractNote`	string	Ghi chú hợp đồng hiện tại
`currentContractSigningMethod`	object	Hình thức ký hợp đồng 1: Electronic Labor Contract
`syncStatus`	object	Trạng thái đồng bộ 1: Not Synced
`currentContractNumber`	string	Số hợp đồng hiện tại

Chi tiết đối tượng `currentRevision` trong Response:

Key	Type	Description
`id`	string	GUID phiên bản
`createdDate`	string	Thời gian tạo phiên bản (định dạng ISO 8601)
`laborContractId`	string	GUID hợp đồng lao động
`version`	int	Số phiên bản hợp đồng
`status`	object	Trạng thái phiên bản 0 Draft (Bản nháp) 1 Pending Signature (Chờ ký) 2 Signing (Đang ký) 3 Signed (Đã ký) 4 Effective (Đang hiệu lực) 5 Expired (Đã hết hạn) 6 Terminated (Đã chấm dứt) 7 Cancelled (Đã hủy) 8 Rejected (Bị từ chối) 9 Correcting (Đang chỉnh sửa)
`actionType`	object	Loại hành động: `{"value": int, "description": string}` 0 Initialization (Khởi tạo) 1 Salary Adjustment (Điều chỉnh lương) 2 Renew Contract (Gia hạn hợp đồng) 3 Terminate Contract (Chấm dứt hợp đồng) 4 Change Position (Thay đổi vị trí công việc) 5 Update Social Insurance Information (Cập nhật thông tin bảo hiểm xã hội) 20 Recreate (Tạo lại)
`currentLaborContractRenderId`	string	GUID bản ghi render hợp đồng
`employeeFullName`	string	Họ tên người lao động
`employeeDateOfBirth`	string	Ngày sinh NLĐ (định dạng ISO 8601)
`employeeGender`	object	Giới tính (1: Male)
`employeeIdentityNumber`	string	Số CCCD/CMND
`employeeSocialInsuranceNumber`	string	Mã số BHXH
`employeeEmail`	string	Email người lao động
`employeePhoneNumber`	string	Số điện thoại
`contractNumber`	string	Số hợp đồng
`contractName`	string	Tên hợp đồng
`contractType`	object	Loại hợp đồng 2: Fixed-term
`jobTitle`	string	Chức danh công việc
`workingPosition`	object	Vị trí công việc 2: High-level Technical Specialist
`salary`	number	Mức lương
`positionAllowance`	number	Phụ cấp chức vụ
`seniorityAllowancePercent`	number	Tỷ lệ % phụ cấp thâm niên
`professionalSeniorityPercent`	number	Tỷ lệ % phụ cấp thâm niên nghề
`salaryAllowance`	number	Phụ cấp lương
`additionalCompensation`	number	Khoản bổ sung khác
`effectiveDate`	string	Ngày hiệu lực (định dạng ISO 8601)
`expiredDate`	string	Ngày hết hạn (định dạng ISO 8601)
`signingMethod`	object	Hình thức ký 1: Electronic Labor Contract
`reportType`	object	Hình thức báo cáo 1: Declaration
`syncStatus`	object	Trạng thái đồng bộ 1: Not Synced
`downloadUrl`	string	Đường dẫn tải xuống file hợp đồng nháp
`contractFile`	object	Thông tin file hợp đồng (`fileName`, `fileSize`)

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

`success`	`code`	`messages`	Ý nghĩa
`false`	`0`	`"Cannot create a new labor contract because the employee already has a labor contract that has not been terminated"`	Nhân viên này đã có hợp đồng lao động đang hiệu lực (chưa thanh lý/chấm dứt). Cần truyền thêm `Id` hợp đồng để thực hiện cập nhật.
`false`	`0`	`"Employee of an existing labor contract cannot be changed"`	Không thể thay đổi thông tin nhân viên của một hợp đồng lao động đã tồn tại.
`false`	`0`	`"Document number 'TEST.2026.001' has been used."`	Số/mã chứng từ này đã được sử dụng trên hệ thống. Cần nhập số chứng từ khác.

Mục đích​

Request mẫu​

Response mẫu — HTTP 200​

Response Parameter​

Chi tiết đối tượng data trong Response:​

Chi tiết đối tượng employee trong Response:​

Chi tiết đối tượng currentRevision trong Response:​

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